Message Header - CometChat Docs

AI Integration Quick Reference

Field	Value
Component	`CometChatMessageHeader`
Package	`@cometchat/chat-uikit-react-native`
Import	`import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";`
Purpose	Displays user or group details in the chat toolbar with typing indicators and navigation controls.
Data props	`user` · `group`
Primary output	`onBack()` — pops the chat screen
Other actions	`onError` · `onNewChatButtonClick` · `onChatHistoryButtonClick` — details
View slots	`ItemView` · `LeadingView` · `TitleView` · `SubtitleView` · `TrailingView` · `AuxiliaryButtonView` — details
Styling	`style` prop — tokens and overrides
Prerequisites	`CometChatUIKit.init()` completed and a user logged in
Stitching	Displays user/group info at top of chat, handles back navigation and call buttons (with `CometChatMessageList` · `CometChatMessageComposer`)

Where It Fits

CometChatMessageHeader is a Component that showcases the User or Group details in the toolbar. It presents a typing indicator and a back navigation button for ease of use.

Minimal Render

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

function MessageHeaderDemo() {
  return <CometChatMessageHeader group={group} />;
}

Actions and Events

Callback Props

onError

Fires on internal errors (network failure, auth issue, SDK exception).

onError?: (error: CometChat.CometChatException) => void

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function MessageHeaderWithError() {
  return (
    <CometChatMessageHeader
      group={group}
      onError={(error: CometChat.CometChatException) => {
        console.error("MessageHeader error:", error);
      }}
    />
  );
}

onBack

Fires when the back button in the app bar is pressed. Requires showBackButton={true}.

onBack?: () => void

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

function MessageHeaderWithBack() {
  return (
    <CometChatMessageHeader
      group={group}
      showBackButton={true}
      onBack={() => {
        console.log("Back pressed");
      }}
    />
  );
}

onNewChatButtonClick

Fires when the new chat button is pressed (only applies to AI Assistant users). Allows handling starting a new conversation with the AI assistant.

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

function MessageHeaderWithNewChat() {
  return (
    <CometChatMessageHeader
      user={user}
      onNewChatButtonClick={() => {
        console.log("Starting new AI chat");
      }}
    />
  );
}

onChatHistoryButtonClick

Fires when the chat history button is pressed (only applies to AI Assistant users). Allows handling opening the AI assistant chat history.

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

function MessageHeaderWithHistory() {
  return (
    <CometChatMessageHeader
      user={user}
      onChatHistoryButtonClick={() => {
        console.log("Opening AI chat history");
      }}
    />
  );
}

Custom View Slots

Each slot replaces a section of the default UI. Slots that accept parameters receive the user or group object for customization.

Slot	Signature	Replaces
`ItemView`	`({ user, group }) => JSX.Element`	Entire header layout
`LeadingView`	`({ user, group }) => JSX.Element`	Avatar / left section
`TitleView`	`({ user, group }) => JSX.Element`	Name / title text
`SubtitleView`	`({ user, group }) => JSX.Element`	Status / subtitle text
`TrailingView`	`({ user, group }) => JSX.Element`	Right section next to call buttons
`AuxiliaryButtonView`	`({ user, group }) => JSX.Element`	Replaces default call buttons

TitleView

Custom view for the name / title text.

TitleView?: ({ user, group }) => JSX.Element

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { Text } from "react-native";

function TitleViewDemo() {
  const getTitleView = ({
    user,
    group,
  }: {
    user?: CometChat.User;
    group?: CometChat.Group;
  }) => {
    const name = user ? user.getName() : group?.getName();
    return (
      <Text style={{ fontWeight: 'bold', fontSize: 18 }}>
        {name}
      </Text>
    );
  };

  return <CometChatMessageHeader group={group} TitleView={getTitleView} />;
}

AuxiliaryButtonView

Custom buttons that replace the default call buttons.

AuxiliaryButtonView?: ({ user, group }) => JSX.Element

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { TouchableOpacity, Text } from "react-native";

function AuxiliaryButtonDemo() {
  const getAuxiliaryView = ({
    user,
    group,
  }: {
    user?: CometChat.User;
    group?: CometChat.Group;
  }) => {
    return (
      <TouchableOpacity onPress={() => console.log("Custom action")}>
        <Text>Custom Button</Text>
      </TouchableOpacity>
    );
  };

  return (
    <CometChatMessageHeader
      group={group}
      AuxiliaryButtonView={getAuxiliaryView}
    />
  );
}

ItemView

Custom view for the entire header layout.

ItemView?: ({ user, group }) => JSX.Element

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function ItemViewDemo() {
  const getItemView = ({
    user,
    group,
  }: {
    user?: CometChat.User;
    group?: CometChat.Group;
  }) => {
    const name = user ? user.getName() : group?.getName();
    return (
      <View style={{ padding: 16 }}>
        <Text style={{ fontWeight: 'bold' }}>{name}</Text>
      </View>
    );
  };

  return <CometChatMessageHeader group={group} ItemView={getItemView} />;
}

