cometchat-components

Ground truth: @cometchat/chat-uikit-react@^6 component catalog (installed package types) + docs/ui-kit/react. Official docs: https://www.cometchat.com/docs/ui-kit/react/components-overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.

Purpose

This is the single source of truth for CometChat React UI Kit v6 component names, props, and usage. Check this catalog before writing any <CometChat*> JSX. If a component is not listed here, it does not exist in the exported API.

All components are imported from @cometchat/chat-uikit-react. All SDK types are imported from @cometchat/chat-sdk-javascript.

When to use

• Any React-family integration emitting <CometChat*> JSX: Vite + React, Next.js (App or Pages Router), React Router v6/v7, Astro with React islands.
• Before scaffolding any chat surface (conversations, messages, users, groups, calls UI).
• When verifying a component name or prop signature — this catalog is authoritative; the kit's node_modules/@cometchat/chat-uikit-react/dist/types/ is the runtime source of truth that backs it.

When NOT to use

• React Native (Expo or bare) — load cometchat-native-components. Class names are similar but prop conventions diverge (RN uses onItemPress, web uses onItemClick — runtime smoke 2026-06-02 confirmed). Cross-family copy-paste produces silent broken event bindings.
• Angular — load cometchat-angular-components. Angular kit class names are Component-suffixed (CometChatConversationsComponent not CometChatConversations — verified by runtime smoke 2026-06-02), HTML selectors are kebab-case, event bindings use round brackets for @Output() events. Different shape entirely.
• Native Android — load cometchat-android-v6-{compose,kotlin}-components (V6) or cometchat-android-v5-components (V5). Different package namespaces (com.cometchat.uikit.compose.* vs com.cometchat.chatuikit.*) — never reuse React component names.
• iOS V5 — load cometchat-ios-components. UIKit Swift surface; CometChatConversations() zero-arg initializer + .set(group: ...) pattern; nothing like the React prop API.
• Flutter V5 / V6 — load cometchat-flutter-{v5,v6}-components. Dart widget API with named parameters; V5 GetX vs V6 Bloc state-management split changes lifecycle.
• Theming-only tasks — load cometchat-theming (CSS variables, recipes) for color/font customization without component changes.
• SDK-only chat (no UI Kit) — this catalog assumes UI Kit components. If a future skill ships for the pure-SDK path (no <CometChat*> JSX), defer to it; today the closest analog is the SDK-only patterns inside cometchat-react-calls §4c.

Importing CometChat.User / CometChat.Group / etc.

CometChat.User, CometChat.Group, CometChat.BaseMessage, CometChat.Conversation, CometChat.GroupMember, CometChat.TextMessage are classes (runtime values), not pure types. That means the import strategy depends on how you use them:

Pattern A — you call the class as a value or use it with instanceof. Use a plain value import:

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

if (entity instanceof CometChat.User) { ... }
const user = await CometChat.getUser(uid);

Pattern B — you use it only as a type annotation, nowhere else. Two options:

// Option 1: value import, reference the type via the namespace — TS lets this slide
// because CometChat is a class-namespace
import { CometChat } from "@cometchat/chat-sdk-javascript";
function renderHeader(user: CometChat.User) { ... }

// Option 2: explicit type-only import
import type { CometChat } from "@cometchat/chat-sdk-javascript";
function renderHeader(user: CometChat.User) { ... }

Do NOT mix these. If you write import type { CometChat } and then try entity instanceof CometChat.User, TypeScript strips the import at compile time and the code throws at runtime. If you write import { CometChat } but only reference CometChat.User as a type, noUnusedLocals can flag it (TS6133).

Safest default: use the plain value import (import { CometChat }). It always works; the TS6133 warning only fires in strict noUnusedLocals configs and can be fixed by actually using the runtime value (e.g. instanceof CometChat.User) or by adding an eslint-disable-next-line if you truly only need the type.

---

1. Core messaging

