Thread Header

Displays the parent message bubble and reply count for threaded conversations.

AI Integration Quick Reference

{
  "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 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 },
      "showScrollbar": { "type": "boolean", "default": false }
    },
    "callbacks": {
      "onClose": "() => void",
      "onSubtitleClicked": "() => void",
      "onParentDeleted": "() => 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
• 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)
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

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	—

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

---

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

---

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

---

Next Steps

Message List

Display threaded replies below the parent message

Message Composer

Compose replies in the thread

Theming

Customize colors, fonts, and spacing