SubtitleView

Custom view for the subtitle / status text.

SubtitleView?: ({ user, group }) => JSX.Element

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { Text } from "react-native";

function SubtitleViewDemo() {
  const getSubtitleView = ({
    user,
    group,
  }: {
    user?: CometChat.User;
    group?: CometChat.Group;
  }) => {
    if (user) {
      return <Text style={{ color: '#727272' }}>Online</Text>;
    }
    return <Text style={{ color: '#727272' }}>{group?.getMembersCount()} members</Text>;
  };

  return <CometChatMessageHeader group={group} SubtitleView={getSubtitleView} />;
}

LeadingView

Custom view for the avatar / left section.

LeadingView?: ({ user, group }) => JSX.Element

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function LeadingViewDemo() {
  const getLeadingView = ({
    user,
    group,
  }: {
    user?: CometChat.User;
    group?: CometChat.Group;
  }) => {
    const name = user ? user.getName() : group?.getName();
    return (
      <View style={{ width: 40, height: 40, borderRadius: 20, backgroundColor: '#6852D6' }}>
        <Text style={{ color: 'white', textAlign: 'center', lineHeight: 40 }}>
          {name?.charAt(0)}
        </Text>
      </View>
    );
  };

  return <CometChatMessageHeader group={group} LeadingView={getLeadingView} />;
}

TrailingView

Custom view for the right section next to call buttons.

TrailingView?: ({ user, group }) => JSX.Element

Options

A function that returns custom menu items to replace the default menu items entirely. This allows you to define your own set of options for the header menu. Use Cases:

Create a custom options menu with specific actions for your use case.
Add info and search options with custom navigation.
Show different menu options based on user type or permissions.
Hide menu options for specific user types (like agentic users).