⛔ STOP — only the components in THIS catalog exist. Do not invent or recall component names from v4/older memory. Before emitting ANY CometChat* component, confirm it appears in this catalog (or the kit's exports). If it's not here, it does not exist — using it produces an unresolved-import build failure or a blank screen. This is the #1 failure class on this skill.

The real v6 component set (the ONLY ones — import { … } from "@cometchat/chat-uikit-react"): CometChatConversations, CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer (+ CometChatCompactMessageComposer), CometChatUsers, CometChatGroups, CometChatMessageInformation (+ the calling/feature components in their own catalogs).

Commonly hallucinated names that were REMOVED in v6 (verified absent from the kit exports) — do NOT use: the all-in-one composites CometChatConversationsWithMessages, CometChatUsersWithMessages, CometChatGroupsWithMessages, the CometChatMessages composite, and the CometChatUI god-component. There is no single "conversations + messages" component in v6 — you compose the two panes yourself (recipe below). (Note: CometChatMessages/CometChatConversationsWithMessages DO still exist in the Flutter v6 kit — this removal is web/RN/Angular. Always check the per-family catalog.)

The canonical two-pane experience (what "CometChatConversationsWithMessages" used to do — now hand-composed):

const [active, setActive] = useState<CometChat.Conversation | null>(null);
// pick the peer the message views need from the selected conversation:
const peer = active?.getConversationWith(); // CometChat.User | CometChat.Group
return (
  <div style={{ display: "flex", height: "100%" }}>
    <div style={{ width: 320 }}>
      <CometChatConversations activeConversation={active ?? undefined}
        onItemClick={(c) => setActive(c)} />
    </div>
    <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
      {peer && <>
        <CometChatMessageHeader {...(peer instanceof CometChat.User ? { user: peer } : { group: peer })} />
        <CometChatMessageList   {...(peer instanceof CometChat.User ? { user: peer } : { group: peer })} />
        <CometChatMessageComposer {...(peer instanceof CometChat.User ? { user: peer } : { group: peer })} />
      </>}
    </div>
  </div>
);

A CometChatMessageHeader/List/Composer takes EITHER user= OR group= (never both) — derive it from the clicked conversation. Conversations-list-only and single-conversation-only are both valid subsets of this.

These are the components you use to build a chat experience. Most integrations use some combination of these seven.

CometChatConversations

Renders a scrollable list of the logged-in user's conversations (both 1:1 and group).

Key props:

Prop	Type	Description
activeConversation	CometChat.Conversation	Highlights the currently selected conversation
onItemClick	(conversation: CometChat.Conversation) => void	Called when the user taps a conversation
showSearchBar	boolean	Shows a basic name-filter search bar above the list
onSearchBarClicked	() => void	Called when the search bar is clicked (use to swap in CometChatSearch for full search)
conversationsRequestBuilder	CometChat.ConversationsRequestBuilder	Customize which conversations to fetch (filters, limits)

Usage:

<CometChatConversations
  activeConversation={activeConversation}
  onItemClick={(conversation) => setActiveConversation(conversation)}
/>

Works with: CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer (two-pane layout)

---

CometChatMessageList

Renders messages for a specific user or group conversation. Supports threaded views via parentMessageId.

Key props:

Prop	Type	Description
user	CometChat.User	Show messages with this user (mutually exclusive with group)
group	CometChat.Group	Show messages in this group (mutually exclusive with user)
parentMessageId	number	If set, shows only replies to this message (thread view)
templates	CometChatMessageTemplate[]	Custom message bubble templates
messagesRequestBuilder	CometChat.MessagesRequestBuilder	Customize message fetching

Usage:

<CometChatMessageList user={selectedUser} />

Works with: CometChatMessageHeader (above), CometChatMessageComposer (below)

---

CometChatMessageComposer

A text input with send button, attachment options, and emoji support. Sends messages to the specified user or group.

Key props:

Prop	Type	Description
user	CometChat.User	Send messages to this user (mutually exclusive with group)
group	CometChat.Group	Send messages to this group (mutually exclusive with user)
parentMessageId	number	If set, sends replies to this message (thread mode)
onSendButtonClick	(message: CometChat.BaseMessage) => void	Called when send is clicked

Usage:

<CometChatMessageComposer user={selectedUser} />

Works with: CometChatMessageList (above), CometChatMessageHeader (at top of message area)

---

CometChatCompactMessageComposer

A rich-text variant of the message composer with formatting toolbar (bold, italic, code, etc.). Same props as CometChatMessageComposer.

Prefer this for new integrations. The v6 sample app uses CometChatCompactMessageComposer everywhere — rich-text formatting is the modern default. Both work; reach for CometChatMessageComposer (the basic variant) only if you have a specific reason to skip the formatting toolbar (e.g., a stripped-down marketplace ping where plain text is the entire UX).

Key props:

Prop	Type	Description
user	CometChat.User	Send messages to this user
group	CometChat.Group	Send messages to this group
parentMessageId	number	Thread mode
onSendButtonClick	(message: CometChat.BaseMessage) => void	Called on send

Usage:

<CometChatCompactMessageComposer user={selectedUser} />

Works with: Same as CometChatMessageComposer -- drop-in replacement for rich text

---

CometChatMessageHeader

Displays the name, avatar, and status of the user or group at the top of a message view. Supports a menu slot and search.

Key props:

Prop	Type	Description
user	CometChat.User	Show header for this user
group	CometChat.Group	Show header for this group
onItemClick	() => void	Called when the header info area is clicked (use to open details panel)
onBack	() => void	Called when back button is clicked
auxiliaryButtonView	JSX.Element	Custom button area (e.g., CometChatCallButtons)
showBackButton	boolean	Show a back button (for mobile/nested views)
showSearchOption	boolean	Show a search icon in the header
onSearchOptionClicked	() => void	Called when search icon is clicked
hideVideoCallButton	boolean	Hide the video call button
hideVoiceCallButton	boolean	Hide the voice call button

Usage:

<CometChatMessageHeader
  user={selectedUser}
  onItemClick={() => setShowDetails(true)}
  auxiliaryButtonView={<CometChatCallButtons user={selectedUser} />}
/>

Works with: CometChatMessageList (below), CometChatCallButtons (in auxiliaryButtonView slot)

⚠️ Header onItemClick has NO default behavior (ENG-35705). The kit ships no built-in <CometChatUserDetails /> / <CometChatGroupDetails /> panel — clicking the header name/avatar produces zero visible feedback unless YOU pass an onItemClick callback. Four testers flagged this as "kit feels broken." Rule when emitting <CometChatMessageHeader>:

1. Either provide an onItemClick that opens a details panel YOU built (use the sample-app reference at sample-app/src/components/CometChatDetails/), OR
2. Wrap the header in a clickable region that goes elsewhere, so the avatar+name doesn't look like a dead end. (There is no showInfo prop on CometChatMessageHeader — don't emit it.) Do NOT mount the header bare without an onItemClick — it's a customer-facing dead end.

