StreamChannelListHeader

StreamChannelListHeader is a ready-made app bar for the channel list screen. It displays the current user's avatar, a customizable title, an optional subtitle, and a trailing slot for any actions you want to add. See the pub.dev documentation for the full API reference.

Background

A common pattern for most messaging apps is to show a list of channels on the first screen and navigate to an individual one on tap. StreamChannelListHeader encapsulates the standard chrome for this screen: a leading user avatar, a title area (with built-in connection-state awareness), and a trailing slot where you wire up any actions your app needs, such as starting a new conversation.

Basic Example

This is a basic example of a page which has a StreamChannelListView and a StreamChannelListHeader to recreate a common Channels Page.

class ChannelListPage extends StatefulWidget {
  const ChannelListPage({
    super.key,
    required this.client,
  });

  final StreamChatClient client;

  @override
  State<ChannelListPage> createState() => _ChannelListPageState();
}

class _ChannelListPageState extends State<ChannelListPage> {
  late final _controller = StreamChannelListController(
    client: widget.client,
    filter: Filter.in_(
      'members',
      [StreamChat.of(context).currentUser!.id],
    ),
    channelStateSort: const [SortOption<ChannelState>.desc('last_message_at')],
  );

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => Scaffold(
        appBar: const StreamChannelListHeader(),
        body: RefreshIndicator(
          onRefresh: _controller.refresh,
          child: StreamChannelListView(
            controller: _controller,
            onChannelTap: (channel) => Navigator.push(
              context,
              MaterialPageRoute(
                builder: (_) => StreamChannel(
                  channel: channel,
                  child: const ChannelPage(),
                ),
              ),
            ),
          ),
        ),
      );
}

Customizing Parts Of The Header

Use the title, subtitle, or trailing parameters to substitute the widgets for your own.

StreamChannelListHeader(
    subtitle: const Text('My Custom Subtitle'),
),

By default, StreamChannelListHeader already wraps the title in a StreamConnectionStatusBuilder that shows a connecting or offline indicator when the WebSocket is not fully connected. If you want to override the title with your own connection-aware widget, pass a StreamConnectionStatusBuilder to the title parameter:

StreamChannelListHeader(
    title: StreamConnectionStatusBuilder(
        statusBuilder: (context, status) {
            return switch (status) {
                ConnectionStatus.connected => const Text('My Chat App'),
                ConnectionStatus.connecting => const Text('Connecting...'),
                ConnectionStatus.disconnected => const Text('Offline'),
            };
        },
    ),
),

Showing Connection State

The StreamChannelListHeader can also display connection state below the tile which shows the user if they are connected or offline, etc. on connection events.

To enable this, use the showConnectionStateTile property.

StreamChannelListHeader(
    showConnectionStateTile: true,
),

StreamChannelListView

StreamThreadListView