Thread Header - CometChat Docs

Display the parent message and reply count for a thread.

When to use this

You are building threaded message views.
You need a header showing the parent message.
You want to handle closing the thread view.

Prerequisites

CometChat React UI Kit v6 installed: @cometchat/chat-uikit-react.
CometChatUIKit.init() and CometChatUIKit.login() complete before rendering.
A valid parentMessage is required.

Quick start

Add the component to your UI.

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

<CometChatThreadHeader parentMessage={parentMessage} />;

What this does: Renders the minimal version of the component.

Verify the component renders after init() and login().

Core concepts

parentMessage is required to render the header.
Use onClose to control thread navigation.

Implementation

AI Agent Component Spec

Package: @cometchat/chat-uikit-react
Import: import { CometChatThreadHeader } from "@cometchat/chat-uikit-react";
Minimal JSX: <CometChatThreadHeader parentMessage={parentMessage} />
Required setup: CometChatUIKit.init(UIKitSettings) then CometChatUIKit.login("UID")
Key props: parentMessage: CometChat.BaseMessage (required)
CSS class: .cometchat-thread-header

Overview

What you’re changing: Overview. Where to change it: Component props or CSS as shown below. Default behavior: UI Kit defaults. Override: Use the examples in this section. Verify: The UI reflects the change shown below. CometChatThreadHeader is a Component that displays the parent message & number of replies of thread.

Before using this component: Ensure CometChatUIKit.init(UIKitSettings) has completed and the user is logged in via CometChatUIKit.login("UID"). See React.js Integration.

Usage

What you’re changing: Usage. Where to change it: Component props or CSS as shown below. Default behavior: UI Kit defaults. Override: Use the examples in this section. Verify: The UI reflects the change shown below.

Integration

The following code snippet illustrates how you can directly incorporate the CometChatThreadHeader component into your Application.

TypeScript
JavaScript

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

