Thread Header - CometChat Docs

AI Agent Component Spec

{
  "component": "CometChatThreadHeader",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatThreadHeader } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "Displays the parent message and reply count at the top of a threaded conversation view.",
  "cssRootClass": ".cometchat-thread-header",
  "props": {
    "data": {
      "parentMessage": { "type": "CometChat.BaseMessage", "required": true },
      "template": { "type": "CometChatMessageTemplate", "default": "undefined" },
      "textFormatters": { "type": "CometChatTextFormatter[]", "default": "undefined" },
      "separatorDateTimeFormat": { "type": "CalendarObject", "default": "DD MMM, YYYY" },
      "messageSentAtDateTimeFormat": { "type": "CalendarObject", "default": "hh:mm A" }
    },
    "callbacks": {
      "onClose": "() => void",
      "onError": "((error: CometChat.CometChatException) => void) | null",
      "onSubtitleClicked": "() => void"
    },
    "visibility": {
      "hideDate": { "type": "boolean", "default": false },
      "hideReplyCount": { "type": "boolean", "default": false },
      "hideReceipts": { "type": "boolean", "default": false },
      "showScrollbar": { "type": "boolean", "default": false }
    },
    "viewSlots": {
      "messageBubbleView": "JSX.Element",
      "subtitleView": "JSX.Element"
    }
  },
  "types": {
    "CalendarObject": {
      "today": "string | undefined",
      "yesterday": "string | undefined",
      "lastWeek": "string | undefined",
      "otherDays": "string | undefined"
    }
  }
}

Where It Fits

CometChatThreadHeader renders the parent message bubble and reply count at the top of a thread panel. Wire it above a CometChatMessageList (with parentMessageId) and CometChatMessageComposer (with parentMessageId) to build a complete thread view.

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

function ThreadView({ parentMessageId, user }: { parentMessageId: number; user: CometChat.User }) {
  const [parentMessage, setParentMessage] = useState<CometChat.BaseMessage>();

  useEffect(() => {
    CometChat.getMessageDetails(String(parentMessageId)).then(setParentMessage);
  }, [parentMessageId]);

  if (!parentMessage) return null;

  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
      <CometChatThreadHeader
        parentMessage={parentMessage}
        onClose={() => { /* close thread panel */ }}
      />
      <CometChatMessageList user={user} parentMessageId={parentMessageId} />
      <CometChatMessageComposer user={user} parentMessageId={parentMessageId} />
    </div>
  );
}

Minimal Render

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

function ThreadHeaderDemo() {
  const [parentMessage, setParentMessage] = useState<CometChat.BaseMessage>();

  useEffect(() => {
    CometChat.getMessageDetails("MESSAGE_ID").then(setParentMessage);
  }, []);

  return parentMessage ? (
    <CometChatThreadHeader parentMessage={parentMessage} />
  ) : null;
}

export default ThreadHeaderDemo;

Root CSS class: .cometchat-thread-header

Actions and Events

Callback Props

onClose

Fires when the close button is clicked.

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

function ThreadHeaderWithClose({ parentMessage }: { parentMessage: CometChat.BaseMessage }) {
  return (
    <CometChatThreadHeader
      parentMessage={parentMessage}
      onClose={() => console.log("Close thread panel")}
    />
  );
}

onSubtitleClicked

Fires when the subtitle area is clicked.

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

function ThreadHeaderWithSubtitleClick({ parentMessage }: { parentMessage: CometChat.BaseMessage }) {
  return (
    <CometChatThreadHeader
      parentMessage={parentMessage}
      onSubtitleClicked={() => console.log("Subtitle clicked")}
    />
  );
}

onError

Fires on internal errors.

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

function ThreadHeaderWithError({ parentMessage }: { parentMessage: CometChat.BaseMessage }) {
  return (
    <CometChatThreadHeader
      parentMessage={parentMessage}
      onError={(error: CometChat.CometChatException) => {
        console.error("ThreadHeader error:", error);
      }}
    />
  );
}

SDK Events (Real-Time, Automatic)

The component listens to SDK events internally for real-time reply count updates. No manual attachment needed.

Custom View Slots

Slot	Type	Replaces
`messageBubbleView`	`JSX.Element`	Parent message bubble
`subtitleView`	`JSX.Element`	Subtitle text below the thread title

messageBubbleView

Replace the parent message bubble with a custom view.

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

function CustomBubbleThread({ parentMessage }: { parentMessage: CometChat.BaseMessage }) {
  return (
    <CometChatThreadHeader
      parentMessage={parentMessage}
      messageBubbleView={<div>Custom bubble view</div>}
    />
  );
}

Date Time Format Customization

separatorDateTimeFormat

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

function CustomDateThread({ parentMessage }: { parentMessage: CometChat.BaseMessage }) {
  return (
    <CometChatThreadHeader
      parentMessage={parentMessage}
      separatorDateTimeFormat={new CalendarObject({
        today: "hh:mm A",
        yesterday: "[yesterday]",
        otherDays: "DD/MM/YYYY",
      })}
    />
  );
}

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

Thread header with hidden chrome

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

