Message Header - CometChat Docs

AI Integration Quick Reference

Field	Value
Component	`CometChatMessageHeader`
Package	`cometchat_chat_uikit`
Import	`import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';`
Purpose	Configure CometChat Flutter UI Kit Message Header with user or group details, presence, typing indicators, navigation, and actions.
Data props	`group` · `user`
Actions	`onBack` · `onHeaderTap` · `onInfoTap` · `onSearchTap` · `onPinnedMessagesTap` · `onPinnedMessageItemTap` · `chatHistoryButtonClick` · `newChatButtonClick` — details
View slots	`backButton` · `trailingView` · `listItemView` · `subtitleView` · `titleView` · `leadingStateView` · `auxiliaryButtonView` — details
Styling	`messageHeaderStyle` — the app `ThemeData` does not reach inside a kit widget, so scope colours here.
Stitching	Pair with `CometChatMessageList` and `CometChatMessageComposer`, passing the same `user` or `group` to all three.
Prerequisites	`CometChatUIKit` initialised and a user logged in.
Full props	37 props

CometChatMessageHeader renders the header of a chat conversation showing user/group avatar, name, online/offline status, typing indicators, back navigation, and action buttons (call buttons, menu).

Where It Fits

CometChatMessageHeader is a toolbar component. It sits at the top of a chat screen above CometChatMessageList and CometChatMessageComposer. It automatically shows typing indicators and user presence in real-time.

Dart

Scaffold(
  body: Column(
    children: [
      CometChatMessageHeader(user: user),
      Expanded(child: CometChatMessageList(user: user)),
      CometChatMessageComposer(user: user),
    ],
  ),
)

Quick Start

Dart

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
import 'package:flutter/material.dart';

class ChatScreen extends StatelessWidget {
  final User user;
  const ChatScreen({super.key, required this.user});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: PreferredSize(
        preferredSize: const Size.fromHeight(60),
        child: CometChatMessageHeader(user: user),
      ),
      body: Column(
        children: [
          Expanded(child: CometChatMessageList(user: user)),
          CometChatMessageComposer(user: user),
        ],
      ),
    );
  }
}

For group chats, pass a Group object instead:

Dart

CometChatMessageHeader(group: group)

Prerequisites: CometChat SDK initialized with CometChatUIKit.init(), a user logged in, and a valid User or Group object.

Actions and Events

Callback Methods

`onBack`

Fires when the user presses the back button.

Dart

CometChatMessageHeader(
  user: user,
  onBack: () {
    Navigator.pop(context);
  },
)

`onError`

SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

SDK Listener	Internal behavior
`onUserOnline` / `onUserOffline`	Updates online/offline status and last seen
`onTypingStarted` / `onTypingEnded`	Shows/hides typing indicator in subtitle
`onGroupMemberJoined` / `onGroupMemberLeft`	Updates group member count
`onGroupMemberKicked` / `onGroupMemberBanned`	Updates group member count
`onMemberAddedToGroup`	Updates group member count
`ccOwnershipChanged`	Updates group owner info
`onUserBlocked` / `onUserUnblocked`	Updates user blocked state
Connection reconnected	Refreshes user/group data

Functionality