⚠️ Reply in Thread action requires the host to wire the thread panel (ENG-35705 — clarified 2026-06-02 from "broken" to "requires wiring"). The kit's <CometChatMessageList> renders a "Reply in Thread" item in the message-options menu and fires onThreadRepliesClick(parentMessage) when tapped — but the kit does NOT ship a default thread screen. If the host doesn't bind onThreadRepliesClick to a thread surface, the action visually does nothing (callback fires; no UI follows). Two paths:

1. You're not building threads — set hideReplyInThreadOption={true} on <CometChatMessageList> to remove the menu item entirely.
2. You ARE building threads — bind onThreadRepliesClick={(parent) => /* open thread surface */} and render a separate <CometChatMessageList parentMessageId={parent.getId()} /> inside the thread surface. Sample app's pattern: cometchat-uikit-react-v6/sample-app/src/components/CometChatMessages/CometChatMessages.tsx:74 wires this via parent component routing.

The dispatcher hard rule still defaults to option 1 (hide threads) because most integrations don't want them. Restated here at point-of-use so the catalog reader makes a conscious choice.

⚠️ Message Privately action — hide it via the kit prop if it misbehaves (ENG-35705). In group chats the message-options menu shows a "Message Privately" item that may do nothing on click in some kit versions. <CometChatMessageList> exposes hideMessagePrivatelyOption={true} to remove it cleanly — set that rather than living with a dead menu item.

