Message Header - CometChat Docs

AI Agent Component Spec

{
  "component": "CometChatMessageHeader",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatMessageHeader } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "Toolbar displaying user/group avatar, name, status, typing indicator, back button, and call controls for a single conversation.",
  "cssRootClass": ".cometchat-message-header",
  "note": "View slots are JSX.Element (not functions) — unlike list components.",
  "props": {
    "data": {
      "user": { "type": "CometChat.User", "default": "undefined" },
      "group": { "type": "CometChat.Group", "default": "undefined" },
      "lastActiveAtDateTimeFormat": { "type": "CalendarObject", "default": "component default" },
      "summaryGenerationMessageCount": { "type": "number", "default": 1000 }
    },
    "callbacks": {
      "onBack": "() => void",
      "onError": "((error: CometChat.CometChatException) => void) | null",
      "onItemClick": "() => void",
      "onSearchOptionClicked": "() => void"
    },
    "visibility": {
      "showBackButton": { "type": "boolean", "default": false },
      "hideVideoCallButton": { "type": "boolean", "default": false },
      "hideVoiceCallButton": { "type": "boolean", "default": false },
      "hideUserStatus": { "type": "boolean", "default": false },
      "showConversationSummaryButton": { "type": "boolean", "default": false },
      "showSearchOption": { "type": "boolean", "default": false },
      "enableAutoSummaryGeneration": { "type": "boolean", "default": false }
    },
    "viewSlots": {
      "itemView": "JSX.Element",
      "leadingView": "JSX.Element",
      "titleView": "JSX.Element",
      "subtitleView": "JSX.Element",
      "trailingView": "JSX.Element",
      "auxiliaryButtonView": "JSX.Element"
    }
  },
  "sdkListeners": [
    "onUserOnline",
    "onUserOffline",
    "onTypingStarted",
    "onTypingEnded",
    "onGroupMemberJoined",
    "onGroupMemberLeft",
    "onGroupMemberKicked",
    "onGroupMemberBanned",
    "onMemberAddedToGroup"
  ],
  "types": {
    "CalendarObject": {
      "today": "string | undefined",
      "yesterday": "string | undefined",
      "lastWeek": "string | undefined",
      "otherDays": "string | undefined",
      "relativeTime": {
        "minute": "string | undefined",
        "minutes": "string | undefined",
        "hour": "string | undefined",
        "hours": "string | undefined"
      }
    }
  }
}

Where It Fits

CometChatMessageHeader is a toolbar component that sits above CometChatMessageList and CometChatMessageComposer. It receives a user or group prop and displays the conversation’s avatar, name, online status, and typing indicator. Call buttons are rendered automatically when the calling extension is enabled.

import { useEffect, useState } from "react";
import {
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import "@cometchat/chat-uikit-react/css-variables.css";

function ChatView() {
  const [user, setUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("UID").then(setUser);
  }, []);

  if (!user) return null;

  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
      <CometChatMessageHeader user={user} />
      <CometChatMessageList user={user} />
      <CometChatMessageComposer user={user} />
    </div>
  );
}

Minimal Render

import { useEffect, useState } from "react";
import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import "@cometchat/chat-uikit-react/css-variables.css";

function MessageHeaderDemo() {
  const [user, setUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("UID").then(setUser);
  }, []);

  return user ? <CometChatMessageHeader user={user} /> : null;
}

export default MessageHeaderDemo;

Root CSS class: .cometchat-message-header

Actions and Events

Callback Props

onBack

Fires when the back button is clicked. Requires showBackButton={true}.

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function HeaderWithBack({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader
      user={user}
      showBackButton={true}
      onBack={() => console.log("Navigate back")}
    />
  );
}

onItemClick

Fires when the header list item area (avatar + name) is clicked.

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function HeaderWithItemClick({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader
      user={user}
      onItemClick={() => console.log("Open user detail")}
    />
  );
}

onSearchOptionClicked

Fires when the search option is clicked. Requires showSearchOption={true}.

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function HeaderWithSearch({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader
      user={user}
      showSearchOption={true}
      onSearchOptionClicked={() => console.log("Open search")}
    />
  );
}

onError

Fires on internal errors.

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function HeaderWithError({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader
      user={user}
      onError={(error: CometChat.CometChatException) => {
        console.error("MessageHeader error:", error);
      }}
    />
  );
}

SDK Events (Real-Time, Automatic)

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