App.tsx

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { useMemo } from "react";
//code
const options = useMemo(() => {
  return ({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => {
    // For agentic users, don't show any options menu
    if (agentic) {
      return [];
    }
    
    const menuOptions = [];

    // Add info option first
    if (group && loggedInUser) {
      menuOptions.push({
        text: 'Group Info',
        onPress: () => {
          navigation.navigate('GroupInfo', { group });
        },
        icon: <Icon name="info" width={20} height={20} color={theme.color.iconSecondary} />,
      });
    } else if (user && !user.getBlockedByMe()) {
      menuOptions.push({
        text: 'User Info',
        onPress: () => {
          navigation.navigate('UserInfo', { user });
        },
        icon: <Icon name="info" width={20} height={20} color={theme.color.iconSecondary} />,
      });
    }

    // Then add search option
    menuOptions.push({
      text: 'Search',
      onPress: () => {
        if (group) {
          navigation.navigate('SearchMessages', { group });
        } else if (user) {
          navigation.navigate('SearchMessages', { user });
        }
      },
      icon: <Icon name="search" width={20} height={20} color={theme.color.iconSecondary} />,
    });

    return menuOptions;
  };
}, [navigation, group, user, theme, agentic, loggedInUser]);

return (
  <CometChatMessageHeader
    group={group}
    options={options}
  />
);

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { TouchableOpacity, Text } from "react-native";

function TrailingViewDemo() {
  const getTrailingView = ({
    user,
    group,
  }: {
    user?: CometChat.User;
    group?: CometChat.Group;
  }) => {
    return (
      <TouchableOpacity onPress={() => console.log("Menu pressed")}>
        <Text>⋮</Text>
      </TouchableOpacity>
    );
  };

  return <CometChatMessageHeader group={group} TrailingView={getTrailingView} />;
}

Pinned Messages

CometChatMessageHeader can show a button that opens a conversation’s pinned messages. It is off by default — set showPinnedMessagesButton to render it, and onPinnedMessagesPress to handle the tap.

showPinnedMessagesButton?: boolean   // default: false
onPinnedMessagesPress?: () => void

The component does not navigate for you: it raises the tap and you decide where to go, so the button works with any navigation setup.

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";
import { useNavigation } from "@react-navigation/native";

function ChatHeader({ user, group }) {
  const navigation = useNavigation<any>();

  return (
    <CometChatMessageHeader
      user={user}
      group={group}
      showPinnedMessagesButton={true}
      onPinnedMessagesPress={() =>
        navigation.navigate("PinnedMessages", { user, group })
      }
    />
  );
}

Render CometChatPinnedMessages on that screen, scoped to the same user/group. See the Pin & Save Messages guide for the full flow.

Pin must be enabled for your app in the CometChat Dashboard. The UI Kit reads that setting at login, so the button opens a panel that stays empty if the feature is off for your app.

Thread Subscription

When the header is given a parentMessage, it switches to thread mode and renders a bell that subscribes the user to that thread or unsubscribes them. Without parentMessage there is no thread to follow, so no bell renders — a conversation header can never accidentally show a thread control.

parentMessage?: CometChat.BaseMessage        // set this to enter thread mode
threadSubscriptionVisibility?: boolean       // default: true
onThreadSubscriptionChange?: (subscribed: boolean) => void

import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";
import { Text } from "react-native";

function ThreadHeader({
  parentMessage,
  user,
  group,
  onBack,
}: {
  parentMessage: CometChat.BaseMessage;
  user?: CometChat.User;
  group?: CometChat.Group;
  onBack: () => void;
}) {
  return (
    <CometChatMessageHeader
      user={user}
      group={group}
      // Thread mode — this is what renders the bell.
      parentMessage={parentMessage}
      showBackButton={true}
      onBack={onBack}
      onThreadSubscriptionChange={(subscribed) =>
        console.log(subscribed ? "Following this thread" : "No longer following")
      }
      // A thread bar names the screen, not the person, and calls belong to a
      // conversation rather than a thread.
      hideVoiceCallButton={true}
      hideVideoCallButton={true}
      LeadingView={() => <></>}
      TitleView={() => <Text>Thread</Text>}
    />
  );
}

The bell manages itself: it reads the current state, flips optimistically on tap, reverts if the server rejects the change, and stays in step with a toggle made from the message action sheet. To hide it on a particular screen, pass threadSubscriptionVisibility={false}:

<CometChatMessageHeader parentMessage={parentMessage} threadSubscriptionVisibility={false} />

The same subscribe/unsubscribe action is also offered as a message option on CometChatMessageList, hidden independently with hideThreadSubscriptionOption — an integrator may want one surface and not the other. See the Thread Subscription guide.

Styling

Using Style you can customize the look and feel of the component in your app. Pass a styling object as a prop to the CometChatMessageHeader component.

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

function StylingDemo() {
  return (
    <CometChatMessageHeader
      group={group}
      style={{
        avatarStyle: {
          containerStyle: {
            borderRadius: 8,
            backgroundColor: "#FBA46B",
          },
          imageStyle: {
            borderRadius: 8,
          },
        },
        titleTextStyle: {
          color: "#F76808",
        },
        callButtonStyle: {
          audioCallButtonIconStyle: {
            tintColor: "#F76808",
          },
          videoCallButtonIconStyle: {
            tintColor: "#F76808",
          },
        },
      }}
    />
  );
}

Visibility Props

Property	Description	Code
`showBackButton`	Toggle visibility of the back button in the app bar	`showBackButton?: boolean`
`hideVoiceCallButton`	Toggle visibility of the voice call button	`hideVoiceCallButton?: boolean`
`hideVideoCallButton`	Toggle visibility of the video call button	`hideVideoCallButton?: boolean`
`usersStatusVisibility`	Toggle user status visibility	`usersStatusVisibility?: boolean`
`hideNewChatButton`	Toggle visibility of new chat button for AI Assistants	`hideNewChatButton?: boolean`
`hideChatHistoryButton`	Toggle visibility of chat history button for AI Assistants	`hideChatHistoryButton?: boolean`
`showPinnedMessagesButton`	Toggle visibility of the pinned-messages button. Off by default	`showPinnedMessagesButton?: boolean`
`threadSubscriptionVisibility`	Toggle visibility of the thread subscription bell. Requires `parentMessage`	`threadSubscriptionVisibility?: boolean`

options

Custom menu items for the header options menu.

options?: ({ user, group }) => MenuItemInterface[]

import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function OptionsDemo() {
  const getOptions = ({
    user,
    group,
  }: {
    user?: CometChat.User;
    group?: CometChat.Group;
  }) => {
    return [
      {
        text: "View Profile",
        onPress: () => { /* view profile logic */ },
      },
      {
        text: "Block User",
        onPress: () => { /* block logic */ },
      },
    ];
  };

  return <CometChatMessageHeader user={user} options={getOptions} />;
}

Next Steps

Message List

Display the list of messages in a conversation

Message Composer

Compose and send messages in a chat

Messages

Complete messaging interface with header, list, and composer

Component Styling

Customize the appearance of UI Kit components

​Where It Fits

​Minimal Render

​Actions and Events

​Callback Props

​onError

​onBack

​onNewChatButtonClick

​onChatHistoryButtonClick

​Custom View Slots

​TitleView

​AuxiliaryButtonView

​ItemView

​SubtitleView

​LeadingView

​TrailingView

​Options

​Pinned Messages

​Thread Subscription

​Styling

​Visibility Props

​options

​Next Steps

Message List

Message Composer

Messages

Component Styling

Where It Fits

Minimal Render

Actions and Events

Callback Props

onError

onBack

onNewChatButtonClick

onChatHistoryButtonClick

Custom View Slots

TitleView

AuxiliaryButtonView

ItemView

SubtitleView

LeadingView

TrailingView

Options

Pinned Messages

Thread Subscription

Styling

Visibility Props

options

Next Steps