Property	Type	Default	Description
`backButton`	`WidgetBuilder?`	`null`	Custom back button widget
`messageHeaderStyle`	`CometChatMessageHeaderStyle?`	`null`	`CometChatMessageHeaderStyle` set styling props for message header
`group`	`Group?`	`null`	Group object for group chat header
`user`	`User?`	`null`	User object for 1:1 chat header
`trailingView`	`List<Widget>? Function(User? user, Group? group, BuildContext context)?`	`null`	`trailingView` set appbar options
`listItemView`	`Widget Function(Group? group, User? user, BuildContext context)?`	`null`	`listItemView` set custom view for listItem
`showBackButton`	`bool?`	`true`	Toggle back button visibility
`subtitleView`	`Widget? Function(Group? group, User? user, BuildContext context)?`	`null`	`subtitleView` to set subtitle view
`listItemStyle`	`ListItemStyle?`	`null`	`listItemStyle` style for every list item
`onBack`	`VoidCallback?`	`null`	`onBack` callback triggered on closing this screen
`onHeaderTap`	`VoidCallback?`	`null`	Fires when the avatar, name or subtitle area is tapped — typically wired to open an info screen. Available since v6.1.1.
`onInfoTap`	`VoidCallback?`	`null`	When set, the ⋯ overflow menu carries a “User Info” / “Group Info” entry that calls it. Available since v6.1.1.
`onSearchTap`	`VoidCallback?`	`null`	When set, the ⋯ overflow menu carries a “Search” entry that calls it. Available since v6.1.1.
`pinnedMessagesVisibility`	`bool?`	`true`	Shows the Pinned Messages entry in the ⋯ overflow menu. Also requires the Pin Message feature to be enabled, and never renders in thread mode. Available since v6.1.1.
`onPinnedMessagesTap`	`VoidCallback?`	`null`	Handles the Pinned Messages entry yourself instead of letting the kit push the screen. Available since v6.1.1.
`onPinnedMessageItemTap`	`Function(BaseMessage message)?`	`null`	Forwarded to the pinned list the kit opens — fires when a pinned row is tapped, after that screen pops. Available since v6.1.1.
`pinnedMessagesStyle`	`CometChatPinnedMessagesStyle?`	`null`	Styling for the pinned list the header opens. Available since v6.1.1.
`parentMessage`	`BaseMessage?`	`null`	The thread’s root message. Puts the header in thread mode and renders the thread subscription bell. Available since v6.1.1.
`threadSubscriptionVisibility`	`bool?`	`true`	Shows the thread subscription bell when `parentMessage` is set. Also requires `UIKitSettings.enableThreadSubscription`. Available since v6.1.1.
`avatarHeight`	`double?`	`null`	`avatarHeight` set height for avatar
`avatarWidth`	`double?`	`null`	`avatarWidth` set width for avatar
`height`	`double?`	`null`	`height` set height for message header
`padding`	`EdgeInsetsGeometry?`	`null`	`padding` set padding for message header
`hideVideoCallButton`	`bool?`	`null`	`hideVideoCallButton` is a `bool` that can be used to hide/display video call button
`hideVoiceCallButton`	`bool?`	`null`	`hideVoiceCallButton` is a `bool` that can be used to hide/display voice call button
`titleView`	`Widget? Function(Group? group, User? user, BuildContext context)?`	`null`	`titleView` to set to set titleView view
`leadingStateView`	`Widget? Function(Group? group, User? user, BuildContext context)?`	`null`	`leadingStateView` to set leading View
`auxiliaryButtonView`	`Widget? Function(Group? group, User? user, BuildContext context)?`	`null`	`auxiliaryButtonView` to set auxiliary view
`usersStatusVisibility`	`bool?`	`true`	`usersStatusVisibility` controls visibility of status indicator shown if a user is online
`dateTimeFormatterCallback`	`DateTimeFormatterCallback?`	`null`	`dateTimeFormatterCallback` is a callback that can be used to format the date and time
`hideNewChatButton`	`bool?`	`null`	`hideNewChatButton` is a `bool` that can be used to hide/display chat button button
`hideChatHistoryButton`	`bool?`	`null`	`hideChatHistoryButton` is a `bool` that can be used to hide/display chat history button
`chatHistoryButtonClick`	`VoidCallback?`	`null`	`chatHistoryButtonClick` callback triggered on chat history button click
`newChatButtonClick`	`VoidCallback?`	`null`	`newChatButtonClick` callback triggered on new chat button click
`newChatIcon`	`IconData?`	`null`	`newChatIcon` provides new chat icon
`chatHistoryIcon`	`IconData?`	`null`	`chatHistoryIcon` provides chat history icon
`messageHeaderBloc`	`MessageHeaderBloc?`	`null`	Your own bloc, used instead of the one the header creates. The header does not close it on dispose. See BLoC Access. Available since v6.2.0.

Available since v6.1.1 The header’s ⋯ button opens a menu built from the props you set, in this order: Search (when onSearchTap is set), Pinned Messages (see below), and User Info / Group Info (when onInfoTap is set). The button only renders when at least one entry applies, and never in thread mode — when parentMessage is set. onHeaderTap is separate: it fires when the avatar, name or subtitle is tapped.

Dart

CometChatMessageHeader(
  group: group,
  onSearchTap: () => _openSearch(group),
  onInfoTap: () => _openGroupInfo(group),
  onHeaderTap: () => _openGroupInfo(group),
)

Pinned messages

The Pinned Messages entry opens the conversation’s Pinned Messages screen. It renders when pinnedMessagesVisibility is not false and CometChat.isPinMessageEnabled() returns true. By default the kit pushes the screen itself, passing it the header’s user or group, onPinnedMessageItemTap as its onItemTap, and pinnedMessagesStyle as its style. Set onPinnedMessagesTap to take over presentation — a desktop layout that shows the list in a side panel rather than a pushed route, say, or to pass the screen’s other options such as hideUnpinOption.

Dart

CometChatMessageHeader(
  group: group,
  onPinnedMessageItemTap: (message) => _controller.jumpToMessage(message.id),
)

Thread subscription

Passing the thread’s root message as parentMessage puts the header in thread mode and renders a notification bell in its trailing area, reflecting the live subscription state. Tapping it subscribes or unsubscribes the user. The bell is gated on UIKitSettings.enableThreadSubscription, which is false by default, and can be hidden with threadSubscriptionVisibility: false — see the Thread Subscription guide.

Custom View Slots

Subtitle View

Replace the default subtitle (online status / typing indicator / member count).

Dart

