Thread Header - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatThreadHeader",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatThreadHeader } from \"@cometchat/chat-uikit-react\";",
  "description": "Displays the parent message bubble and reply count for threaded conversations.",
  "cssRootClass": ".cometchat-thread-header",
  "primaryOutput": {
    "prop": "onClose",
    "type": "() => void"
  },
  "props": {
    "data": {
      "parentMessage": {
        "type": "CometChat.BaseMessage",
        "required": true,
        "note": "The parent message of the thread"
      },
      "separatorDateTimeFormat": {
        "type": "CometChatDateFormatConfig",
        "default": "undefined"
      },
      "messageSentAtDateTimeFormat": {
        "type": "CometChatDateFormatConfig",
        "default": "undefined"
      }
    },
    "visibility": {
      "hideReceipts": { "type": "boolean", "default": false },
      "hideDate": { "type": "boolean", "default": false },
      "hideReplyCount": { "type": "boolean", "default": false },
      "hideThreadSubscriptionToggle": { "type": "boolean", "default": false },
      "showScrollbar": { "type": "boolean", "default": false }
    },
    "callbacks": {
      "onClose": "() => void",
      "onSubtitleClicked": "() => void",
      "onParentDeleted": "() => void",
      "onThreadSubscriptionChange": "(subscribed: boolean) => void",
      "onError": "((error: CometChat.CometChatException) => void) | null"
    },
    "viewSlots": {
      "headerView": "ReactNode",
      "messageBubbleView": "ReactNode",
      "subtitleView": "ReactNode"
    }
  },
  "events": {
    "emitted": [],
    "received": [
      {
        "name": "ui:message/sent",
        "payload": "{ message, status: 'success' }",
        "description": "Increments reply count when current user sends a reply"
      },
      {
        "name": "ui:compose/edit",
        "payload": "{ message, status: 'success' }",
        "description": "Updates parent bubble when edited"
      },
      {
        "name": "ui:message/deleted",
        "payload": "{ message }",
        "description": "Triggers onParentDeleted"
      }
    ]
  },
  "sdkListeners": [
    "onTextMessageReceived",
    "onMediaMessageReceived",
    "onCustomMessageReceived",
    "onInteractiveMessageReceived",
    "onMessageEdited",
    "onMessageDeleted"
  ],
  "types": {
    "CometChatDateFormatConfig": {
      "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"
      }
    }
  }
}

Overview

CometChatThreadHeader displays the parent message bubble and reply count for threaded conversations. It renders a top bar with the thread title, sender name, and close button, followed by the parent message bubble and a real-time reply count divider. Wire it above a CometChatMessageList (with parentMessageId) and CometChatMessageComposer to build a complete thread view.

Live Preview — interact with the default thread header.Open in Storybook ↗

The component handles:

Rendering the parent message as a bubble
Real-time reply count updates via SDK listeners
Parent message edit/delete detection
A thread subscription (subscribe/unsubscribe) bell for group threads
Close button and keyboard (Escape) dismissal

Usage

Flat API

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

function ThreadPanel({
  parentMessage,
  onClose,
}: {
  parentMessage: CometChat.BaseMessage;
  onClose: () => void;
}) {
  return (
    <CometChatThreadHeader
      parentMessage={parentMessage}
      onClose={onClose}
    />
  );
}

Compound Composition

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

function ThreadPanel({
  parentMessage,
  onClose,
}: {
  parentMessage: CometChat.BaseMessage;
  onClose: () => void;
}) {
  return (
    <CometChatThreadHeader.Root parentMessage={parentMessage} onClose={onClose}>
      <CometChatThreadHeader.TopBar>
        <CometChatThreadHeader.Title />
        <CometChatThreadHeader.SenderName />
        <CometChatThreadHeader.CloseButton />
      </CometChatThreadHeader.TopBar>
      <CometChatThreadHeader.ParentBubble />
      <CometChatThreadHeader.ReplyCount />
    </CometChatThreadHeader.Root>
  );
}

Full Layout Example

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

function ThreadView({
  parentMessage,
  user,
  group,
  onClose,
}: {
  parentMessage: CometChat.BaseMessage;
  user?: CometChat.User;
  group?: CometChat.Group;
  onClose: () => void;
}) {
  const parentMessageId = parentMessage.getId();

  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
      <CometChatThreadHeader
        parentMessage={parentMessage}
        onClose={onClose}
        onParentDeleted={onClose}
      />
      <CometChatMessageList
        user={user}
        group={group}
        parentMessageId={parentMessageId}
      />
      <CometChatMessageComposer
        user={user}
        group={group}
        parentMessageId={parentMessageId}
      />
    </div>
  );
}

