StreamUserListController

docusaurus/docs/Flutter/stream_chat_flutter_core/stream_channel_list_controller.mdx

@@ -80,7 +80,12 @@ Widget build(BuildContext context) => Scaffold(
                 itemBuilder: (BuildContext context, int index) {
                   if (index == channels.length) {
                     if (error != null) {
-                      return Text(error.message);
+                      return TextButton(
+                          onPressed: () {
+                            channelListController.retry();
+                          },
+                          child: Text(error.message),
+                        );
                     }
                     return CircularProgressIndicator();
                   }

docusaurus/docs/Flutter/stream_chat_flutter_core/stream_user_list_controller.mdx

@@ -0,0 +1,110 @@
+---
+id: stream_user_list_controller
+sidebar_position: 5
+title: StreamUserListController
+---
+
+A Widget For Controlling A List Of Users
+
+### Background
+
+The `StreamUserListController` is a controller class that allows you to control a list of users.
+`StreamUserListController` is a required parameter of the `StreamUserListView` widget.
+Check the [`StreamUserListView` documentation](../stream_chat_flutter/stream_user_list_view.mdx) to read more about that.
+
+### Basic Example
+
+Building a custom user list is a very common task. Here is an example of how to use the `StreamUserListController` to build a simple list with pagination.
+
+First of all we should create an instance of the `StreamUserListController` and provide it with the `StreamChatClient` instance.
+You can also add a `Filter`, a list of `SortOption`s and other pagination-related parameters.
+
+```dart
+class UserListPageState extends State<HomeScreen> {
+  /// Controller used for loading more data and controlling pagination in
+  /// [StreamUserListController].
+  late final userListController = StreamUserListController(
+    client: StreamChatCore.of(context).client,
+  );
+```
+
+Make sure you call `userListController.doInitialLoad()` to load the initial data and `userListController.dispose()` when the controller is no longer required.
+
+```dart
+@override
+void initState() {
+  userListController.doInitialLoad();
+  super.initState();
+}
+
+@override
+void dispose() {
+  userListController.dispose();
+  super.dispose();
+}
+```
+
+The `StreamUserListController` is basically a [`PagedValueNotifier`](./paged_value_notifier.mdx) that notifies you when the list of users has changed.
+You can use a [`PagedValueListenableBuilder`](./paged_value_listenable_builder.mdx) to build your UI depending on the latest users.
+
+```dart
+@override
+Widget build(BuildContext context) => Scaffold(
+      body: PagedValueListenableBuilder<int, Channel>(
+        valueListenable: userListController,
+        builder: (context, value, child) {
+          return value.when(
+            (users, nextPageKey, error) => LazyLoadScrollView(
+              onEndOfPage: () async {
+                if (nextPageKey != null) {
+                  userListController.loadMore(nextPageKey);
+                }
+              },
+              child: ListView.builder(
+                /// We're using the users length when there are no more
+                /// pages to load and there are no errors with pagination.
+                /// In case we need to show a loading indicator or and error
+                /// tile we're increasing the count by 1.
+                itemCount: (nextPageKey != null || error != null)
+                    ? users.length + 1
+                    : users.length,
+                itemBuilder: (BuildContext context, int index) {
+                  if (index == users.length) {
+                    if (error != null) {
+                      return TextButton(
+                          onPressed: () {
+                            userListController.retry();
+                          },
+                          child: Text(error.message),
+                        );
+                    }
+                    return CircularProgressIndicator();
+                  }
+
+                  final _item = users[index];
+                  return ListTile(
+                    title: Text(_item.name ?? ''),
+                  );
+                },
+              ),
+            ),
+            loading: () => const Center(
+              child: SizedBox(
+                height: 100,
+                width: 100,
+                child: CircularProgressIndicator(),
+              ),
+            ),
+            error: (e) => Center(
+              child: Text(
+                'Oh no, something went wrong. '
+                'Please check your config. $e',
+              ),
+            ),
+          );
+        },
+      ),
+    );
+```
+
+In this case we're using the [`LazyLoadScrollView`](./lazy_load_scroll_view.mdx) widget to load more data when the user scrolls to the bottom of the list.

packages/stream_chat_flutter_core/example/lib/main.dart

@@ -127,7 +127,12 @@ class _HomeScreenState extends State<HomeScreen> {
                   itemBuilder: (BuildContext context, int index) {
                     if (index == channels.length) {
                       if (error != null) {
-                        return Text(error.message);
+                        return TextButton(
+                          onPressed: () {
+                            channelListController.retry();
+                          },
+                          child: Text(error.message),
+                        );
                       }
                       return CircularProgressIndicator();
                     }