SDK Listener	Internal behavior
`onUserOnline` / `onUserOffline`	Updates the user’s online/offline status indicator
`onTypingStarted` / `onTypingEnded`	Shows/hides the typing indicator in the subtitle area
Group member events	Updates group member count when members join/leave

In React 18 StrictMode, useEffect runs twice on mount in development. The component handles listener cleanup internally.

Custom View Slots

View slots for CometChatMessageHeader are JSX.Element (not functions) — unlike list components where slots receive a data parameter.

Slot	Type	Replaces
`itemView`	`JSX.Element`	Entire list item (avatar + name + subtitle)
`leadingView`	`JSX.Element`	Avatar / left section
`titleView`	`JSX.Element`	Name / title text
`subtitleView`	`JSX.Element`	Subtitle text (status / typing indicator)
`trailingView`	`JSX.Element`	Right section (call buttons area)
`auxiliaryButtonView`	`JSX.Element`	Auxiliary button area (next to call buttons)

itemView

Replace the entire list item (avatar + name + subtitle).

TypeScript
CSS

import {
  CometChatMessageHeader,
  CometChatListItem,
} from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function CustomItemViewHeader({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader
      user={user}
      itemView={
        <CometChatListItem
          avatarName={user.getName()}
          avatarURL={user.getAvatar()}
          title={user.getName()}
          subtitleView={user.getStatus()}
        />
      }
      showBackButton={true}
    />
  );
}

.cometchat-message-header .cometchat-list-item .cometchat-avatar {
  border-radius: 8px;
}

titleView

Replace the name / title text.

TypeScript
CSS

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function CustomTitleHeader({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader
      user={user}
      titleView={
        <div className="message-header__title-view">
          <span className="message-header__title-view-name">
            {user.getName() + " • "}
          </span>
          <span className="message-header__title-view-status">
            {user.getStatusMessage()}
          </span>
        </div>
      }
    />
  );
}

.cometchat-message-header .message-header__title-view {
  display: flex;
  gap: 4px;
  width: 100%;
}

.message-header__title-view-name {
  color: #141414;
  font: 500 16px/19.2px Roboto;
}

.message-header__title-view-status {
  color: #6852d6;
  font: 400 16px/19.2px Roboto;
}

subtitleView

Replace the subtitle text (status / typing indicator area).

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function CustomSubtitleHeader({ group }: { group: CometChat.Group }) {
  return (
    <CometChatMessageHeader
      group={group}
      subtitleView={
        <>{group.getMembersCount() + " • " + group.getDescription()}</>
      }
    />
  );
}

leadingView

Replace the avatar / left section.

TypeScript
CSS

import {
  CometChatMessageHeader,
  CometChatAvatar,
} from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function CustomLeadingHeader({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader
      user={user}
      leadingView={
        <div className="message-header__leading-view">
          <CometChatAvatar image={user.getAvatar()} name={user.getName()} />
          <span className="message-header__leading-view-role">
            {user.getRole()}
          </span>
        </div>
      }
    />
  );
}

.cometchat-message-header .message-header__leading-view .cometchat-avatar {
  border-radius: 8px;
  height: 48px;
  width: 48px;
}

.message-header__leading-view-role {
  display: flex;
  width: 48px;
  height: 15px;
  padding: 1px 3px;
  justify-content: center;
  align-items: center;
  color: #fff;
  font: 600 8px/9.6px Roboto;
  background: #0b7bea;
  position: absolute;
  bottom: -2px;
}

.message-header__leading-view {
  position: relative;
}

trailingView

Replace the right section (call buttons area).

import {
  CometChatMessageHeader,
  CometChatButton,
} from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function CustomTrailingHeader({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader
      user={user}
      trailingView={
        <CometChatButton onClick={() => { /* custom action */ }} />
      }
    />
  );
}

auxiliaryButtonView

Replace the auxiliary button area (next to call buttons).

import {
  CometChatMessageHeader,
  CometChatButton,
} from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function AuxiliaryButtonHeader({ group }: { group: CometChat.Group }) {
  return (
    <CometChatMessageHeader
      group={group}
      auxiliaryButtonView={
        <CometChatButton onClick={() => { /* custom action */ }} />
      }
    />
  );
}

lastActiveAtDateTimeFormat

Customize the “last seen” timestamp format using a CalendarObject.