Filtering

This component does not support request builders or filtering. It renders a single parent message and its reply count.

Actions and Events

Callback Props

Prop	Signature	Fires when
`onClose`	`() => void`	Close button clicked or Escape pressed
`onSubtitleClicked`	`() => void`	Sender name / subtitle is clicked
`onParentDeleted`	`() => void`	Parent message is deleted (thread should close)
`onThreadSubscriptionChange`	`(subscribed: boolean) => void`	User subscribes to or unsubscribes from the thread via the bell
`onError`	`((error: CometChat.CometChatException) => void) \| null`	SDK error occurs

Events Emitted

This component does not emit UI events.

Events Received

UI events this component subscribes to (published by other components):

Event	Payload	Behavior
`ui:message/sent`	`{ message, status: 'success' }`	Increments reply count when current user sends a reply in this thread
`ui:compose/edit`	`{ message, status: 'success' }`	Updates the parent bubble when the parent message is edited
`ui:message/deleted`	`{ message }`	Triggers `onParentDeleted` when the parent message is deleted

SDK Listeners (Automatic)

These SDK listeners are attached internally. The component updates its state automatically — no manual subscription needed:

Message listeners: onTextMessageReceived, onMediaMessageReceived, onCustomMessageReceived, onInteractiveMessageReceived — increments reply count when other users send replies
Edits: onMessageEdited — updates parent bubble when edited by another user
Deletes: onMessageDeleted — triggers onParentDeleted when deleted by another user

Customization

View Props

Use view props to replace sections of the default UI while keeping the component’s behavior intact:

<CometChatThreadHeader
  parentMessage={parentMessage}
  onClose={onClose}
  headerView={<MyCustomTopBar />}
  messageBubbleView={<MyCustomBubble message={parentMessage} />}
  subtitleView={<span>Custom subtitle</span>}
/>

Slot	Type	Replaces
`headerView`	`ReactNode`	Entire top bar (title + sender + close button)
`messageBubbleView`	`ReactNode`	Parent message bubble
`subtitleView`	`ReactNode`	Subtitle below the title

messageBubbleView

Replace the parent message bubble with a custom view.

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

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

Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

<CometChatThreadHeader.Root parentMessage={parentMessage} onClose={onClose}>
  <CometChatThreadHeader.TopBar>
    <CometChatThreadHeader.Title />
    <CometChatThreadHeader.CloseButton />
    {/* No SenderName — it won't render */}
  </CometChatThreadHeader.TopBar>
  <CometChatThreadHeader.ParentBubble />
  {/* No ReplyCount — it won't render */}
</CometChatThreadHeader.Root>

Available sub-components:

Sub-component	Description	Props	Flat API equivalent
`Root`	Context provider and container	All Root props + `children`	—
`TopBar`	Top bar container	`children`, `className`	`headerView`
`Title`	Thread title text	`title`, `className`	—
`SenderName`	Parent message sender	`className`	—
`CloseButton`	Close button	`className`	—
`ParentBubble`	Parent message bubble	`disableInteraction`, `messageSentAtDateTimeFormat`, `className`	`messageBubbleView`
`ReplyCount`	Reply count with divider	`showDivider`, `className`	—

Thread Subscription

In a group thread, the header shows a bell that lets the user subscribe to or unsubscribe from the thread, so they can receive updates about new replies even when they aren’t actively viewing it. The bell reflects the current subscription state and toggles it on click, with an optimistic UI update and a toast on failure. The bell renders automatically for group threads. It never appears in a 1:1 thread. To remove it, set hideThreadSubscriptionToggle; to react to changes, pass onThreadSubscriptionChange.

<CometChatThreadHeader
  parentMessage={parentMessage}
  onClose={onClose}
  onThreadSubscriptionChange={(subscribed) =>
    console.log(subscribed ? "Subscribed to thread" : "Unsubscribed from thread")
  }
/>

The same subscribe/unsubscribe action is also available as a message-context-menu option in CometChatMessageList (hideThreadSubscriptionOption). For the underlying hook and events, see Threaded Messages → Thread Subscription.

CSS Styling

Override design tokens on the component selector:

