Skip to main content

Channel Page Config

ChannelPage accepts ChannelConfig for channel-list styling and built-in behavior. The config is intentionally narrow: it controls the built-in app bar, list loading, channel item presentation, long-press menu, and swipe action style. Page-level interactions such as routing, analytics, and custom action handling are supplied through ChannelPage callbacks.

Entry Point​

Dart
ChannelPage(
  config: ChannelConfig(
    appBarConfig: ChannelAppBarConfig(title: 'Messages'),
    listConfig: ChannelListConfig(showSearchBar: true),
    itemConfig: ChannelItemConfig(showReadStatus: true),
  ),
)

ChannelConfig​

ChannelConfig contains five sections:

  • appBarConfig: built-in page app bar.
  • listConfig: list behavior, paging, filters, and background.
  • itemConfig: built-in row visibility, colors, text styles, avatar behavior, and item-level builders.
  • profileProvider: shared lightweight profile resolver for built-in channel rows and the default ChatPage opened from the channel list.
  • longPressMenuConfig: built-in long-press menu style.

When a channel item is tapped, the page resolves navigation in this order:

PriorityAPIBehavior
1ChannelPage.onItemTapFull host-app ownership of the tap. Use this for custom routing, analytics, or permission checks.
2ChannelPage.chatPageOpenerUses a custom opener while keeping the built-in item tap flow.
3ChannelListConfig.itemTapBehavioropenChatPage opens ChatPage; none disables built-in navigation.

Use onChannelAction for pin, mute, and delete confirmation flows. Use ChannelConfig for how those actions are shown.

ChannelAppBarConfig​

Fields:

  • height: app bar height.
  • title: title text.
  • centerTitle: whether the title is centered.
  • backgroundColor: app bar background color.
  • titleTextStyle: title style.
  • titleSpacing: title spacing passed to the app bar.
  • actions: trailing widgets.

Example:

Dart
ChannelPage(
  config: const ChannelConfig(
    appBarConfig: ChannelAppBarConfig(
      title: 'Messages',
      centerTitle: true,
      backgroundColor: Colors.white,
    ),
  ),
)

ChannelListConfig​

Fields:

  • showSearchBar: shows the built-in search row.
  • showNetworkStatusTip: shows the built-in network status tip when needed.
  • emptyText: fallback empty-state text.
  • backgroundColor: list background color.
  • channelTypes: channel types used by the default ChannelProvider.
  • pageSize: page size for ChannelsQuery; valid range is 1...50.
  • itemTapBehavior: ChannelItemTapBehavior.openChatPage opens ChatPage; ChannelItemTapBehavior.none leaves the tap to your callbacks.

Example:

Dart
ChannelPage(
  config: const ChannelConfig(
    listConfig: ChannelListConfig(
      showSearchBar: true,
      pageSize: 30,
      channelTypes: [ChannelType.direct, ChannelType.group],
      itemTapBehavior: ChannelItemTapBehavior.openChatPage,
    ),
  ),
)

ChannelItemConfig​

Visibility fields:

  • showUnreadBadge
  • showLastMessage
  • showTime
  • showPinnedIndicator
  • showDirectChannelOnlineStatus
  • showReadStatus
  • showNotificationLevelIndicator

Avatar and profile fields:

  • avatarRadius
  • avatarShape: ChannelAvatarShape.circle, roundedRectangle, or rectangle.
  • useDefaultAvatarAsset
  • displayProfileResolver
  • displayProfiles
  • directChannelAvatarAssetName
  • groupChannelAvatarAssetName
  • systemChannelAvatarAssetName

ChannelConfig.profileProvider can be used when the same app-owned profile source should drive both the channel list row and the default chat page. Channel row priority is:

  1. ChannelItemConfig.displayProfiles
  2. ChannelItemConfig.displayProfileResolver
  3. ChannelConfig.profileProvider
  4. Built-in fallback display

When ChannelPage opens the default ChatPage, ChannelConfig.profileProvider is passed through to ChatPageConfig.profileProvider and is also used as a fallback for the default chat title. If you provide a custom chatPageOpener or onItemTap, your app owns the target page configuration.

Style fields:

  • titleStyle
  • lastMessageStyle
  • timeStyle
  • dividerColor
  • dividerIndent
  • dividerEndIndent
  • dividerHeight
  • backgroundColor
  • pinnedBackgroundColor
  • longPressBackgroundColor

Callback and builder fields:

  • onlineStatusProvider
  • onlineStatusBuilder
  • readStatusBuilder
  • notificationLevelBuilder
  • avatarBuilder
  • titleBuilder
  • lastMessageBuilder
  • timeBuilder
  • unreadBadgeBuilder

Swipe actions:

  • swipeActionsConfig: a ChannelSwipeActionsConfig value for built-in row actions.

Example:

Dart
ChannelPage(
  config: ChannelConfig(
    profileProvider: (channel, {message}) async {
      final userId = message?.senderUserId ?? channel.channelId;
      final profile = await accountRepository.loadUser(userId);
      return ChatProfileInfo(
        id: userId,
        name: profile?.displayName,
        portraitUri: profile?.avatarUrl,
      );
    },
    itemConfig: ChannelItemConfig(
      showDirectChannelOnlineStatus: true,
      showReadStatus: true,
      avatarShape: ChannelAvatarShape.circle,
      titleStyle: const TextStyle(fontWeight: FontWeight.w600),
      displayProfileResolver: (context, channel) async {
        return const ChannelDisplayProfile(displayName: 'Support');
      },
    ),
  ),
)

ChannelSwipeActionsConfig​

Fields:

  • enabled: enables or disables built-in swipe actions.
  • actionWidth: width for each action.
  • revealThreshold: drag threshold from 0 to 1.
  • actions: ordered ChannelActionType values.
  • labels: labels by action type.
  • icons: icons by action type.
  • backgroundColors: background colors by action type.
  • foregroundColor: icon and label color.

Example:

Dart
ChannelItemConfig(
  swipeActionsConfig: ChannelSwipeActionsConfig(
    actions: [ChannelActionType.mute, ChannelActionType.delete],
    labels: {
      ChannelActionType.mute: 'Mute',
      ChannelActionType.delete: 'Remove',
    },
  ),
)

ChannelLongPressMenuConfig​

Fields:

  • backgroundColor
  • shape
  • width
  • iconSize
  • iconColor
  • padding
  • itemHeight
  • itemPadding
  • itemMargin
  • actionTextStyle
  • destructiveTextStyle
  • cancelText
  • showCancel

Example:

Dart
ChannelPage(
  config: const ChannelConfig(
    longPressMenuConfig: ChannelLongPressMenuConfig(
      width: 180,
      showCancel: true,
    ),
  ),
)

Use page-level builders when the built-in row structure is not enough. See Channel page builders.

Last updated on