---

CometChatSearch

Full-featured dual-scope search: searches across conversations AND messages with filter chips. This is the primary search component.

Key props:

Prop	Type	Description
onConversationClicked	(conversation: CometChat.Conversation) => void	Called when a conversation result is clicked
onMessageClicked	(message: CometChat.BaseMessage) => void	Called when a message result is clicked

Usage:

<CometChatSearch
  onConversationClicked={(conv) => navigateToConversation(conv)}
  onMessageClicked={(msg) => scrollToMessage(msg)}
/>

Works with: CometChatConversations (replaces the list when search is active)

Hard rule — never roll your own search. Any request involving "search", "find messages", "search conversations", or "search across conversations" MUST use <CometChatSearch> (or showSearchBar={true}

• onSearchBarClicked on CometChatConversations to swap into <CometChatSearch> on click). Do NOT build custom <input type="search"> bars, hand-rolled result lists, or filter UIs — they bypass the SDK's pagination, highlighting, and dual-scope (conversations + messages) matching that ship with the built-in component.

---

CometChatThreadHeader

Header bar for a threaded message view. Shows the parent message and a close button.

Key props:

Prop	Type	Description
parentMessage	CometChat.BaseMessage	The message that started the thread
onClose	() => void	Called when the user closes the thread view

Usage:

<CometChatThreadHeader
  parentMessage={threadParentMessage}
  onClose={() => setThreadParent(null)}
/>

Works with: CometChatMessageList (with parentMessageId), CometChatMessageComposer (with parentMessageId)

---

2. Lists and selection

Components for browsing and selecting users, groups, and group members.

CometChatUsers

A scrollable list of users. Used for starting new conversations or browsing the user directory.

Key props:

Prop	Type	Description
onItemClick	(user: CometChat.User) => void	Called when a user is selected
usersRequestBuilder	CometChat.UsersRequestBuilder	Customize which users to fetch

Usage:

<CometChatUsers onItemClick={(user) => startConversation(user)} />

Works with: CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer (after selection)

---

CometChatGroups

A scrollable list of groups. Used for browsing and joining groups.

Key props:

Prop	Type	Description
onItemClick	(group: CometChat.Group) => void	Called when a group is selected
groupsRequestBuilder	CometChat.GroupsRequestBuilder	Customize which groups to fetch

Usage:

<CometChatGroups onItemClick={(group) => openGroup(group)} />

Works with: CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer (after selection)

---

CometChatGroupMembers

Displays members of a specific group with their roles (owner, admin, member).

Key props:

Prop	Type	Description
group	CometChat.Group	The group whose members to display (required)
onItemClick	(member: CometChat.GroupMember) => void	Called when a member is selected

Usage:

<CometChatGroupMembers group={selectedGroup} />

Works with: Group details panel, CometChatGroups

---

CometChatSearchBar

A standalone search input component. Used for filtering within other components.

Key props:

Prop	Type	Description
onChange	(input: { value?: string }) => void	Called as the user types — read input.value
searchText	string	Controlled input value
placeholderText	string	Placeholder text

Usage:

<CometChatSearchBar onChange={(input) => filterUsers(input.value ?? "")} />

Works with: Any list component for client-side filtering

---

3. Calls

Components for voice and video calling.

CometChatCallButtons

Renders voice and video call buttons. Typically placed in the auxiliaryButtonView prop of CometChatMessageHeader.

Key props:

Prop	Type	Description
user	CometChat.User	Call this user
group	CometChat.Group	Call this group
hideVideoCallButton	boolean	Hide the video call button
hideVoiceCallButton	boolean	Hide the voice call button

Usage:

<CometChatCallButtons user={selectedUser} />