CometChatMessageHeader(
  user: user,
  subtitleView: (group, user, context) {
    if (user != null) {
      return Text(
        user.status == "online" ? "Active now" : "Last seen recently",
        style: TextStyle(color: Color(0xFF727272), fontSize: 12),
      );
    }
    if (group != null) {
      return Text(
        "${group.membersCount} members",
        style: TextStyle(color: Color(0xFF727272), fontSize: 12),
      );
    }
    return null;
  },
)

Leading View

Replace the avatar / left section.

Dart

CometChatMessageHeader(
  user: user,
  leadingStateView: (group, user, context) {
    return CircleAvatar(
      backgroundImage: NetworkImage(user?.avatar ?? ""),
      child: user?.avatar == null ? Text(user?.name.isNotEmpty == true ? user!.name[0] : "") : null,
    );
  },
)

Title View

Replace the name / title text.

Dart

CometChatMessageHeader(
  user: user,
  titleView: (group, user, context) {
    return Text(
      user?.name ?? group?.name ?? "",
      style: TextStyle(fontWeight: FontWeight.bold, fontSize: 16),
    );
  },
)

Trailing View

Replace the right section (call buttons, menu, etc.).

Dart

CometChatMessageHeader(
  user: user,
  trailingView: (user, group, context) {
    return Row(
      mainAxisSize: MainAxisSize.min,
      children: [
        IconButton(icon: Icon(Icons.call), onPressed: () {}),
        IconButton(icon: Icon(Icons.videocam), onPressed: () {}),
        IconButton(icon: Icon(Icons.info_outline), onPressed: () {}),
      ],
    );
  },
)

Common Patterns

Header with info button for groups

Dart

CometChatMessageHeader(
  group: group,
  trailingView: (user, group, context) {
    return IconButton(
      icon: Icon(Icons.info_outline),
      onPressed: () {
        Navigator.push(context, MaterialPageRoute(
          builder: (context) => GroupInfoScreen(group: group!),
        ));
      },
    );
  },
)

Hide back button (embedded in tab layout)

Dart

CometChatMessageHeader(
  user: user,
  showBackButton: false,
)

Advanced

BLoC Access

Available since v6.2.0. Pass your own MessageHeaderBloc through messageHeaderBloc to own the header’s state. The header uses it instead of creating one, still sets the user or group on it, and does not close it on dispose — close it yourself.

Dart

class _ChatScreenState extends State<ChatScreen> {
  late final MessageHeaderBloc _headerBloc = MessageHeaderBloc();

  @override
  void dispose() {
    _headerBloc.close(); // the header does not close a bloc it was given
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return CometChatMessageHeader(
      user: widget.user,
      messageHeaderBloc: _headerBloc,
    );
  }
}

On v6.1.1 and earlier, CometChatMessageHeader has no messageHeaderBloc parameter and always manages its own bloc — customize presentation with the view slots above instead. The header passes usersStatusVisibility to the bloc only when it creates the bloc itself; give your own bloc the same value through the MessageHeaderBloc constructor.

Public BLoC Methods

Method	Returns	Description
`getTypingNotifier()`	`ValueNotifier<TypingIndicator?>`	Typing indicator notifier for isolated rebuilds

Style

Dart

CometChatMessageHeader(
  user: user,
  messageHeaderStyle: CometChatMessageHeaderStyle(
    backgroundColor: Colors.white,
    titleTextColor: Color(0xFF141414),
    subtitleTextColor: Color(0xFF727272),
    onlineStatusColor: Color(0xFF09C26F),
    typingIndicatorTextStyle: TextStyle(fontSize: 12),
  ),
)

Style Properties

Property	Description
`backgroundColor`	Header background color
`avatarStyle`	Avatar appearance
`statusIndicatorStyle`	Online/offline indicator
`typingIndicatorStyle`	Typing indicator text style

See Component Styling for the full reference.

Next Steps

Message List

Display messages in a conversation

Message Composer

Compose and send messages

Call Buttons

Add voice and video call buttons

Component Styling

Detailed styling reference

​Where It Fits

​Quick Start

​Actions and Events

​Callback Methods

​onBack

​onError

​SDK Events (Real-Time, Automatic)

​Functionality

​Overflow Menu

​Pinned messages

​Thread subscription

​Custom View Slots

​Subtitle View

​Leading View

​Title View

​Trailing View

​Common Patterns

​Header with info button for groups

​Hide back button (embedded in tab layout)

​Advanced

​BLoC Access

​Public BLoC Methods

​Style

​Style Properties

​Next Steps

Message List

Message Composer

Call Buttons

Component Styling

Where It Fits

Quick Start

Actions and Events

Callback Methods

`onBack`

`onError`

SDK Events (Real-Time, Automatic)

Functionality

Overflow Menu

Pinned messages

Thread subscription

Custom View Slots

Subtitle View

Leading View

Title View

Trailing View

Common Patterns

Header with info button for groups

Hide back button (embedded in tab layout)

Advanced

BLoC Access

Public BLoC Methods

Style

Style Properties

Next Steps