export function ThreadHeaderDemo() {
  const [parentMessage, setParentMessage] =
    React.useState<CometChat.BaseMessage>();
  const [chatWithUser, setChatWithUser] = React.useState<CometChat.User>();

  React.useEffect(() => {
    CometChat.getUser("uid").then((user) => {
      setChatWithUser(user);
    });
    CometChat.getMessageDetails("Parent Message Id").then((message) => {
      setParentMessage(message);
    });
  }, []);

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

What this does: Shows the code for this step.

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

export function ThreadHeaderDemo() {
  const [parentMessage, setParentMessage] = useState(null);
  const [chatWithUser, setChatWithUser] = useState(null);

  useEffect(() => {
    CometChat.getUser("uid").then((user) => {
      setChatWithUser(user);
    });
    CometChat.getMessageDetails("Parent Message Id").then((message) => {
      setParentMessage(message);
    });
  }, []);

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

What this does: Shows the code for this step.

Actions

Actions dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the component to fit your specific needs. Example In this example, we are overriding the onClose of the ThreadedMesssage Component.

ThreadHeaderDemo.tsx

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

export function ThreadHeaderDemo() {
  const [parentMessage, setParentMessage] =
    React.useState<CometChat.BaseMessage>();
  const [chatWithUser, setChatWithUser] = React.useState<CometChat.User>();

  React.useEffect(() => {
    CometChat.getUser("uid").then((user) => {
      setChatWithUser(user);
    });
    CometChat.getMessageDetails("Parent Message Id").then((message) => {
      setParentMessage(message);
    });
  }, []);

  const handleClose = () => {
    console.log("your custom on close action");
  };

  return chatWithUser && parentMessage ? (
    <CometChatThreadHeader
      parentMessage={parentMessage}
      onClose={handleClose}
    />
  ) : null;
}

What this does: Shows the code for this step.

Events

Events are emitted by a Component. By using event you can extend existing functionality. Being global events, they can be applied in Multiple Locations and are capable of being Added or Removed. The ThreadHeader Component does not emit any events of its own.

Customization

What you’re changing: Customization. Where to change it: Component props or CSS as shown below. Default behavior: UI Kit defaults. Override: Use the examples in this section. Verify: The UI reflects the change shown below. To fit your app’s design requirements, you can customize the appearance of the conversation component. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.

Style

Using Style you can customize the look and feel of the component in your app, These parameters typically control elements such as the color, size, shape, and fonts used within the component. Example

ThreadHeaderDemo.tsx
ThreadHeaderDemo.css

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

export function ThreadHeaderDemo() {
  const [parentMessage, setParentMessage] =
    React.useState<CometChat.BaseMessage>();
  const [chatWithUser, setChatWithUser] = React.useState<CometChat.User>();

  React.useEffect(() => {
    CometChat.getUser("uid").then((user) => {
      setChatWithUser(user);
    });
    CometChat.getMessageDetails("Parent Message Id").then((message) => {
      setParentMessage(message);
    });
  }, []);

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

What this does: Shows the code for this step.

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

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

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

What this does: Shows the code for this step.

Functionality

These are a set of small functional customizations that allow you to fine-tune the overall experience of the component. With these, you can change text, set custom icons, and toggle the visibility of UI elements.

ThreadHeaderDemo.tsx

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

const messageBubbleView = () => {
  return <div>your custom bubble view</div>;
};

export function ThreadHeaderDemo() {
  const [parentMessage, setParentMessage] =
    React.useState<CometChat.BaseMessage>();
  const [chatWithUser, setChatWithUser] = React.useState<CometChat.User>();

  React.useEffect(() => {
    CometChat.getUser("uid").then((user) => {
      setChatWithUser(user);
    });

    CometChat.getMessageDetails("Parent Message Id").then((message) => {
      setParentMessage(message);
    });
  }, []);

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

What this does: Shows the code for this step.

Below is a list of customizations along with corresponding code snippets

Property	Description	Code
Parent Message	Represents the parent message for displaying threaded conversations.	`parentMessage={message}`
Message Bubble View	A custom view for rendering the message bubble.	`messageBubbleView={(message: CometChat.BaseMessage) => <>Custom Bubble View</>}`
Template	Template for customizing the appearance of the message.	`template={"PASS_CUSTOM_MESSAGE_TEMPLATE"}`
Hide Date	Hides the visibility of the date header.	`hideDate={true}`
Hide Reply Count	Hides the visibility of the reply count.	`hideReplyCount={true}`
Show Scrollbar	Controls the visibility of the scrollbar in the component.	`showScrollbar={true}`
On Error	Callback function triggered when an error occurs.	`onError={(error: CometChat.CometChatException) => console.log(error)}`

Advanced

Separator DateTime Format

The separatorDateTimeFormat property allows you to customize the Date Separator timestamp displayed in the Threaded Message Preview. Default Date Time Format:

new CalendarObject({
    today: `DD MMM, YYYY`,   // Example: "25 Jan, 2025"
    yesterday: `DD MMM, YYYY`, // Example: "25 Jan, 2025"
    otherDays: `DD MMM, YYYY`,  // Example: "25 Jan, 2025"
});

What this does: Shows the code for this step. The following example demonstrates how to modify the Date Separator timestamp format using a custom CalendarObject.

TypeScript

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

// Define a custom date format pattern
function getDateFormat() {
  const dateFormat = new CalendarObject({
    today: `hh:mm A`, // Example: "10:30 AM"
    yesterday: `[yesterday]`, // Example: "yesterday"
    otherDays: `DD/MM/YYYY`, // Example: "25/05/2025"
  });
  return dateFormat;
}

// Apply the custom format to the CometChatThreadHeader component
<CometChatThreadHeader separatorDateTimeFormat={getDateFormat()} />;

What this does: Shows the code for this step.

Fallback Mechanism

If you do not pass any property in the CalendarObject, the component will first check the global configuration. If the property is also missing in the global configuration, it will fallback to the component’s default formatting.

Message SentAt DateTime Format

The messageSentAtDateTimeFormat property allows you to customize the Message SentAt timestamp displayed in the Threaded Message Preview. Default Date Time Format:

new CalendarObject({
    today: "hh:mm A" // Example: "12:00 PM"
    yesterday: "hh:mm A", // Example: "01:00 AM"
    otherDays: `hh:mm A`, // Example: "09:30 PM"
});

What this does: Shows the code for this step. The following example demonstrates how to modify the Message SentAt timestamp format using a custom CalendarObject.

TypeScript

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

// Define a custom date format pattern
function getDateFormat() {
  const dateFormat = new CalendarObject({
    today: `hh:mm A`, // Example: "10:30 AM"
    yesterday: `[yesterday]`, // Example: "yesterday"
    otherDays: `DD/MM/YYYY`, // Example: "25/05/2025"
  });
  return dateFormat;
}

// Apply the custom format to the CometChatThreadHeader component
<CometChatThreadHeader  messageSentAtDateTimeFormat={getDateFormat()} />;

What this does: Shows the code for this step.

Fallback Mechanism

If you do not pass any property in the CalendarObject, the component will first check the global configuration. If the property is also missing in the global configuration, it will fallback to the component’s default formatting.

Common Failure Modes

Symptom	Cause	Fix
Component doesn’t render	`CometChatUIKit.init()` not called or not awaited	Ensure init completes before rendering. See Methods
No parent message displayed	`parentMessage` prop not passed or invalid	Ensure a valid `CometChat.BaseMessage` object is passed
Reply count not updating	Real-time events not connected	Check WebSocket connection status
SSR hydration error	Component uses browser APIs on server	Wrap in `useEffect` or dynamic import with `ssr: false`. See Next.js Integration

Customization matrix

What you want to change	Where	Property/API	Example
Render header	`CometChatThreadHeader`	`parentMessage`	`parentMessage={message}`
Handle close	`CometChatThreadHeader`	`onClose`	`onClose={() => setThread(null)}`

Common pitfalls and fixes

Symptom	Cause	Fix
Header does not render	Parent message missing	Fetch and pass a valid `CometChat.BaseMessage`
Init/login missing	SDK not initialized	Call `CometChatUIKit.init()` and `login()`

FAQ

Where do I get the parent message? Use CometChat.getMessageDetails() or thread context. Can I hide the close button? Use the component props in the Actions section.

​When to use this

​Prerequisites

​Quick start

​Core concepts

​Implementation

​Overview

​Usage

​Integration

​Actions

​Events

​Customization

​Style

​Functionality

​Advanced

Separator DateTime Format

Message SentAt DateTime Format

​Customization matrix

​Common pitfalls and fixes

​FAQ

​Next steps

When to use this

Prerequisites

Quick start

Core concepts

Implementation

Overview

Usage

Integration

Actions

Events

Customization

Style

Functionality

Advanced

Customization matrix

Common pitfalls and fixes

FAQ

Next steps