Works with: CometChatMessageHeader (via its auxiliaryButtonView prop — there is no menu prop), CometChatIncomingCall (at app root)

---

CometChatIncomingCall

Renders an incoming call notification overlay. Mount this at the app root so it can show incoming calls from any screen.

Key props: None required -- it auto-listens for incoming call events.

Usage:

// At your app root, always mounted:
<CometChatIncomingCall />

Works with: CometChatCallButtons (triggers outgoing calls that the other user sees as incoming)

---

CometChatOutgoingCall

Renders the outgoing call screen (ringing state). Automatically shown when the user initiates a call.

Key props: None required -- auto-triggered by call initiation.

Usage:

<CometChatOutgoingCall />

Works with: CometChatCallButtons

---

CometChatOngoingCall

Renders the active call screen with video feeds, mute/unmute, and hang-up controls.

Key props: None required -- auto-triggered when a call connects.

Usage:

<CometChatOngoingCall />

Works with: CometChatIncomingCall, CometChatOutgoingCall

---

CometChatCallLogs

Displays a history of past voice and video calls.

Key props: None required for basic usage.

Usage:

<CometChatCallLogs />

Works with: Tab-based layouts (as one of the tabs alongside Conversations, Users, Groups)

---

4. Interactions

Components for message reactions and emoji.

CometChatReactions

Displays reaction badges on a message (e.g., thumbs-up x3). Automatically rendered inside message bubbles when reactions are enabled.

Key props: Typically used internally by the message list. Not usually instantiated directly.

---

CometChatReactionList

Shows a detailed list of who reacted with what emoji on a specific message.

Key props: Used internally. Shown when the user clicks on a reaction badge.

---

5. Notifications (catalog gap closed 2026-06-02)

Three notification-related exports that were missing from this catalog before today. Verified against cometchat-uikit-react-v6/src/index.ts:167-169.

CometChatNotificationFeed

A scrollable inbox of campaign / promotional notifications. Renders a list view; integrators wire it as a dropdown or dedicated route.

Key props: onItemClick: (feedItem: NotificationFeedItem) => void to handle taps; notificationFeedRequestBuilder (and notificationCategoriesRequestBuilder) to filter — NOT notificationsRequestBuilder.

Usage:

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

// feedItem is a NotificationFeedItem (campaign notification) — it has no
// `conversationId`; route off its own fields / deep-link payload.
<CometChatNotificationFeed onItemClick={(feedItem) => handleNotification(feedItem)} />

---

CometChatNotificationBadge

A small unread-count pill, designed to attach to a nav item / icon. Auto-updates as new notifications arrive via the kit's notification feed listener.

Key props: All optional — defaults to showing the current unread count of the logged-in user. Style with the standard CometChat*Style pattern.

Usage:

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

<button onClick={openNotificationFeed}>
  <BellIcon />
  <CometChatNotificationBadge />
</button>

---

useNotificationUnreadCount (hook)

React hook returning the current unread-notification count for the logged-in user. Use this when <CometChatNotificationBadge /> doesn't fit your layout — gives you the raw number to render however you like.

Signature:

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

const { count, isLoading } = useNotificationUnreadCount({ /* optional UseNotificationUnreadCountOptions */ });

Internally subscribes to the same notification stream as CometChatNotificationBadge — using both is safe (single shared source).

---

CometChatEmojiKeyboard

A full emoji picker. Automatically rendered inside the message composer when the emoji button is clicked.

Key props: Used internally by CometChatMessageComposer. Not usually instantiated directly.

---

CometChatReactionInfo

Tooltip or popover showing reaction details on hover.

Key props: Used internally by the message list. Not usually instantiated directly.

---

5. AI

AI-powered assistant components. These require AI features (Smart Chat Features) to be enabled in your CometChat dashboard at Chat & Messaging → Features → Smart Chat Features.

CometChatAIAssistantChat

An AI chatbot interface that users can interact with for automated responses. Typically rendered inside a panel or modal triggered from the message header.

Prerequisites: Enable "Conversation Starter" and/or "Smart Replies" in the dashboard.