import {
  CometChatMessageHeader,
  CalendarObject,
} from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function CustomDateHeader({ user }: { user: CometChat.User }) {
  const dateFormat = new CalendarObject({
    today: "hh:mm A",
    yesterday: "[yesterday]",
    otherDays: "DD MM YYYY",
  });

  return (
    <CometChatMessageHeader
      user={user}
      lastActiveAtDateTimeFormat={dateFormat}
    />
  );
}

If no property is passed in the CalendarObject, the component checks the global configuration first. If also missing there, the component’s default formatting applies.

Common Patterns

Header with back button and search

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function FullFeaturedHeader({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader
      user={user}
      showBackButton={true}
      showSearchOption={true}
      onBack={() => { /* navigate back */ }}
      onSearchOptionClicked={() => { /* open search */ }}
    />
  );
}

Hide call buttons

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function NoCalls({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader
      user={user}
      hideVideoCallButton={true}
      hideVoiceCallButton={true}
    />
  );
}

Group header with AI summary

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function GroupHeaderWithSummary({ group }: { group: CometChat.Group }) {
  return (
    <CometChatMessageHeader
      group={group}
      showConversationSummaryButton={true}
      enableAutoSummaryGeneration={true}
      summaryGenerationMessageCount={500}
    />
  );
}

CSS Architecture

The component uses CSS custom properties (design tokens) defined in @cometchat/chat-uikit-react/css-variables.css. The cascade:

Global tokens are set on the .cometchat root wrapper.
Component CSS (.cometchat-message-header) consumes these tokens via var() with fallback values.
Overrides target .cometchat-message-header descendant selectors in a global stylesheet.

Key Selectors

Target	Selector
Root	`.cometchat-message-header`
List item	`.cometchat-message-header .cometchat-list-item`
Body title	`.cometchat-message-header .cometchat-list-item__body-title`
Avatar	`.cometchat-message-header .cometchat-list-item .cometchat-avatar`
Leading view	`.cometchat-message-header .cometchat-list-item__leading-view`
Trailing view	`.cometchat-message-header .cometchat-list-item__trailing-view`
Subtitle	`.cometchat-message-header__subtitle`
Subtitle (typing)	`.cometchat-message-header__subtitle-typing`
Back button	`.cometchat-message-header__back-button`
Auxiliary button view	`.cometchat-message-header__auxiliary-button-view`
List item container	`.cometchat-message-header__listitem`
Title container	`.cometchat-message-header .cometchat-list-item__title-container`

Example: Brand-themed header

.cometchat-message-header .cometchat-list-item .cometchat-avatar {
  background: #f0999b;
  border-radius: 8px;
}

.cometchat-message-header .cometchat-avatar__text {
  font-family: "SF Pro";
}

Customization Matrix

What to change	Where	Property/API	Example
Override behavior on user interaction	Component props	`on<Event>` callbacks	`onBack={() => navigate(-1)}`
Toggle visibility of UI elements	Component props	`hide<Feature>` / `show<Feature>` boolean props	`hideVideoCallButton={true}`
Replace a section of the header	Component props	`<slot>View` JSX.Element props	`titleView={<div>Custom</div>}`
Change colors, fonts, spacing	Global CSS	Target `.cometchat-message-header` class	`.cometchat-message-header .cometchat-avatar { border-radius: 8px; }`

Accessibility

The component renders a toolbar with interactive elements. The back button, call buttons, and auxiliary buttons are keyboard-focusable and activate on Enter/Space. The avatar includes alt text. The typing indicator updates the subtitle text dynamically — screen readers announce the change via live region behavior.

Props

All props are optional unless noted otherwise.

auxiliaryButtonView

Custom component for the auxiliary button area.


Type	`JSX.Element`
Default	`undefined`

enableAutoSummaryGeneration

Enables automatic conversation summary generation.


Type	`boolean`
Default	`false`

group

Displays group details in the header.


Type	`CometChat.Group`
Default	`undefined`

Pass either user or group, not both.

hideBackButton

Hides the back navigation button. Deprecated — use showBackButton instead.


Type	`boolean`
Default	`true`

hideUserStatus

Hides the user’s online/offline status indicator.


Type	`boolean`
Default	`false`

hideVideoCallButton

Hides the video call button.


Type	`boolean`
Default	`false`

hideVoiceCallButton

Hides the voice call button.


Type	`boolean`
Default	`false`

itemView

Custom component for the entire list item.


Type	`JSX.Element`
Default	`undefined`

lastActiveAtDateTimeFormat

