# StreamUserListController

A Widget For Controlling A List Of Users

Find the pub.dev documentation [here](https://pub.dev/documentation/stream_chat_flutter_core/latest/stream_chat_flutter_core/StreamUserListController-class.html)

### 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](/chat/docs/sdk/flutter/v5/stream-chat-flutter/stream-user-list-view/) 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<UserListPage> {
  /// 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`](/chat/docs/sdk/flutter/v5/stream-chat-flutter-core/paged-value-listenable-builder/) that notifies you when the list of users has changed.
You can use a [`PagedValueListenableBuilder`](/chat/docs/sdk/flutter/v5/stream-chat-flutter-core/paged-value-listenable-builder/) to build your UI depending on the latest users.

```dart
@override
Widget build(BuildContext context) => Scaffold(
      body: PagedValueListenableBuilder<int, User>(
        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 const 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`](/chat/docs/sdk/flutter/v5/stream-chat-flutter-core/lazy-load-scroll-view/) widget to load more data when the user scrolls to the bottom of the list.


---

This page was last updated at 2026-05-22T16:31:58.682Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/flutter/v5/stream-chat-flutter-core/stream-user-list-controller/](https://getstream.io/chat/docs/sdk/flutter/v5/stream-chat-flutter-core/stream-user-list-controller/).