> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-feature-react-thread-subscription-pin-sa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Thread Header

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

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "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"
        }
      }
    }
  }
  ```
</Accordion>

## 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.

<Info>
  **Live Preview** — interact with the default thread header.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-messages-thread-header--default)
</Info>

<iframe src="https://storybook.cometchat.io/react/iframe.html?id=components-messages-thread-header--default&viewMode=story&shortcuts=false&singleStory=true" className="w-full rounded-xl" loading="lazy" style={{height: "250px", border: "1px solid #e0e0e0"}} title="CometChat Thread Header — Default" allow="clipboard-write" />

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

```tsx theme={null}
import { CometChatThreadHeader } from "@cometchat/chat-uikit-react";

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

### Compound Composition

```tsx theme={null}
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

```tsx theme={null}
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:

```tsx theme={null}
<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.

```tsx theme={null}
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:

```tsx theme={null}
<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`.

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

<Note>
  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](/ui-kit/react/guide-threaded-messages#thread-subscription).
</Note>

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.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.

<Note>
  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.
</Note>

***

### 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

<CardGroup cols={2}>
  <Card title="Message List" icon="comments" href="/ui-kit/react/components/message-list">
    Display threaded replies below the parent message
  </Card>

  <Card title="Message Composer" icon="keyboard" href="/ui-kit/react/components/message-composer">
    Compose replies in the thread
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>