Format for displaying the “last seen” timestamp.


Type	`CalendarObject`
Default	Component default

leadingView

Custom component for the avatar / left section.


Type	`JSX.Element`
Default	`undefined`

onBack

Callback fired when the back button is clicked.


Type	`() => void`
Default	`() => {}`

onError

Callback fired when the component encounters an error.


Type	`((error: CometChat.CometChatException) => void) \| null`
Default	`undefined`

onItemClick

Callback fired when the header list item is clicked.


Type	`() => void`
Default	`() => {}`

onSearchOptionClicked

Callback fired when the search option is clicked.


Type	`() => void`
Default	`() => {}`

showBackButton

Shows the back navigation button.


Type	`boolean`
Default	`false`

showConversationSummaryButton

Shows the AI conversation summary button.


Type	`boolean`
Default	`false`

showSearchOption

Shows the search option in the header.


Type	`boolean`
Default	`false`

subtitleView

Custom component for the subtitle text.


Type	`JSX.Element`
Default	`undefined`

summaryGenerationMessageCount

Number of messages used for AI summary generation.


Type	`number`
Default	`1000`

titleView

Custom component for the name / title text.


Type	`JSX.Element`
Default	`undefined`

trailingView

Custom component for the right section.


Type	`JSX.Element`
Default	`undefined`

user

Displays user details in the header.


Type	`CometChat.User`
Default	`undefined`

Pass either user or group, not both.

CSS Selectors

Target	Selector
Root	`.cometchat-message-header`
List item	`.cometchat-message-header .cometchat-list-item`
Body title	`.cometchat-message-header .cometchat-list-item__body-title`
Avatar	`.cometchat-message-header .cometchat-list-item .cometchat-avatar`
Leading view	`.cometchat-message-header .cometchat-list-item__leading-view`
Trailing view	`.cometchat-message-header .cometchat-list-item__trailing-view`
Subtitle	`.cometchat-message-header__subtitle`
Subtitle (typing)	`.cometchat-message-header__subtitle-typing`
Back button	`.cometchat-message-header__back-button`
Auxiliary button view	`.cometchat-message-header__auxiliary-button-view`
List item container	`.cometchat-message-header__listitem`
Title container	`.cometchat-message-header .cometchat-list-item__title-container`
Summary button	`.cometchat-message-header__conversation-summary-button`
Search button	`.cometchat-message-header__search-button`
Menu	`.cometchat-message-header__menu`

​Where It Fits

​Minimal Render

​Actions and Events

​Callback Props

​onBack

​onItemClick

​onSearchOptionClicked

​onError

​SDK Events (Real-Time, Automatic)

​Custom View Slots

​itemView

​titleView

​subtitleView

​leadingView

​trailingView

​auxiliaryButtonView

​lastActiveAtDateTimeFormat

​Common Patterns

​Header with back button and search

​Hide call buttons

​Group header with AI summary

​CSS Architecture

​Key Selectors

​Example: Brand-themed header

​Customization Matrix

​Accessibility

​Props

​auxiliaryButtonView

​enableAutoSummaryGeneration

​group

​hideBackButton

​hideUserStatus

​hideVideoCallButton

​hideVoiceCallButton

​itemView

​lastActiveAtDateTimeFormat

​leadingView

​onBack

​onError

​onItemClick

​onSearchOptionClicked

​showBackButton

​showConversationSummaryButton

​showSearchOption

​subtitleView

​summaryGenerationMessageCount

​titleView

​trailingView

​user

​CSS Selectors

Where It Fits

Minimal Render

Actions and Events

Callback Props

onBack

onItemClick

onSearchOptionClicked

onError

SDK Events (Real-Time, Automatic)

Custom View Slots

itemView

titleView

subtitleView

leadingView

trailingView

auxiliaryButtonView

lastActiveAtDateTimeFormat

Common Patterns

Header with back button and search

Hide call buttons

Group header with AI summary

CSS Architecture

Key Selectors

Example: Brand-themed header

Customization Matrix

Accessibility

Props

auxiliaryButtonView

enableAutoSummaryGeneration

group

hideBackButton

hideUserStatus

hideVideoCallButton

hideVoiceCallButton

itemView

lastActiveAtDateTimeFormat

leadingView

onBack

onError

onItemClick

onSearchOptionClicked

showBackButton

showConversationSummaryButton

showSearchOption

subtitleView

summaryGenerationMessageCount

titleView

trailingView

user

CSS Selectors