function MinimalThread({ parentMessage }: { parentMessage: CometChat.BaseMessage }) {
  return (
    <CometChatThreadHeader
      parentMessage={parentMessage}
      hideDate={true}
      hideReplyCount={true}
      hideReceipts={true}
    />
  );
}

CSS Architecture

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

Key Selectors

Target	Selector
Root	`.cometchat-thread-header`
Top bar	`.cometchat-thread-header__top-bar`
Title	`.cometchat-thread-header__top-bar-title`
Subtitle	`.cometchat-thread-header__top-bar-subtitle-text`
Close button	`.cometchat-thread-header__top-bar-close`
Body	`.cometchat-thread-header__body`
Date separator	`.cometchat-thread-header__body-timestamp`
Message bubble area	`.cometchat-thread-header__message`
Incoming message	`.cometchat-thread-header__message-incoming`
Outgoing message	`.cometchat-thread-header__message-outgoing`
Reply bar	`.cometchat-thread-header__reply-bar`
Reply count	`.cometchat-thread-header__reply-bar-count`
Reply divider	`.cometchat-thread-header__reply-bar-divider`

Example: Brand-themed thread header

.cometchat-thread-header {
  background-color: #edeafa;
}

.cometchat-thread-header__reply-bar-count {
  color: #6852d6;
}

.cometchat-thread-header__reply-bar-divider {
  background: #6852d6;
}

Accessibility

The component renders a thread header with a close button that is keyboard-focusable and activates on Enter/Space. The parent message bubble is rendered within a scrollable container. The reply count is exposed as text content.

Props

All props are optional unless noted otherwise.

hideDate

Hides the date header.


Type	`boolean`
Default	`false`

hideReceipts

Hides the receipt indicator.


Type	`boolean`
Default	`false`

hideReplyCount

Hides the reply count.


Type	`boolean`
Default	`false`

messageBubbleView

Custom component for the parent message bubble.


Type	`JSX.Element`
Default	`undefined`

messageSentAtDateTimeFormat

Format for the message sent-at timestamp.


Type	`CalendarObject`
Default	`hh:mm A`

onClose

Callback fired when the close button is clicked.


Type	`() => void`
Default	`undefined`

onError

Callback fired when the component encounters an error.


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

onSubtitleClicked

Callback fired when the subtitle area is clicked.


Type	`() => void`
Default	`undefined`

parentMessage

The parent message displayed in the thread header. Required.


Type	`CometChat.BaseMessage`
Default	—

separatorDateTimeFormat

Format for the date separator timestamp.


Type	`CalendarObject`
Default	`DD MMM, YYYY`

showScrollbar

Shows the scrollbar in the component.


Type	`boolean`
Default	`false`

subtitleView

Custom component for the subtitle text.


Type	`JSX.Element`
Default	`undefined`

template

Custom template for the parent message bubble rendering.


Type	`CometChatMessageTemplate`
Default	`undefined`

textFormatters

Custom text formatters for message text.


Type	`CometChatTextFormatter[]`
Default	`undefined`

CSS Selectors

Target	Selector
Root	`.cometchat-thread-header`
Top bar	`.cometchat-thread-header__top-bar`
Title	`.cometchat-thread-header__top-bar-title`
Subtitle	`.cometchat-thread-header__top-bar-subtitle-text`
Close button	`.cometchat-thread-header__top-bar-close`
Body	`.cometchat-thread-header__body`
Date separator	`.cometchat-thread-header__body-timestamp`
Message bubble area	`.cometchat-thread-header__message`
Incoming message	`.cometchat-thread-header__message-incoming`
Outgoing message	`.cometchat-thread-header__message-outgoing`
Reply bar	`.cometchat-thread-header__reply-bar`
Reply count	`.cometchat-thread-header__reply-bar-count`
Reply divider	`.cometchat-thread-header__reply-bar-divider`

​Where It Fits

​Minimal Render

​Actions and Events

​Callback Props

​onClose

​onSubtitleClicked

​onError

​SDK Events (Real-Time, Automatic)

​Custom View Slots

​messageBubbleView

​Date Time Format Customization

​separatorDateTimeFormat

​Common Patterns

​Thread header with hidden chrome

​CSS Architecture

​Key Selectors

​Example: Brand-themed thread header

​Accessibility

​Props

​hideDate

​hideReceipts

​hideReplyCount

​messageBubbleView

​messageSentAtDateTimeFormat

​onClose

​onError

​onSubtitleClicked

​parentMessage

​separatorDateTimeFormat

​showScrollbar

​subtitleView

​template

​textFormatters

​CSS Selectors

Where It Fits

Minimal Render

Actions and Events

Callback Props

onClose

onSubtitleClicked

onError

SDK Events (Real-Time, Automatic)

Custom View Slots

messageBubbleView

Date Time Format Customization

separatorDateTimeFormat

Common Patterns

Thread header with hidden chrome

CSS Architecture

Key Selectors

Example: Brand-themed thread header

Accessibility

Props

hideDate

hideReceipts

hideReplyCount

messageBubbleView

messageSentAtDateTimeFormat

onClose

onError

onSubtitleClicked

parentMessage

separatorDateTimeFormat

showScrollbar

subtitleView

template

textFormatters

CSS Selectors