.cometchat-thread-header {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-thread-header__top-bar {
  border-bottom: 1px solid var(--cometchat-border-color-light);
}

Props

parentMessage is required. All other props are optional.

View slot props (headerView, messageBubbleView, subtitleView) are convenience props available only on the flat API. In compound composition mode, use the corresponding sub-components directly.

parentMessage

The parent message of the thread. Required.


Type	`CometChat.BaseMessage`
Required	Yes

hideReceipts

Hide message delivery/read receipts on the parent bubble.


Type	`boolean`
Default	`false`

hideDate

Hide the date chip shown above the parent bubble.


Type	`boolean`
Default	`false`

hideReplyCount

Hide the reply count section below the parent bubble.


Type	`boolean`
Default	`false`

hideThreadSubscriptionToggle

Hide the subscribe/unsubscribe (subscription) bell. The bell only renders for group threads to begin with — it never shows in a 1:1 thread.


Type	`boolean`
Default	`false`

separatorDateTimeFormat

Custom date/time format for the date chip shown above the parent bubble.


Type	`CometChatDateFormatConfig`
Default	`undefined`

messageSentAtDateTimeFormat

Custom date/time format for the sent-at timestamp on the parent message bubble.


Type	`CometChatDateFormatConfig`
Default	`undefined`

showScrollbar

Show the native scrollbar on the bubble wrapper area.


Type	`boolean`
Default	`false`

onClose

Callback when the close button is clicked or Escape is pressed.


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

onSubtitleClicked

Callback when the sender name / subtitle is clicked (navigate to parent in main list).


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

onParentDeleted

Callback when the parent message is deleted (thread should close).


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

onThreadSubscriptionChange

Callback when the user subscribes to or unsubscribes from the thread via the subscription bell. Receives the new subscription state.


Type	`(subscribed: boolean) => void`
Default	`undefined`

onError

Callback when an SDK error occurs.


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

headerView

Custom content to replace the entire top bar (title + sender name + close button).


Type	`ReactNode`
Default	`undefined`

messageBubbleView

Custom content to replace the parent message bubble rendering.


Type	`ReactNode`
Default	`undefined`

subtitleView

Custom subtitle view below the title.


Type	`ReactNode`
Default	`undefined`

CSS Selectors

Target	Selector
Root container	`.cometchat-thread-header`
Top bar	`.cometchat-thread-header__top-bar`
Content area	`.cometchat-thread-header__content`
Title	`.cometchat-thread-header__title`
Sender name	`.cometchat-thread-header__sender-name`
Close button	`.cometchat-thread-header__close-button-wrapper`
Bubble wrapper	`.cometchat-thread-header__bubble-wrapper`
Body timestamp	`.cometchat-thread-header__body-timestamp`
Reply count	`.cometchat-thread-header__reply-count`
Reply count divider	`.cometchat-thread-header__reply-count-divider`
Subscription bell wrapper	`.cometchat-thread-header__subscription-wrapper`
Subscription bell button	`.cometchat-thread-header__subscription-button`
Subscription bell icon	`.cometchat-thread-header__subscription-icon` (`--on` subscribed, `--off` not subscribed)

Next Steps

Message List

Display threaded replies below the parent message

Message Composer

Compose replies in the thread

Theming

Customize colors, fonts, and spacing

​Overview

​Usage

​Flat API

​Compound Composition

​Full Layout Example

​Filtering

​Actions and Events

​Callback Props

​Events Emitted

​Events Received

​SDK Listeners (Automatic)

​Customization

​View Props

​messageBubbleView

​Compound Composition

​Thread Subscription

​CSS Styling

​Props

​parentMessage

​hideReceipts

​hideDate

​hideReplyCount

​hideThreadSubscriptionToggle

​separatorDateTimeFormat

​messageSentAtDateTimeFormat

​showScrollbar

​onClose

​onSubtitleClicked

​onParentDeleted

​onThreadSubscriptionChange

​onError

​headerView

​messageBubbleView

​subtitleView

​CSS Selectors

​Next Steps

Message List

Message Composer

Theming

Overview

Usage

Flat API

Compound Composition

Full Layout Example

Filtering

Actions and Events

Callback Props

Events Emitted

Events Received

SDK Listeners (Automatic)

Customization

View Props

messageBubbleView

Compound Composition

Thread Subscription

CSS Styling

Props

parentMessage

hideReceipts

hideDate

hideReplyCount

hideThreadSubscriptionToggle

separatorDateTimeFormat

messageSentAtDateTimeFormat

showScrollbar

onClose

onSubtitleClicked

onParentDeleted

onThreadSubscriptionChange

onError

headerView

messageBubbleView

subtitleView

CSS Selectors

Next Steps