--- name: cometchat-components description: "Complete catalog of CometChat React UI Kit v6 components. Reference before writing integration code -- never invent component names." license: "MIT" compatibility: "@cometchat/chat-uikit-react ^6; @cometchat/chat-sdk-javascript ^4" metadata: author: "CometChat" version: "3.0.0" tags: "chat cometchat react components catalog reference ui-kit" --- > **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 `` 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 `` 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 `` 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: ```tsx 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: ```tsx // 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):** > ```tsx > const [active, setActive] = useState(null); > // pick the peer the message views need from the selected conversation: > const peer = active?.getConversationWith(); // CometChat.User | CometChat.Group > return ( >
>
> onItemClick={(c) => setActive(c)} /> >
>
> {peer && <> > > > > } >
>
> ); > ``` > 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:** ```tsx 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:** ```tsx ``` **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:** ```tsx ``` **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:** ```tsx ``` **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:** ```tsx setShowDetails(true)} auxiliaryButtonView={} /> ``` **Works with:** CometChatMessageList (below), CometChatCallButtons (in auxiliaryButtonView slot) > ⚠️ **Header `onItemClick` has NO default behavior (ENG-35705).** The kit ships no built-in `` / `` 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 ``: > 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 `` 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 `` to remove the menu item entirely. > 2. **You ARE building threads** — bind `onThreadRepliesClick={(parent) => /* open thread surface */}` and render a separate `` 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. `` 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:** ```tsx 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 `` (or `showSearchBar={true}` > + `onSearchBarClicked` on `CometChatConversations` to swap into > `` on click). Do NOT build custom `` > 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:** ```tsx 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:** ```tsx 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:** ```tsx 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:** ```tsx ``` **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:** ```tsx 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:** ```tsx ``` **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:** ```tsx // At your app root, always mounted: ``` **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:** ```tsx ``` **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:** ```tsx ``` **Works with:** CometChatIncomingCall, CometChatOutgoingCall --- ### CometChatCallLogs Displays a history of past voice and video calls. **Key props:** None required for basic usage. **Usage:** ```tsx ``` **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:** ```tsx 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. 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:** ```tsx import { CometChatNotificationBadge } from "@cometchat/chat-uikit-react"; ``` --- ### useNotificationUnreadCount (hook) React hook returning the current unread-notification count for the logged-in user. Use this when `` doesn't fit your layout — gives you the raw number to render however you like. **Signature:** ```tsx 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. **Usage:** `user` is a **required** prop (the AI assistant user to chat with): ```tsx ``` --- ### CometChatAIAssistantChatHistory Displays past AI assistant interactions. Used alongside `CometChatAIAssistantChat` to show conversation history with the AI. **Usage:** ```tsx ``` --- ### CometChatAIAssistantTools ⚠️ **This is a CLASS, not a renderable component.** You instantiate it with a map of action functions and pass it to `` via the `aiAssistantTools` prop — do NOT render `` (it's a type error). **Prerequisites:** Enable "Conversation Summary" and/or other AI tools in the dashboard. **Usage:** ```tsx const toolkit = new CometChatAIAssistantTools({ /* actionsMap */ }); ``` > **Note:** For detailed props, configuration options, and customization of AI components, query the docs MCP — these components' APIs evolve with CometChat's AI feature releases. ### CometChatStreamMessageBubble Renders a streaming AI message with a typing animation effect. Used internally by AI assistant features. ### CometChatAIAssistantMessageBubble Renders AI assistant response bubbles with special formatting. Used internally by AI features. --- ## 5b. Moderation and utility components These are exported but typically rendered internally by the kit. You may need them for advanced customization. ### CometChatFlagMessageDialog A dialog for reporting/flagging messages. Rendered internally when a user reports a message. ### CometChatMessageInformation Shows message delivery and read receipt details (who received, who read, timestamps). Useful for building a message info panel. --- ## 5c. Text formatters These are not React components — they are formatter classes that customize how text is rendered in message bubbles. Pass them via the `textFormatters` prop on `CometChatMessageList`. | Formatter | Purpose | |---|---| | `CometChatTextFormatter` | Base class for custom formatters | | `CometChatUrlsFormatter` | Auto-links URLs in messages | | `CometChatMentionsFormatter` | Renders @mentions with styling + click handlers | | `CometChatTextHighlightFormatter` | Highlights search terms in messages | | `CometChatRichTextFormatter` | Renders rich text (bold, italic, etc.) | | `CometChatMarkdownFormatter` | Renders markdown syntax in messages | All imported from `@cometchat/chat-uikit-react`. To customize text rendering, create a class extending `CometChatTextFormatter` and pass it in the `textFormatters` array. --- ## 6. Infrastructure These are not visual components -- they handle initialization, login state, and configuration. ### CometChatUIKit The main entry point for initialization and authentication. This is a static class, not a React component. **Key methods:** | Method | Description | |---|---| | `CometChatUIKit.init(settings)` | Initialize the SDK. Returns a Promise. Must be called once before any component renders. | | `CometChatUIKit.login(uid)` | Log in with a user ID (dev mode). Returns `Promise`. Safe to call after a prior login completes (no-op), but **not concurrently** — two overlapping calls throw *"Please wait until the previous login request ends."* Use `cometchat-core`'s `ensureLoggedIn` helper to dedupe. | | `CometChatUIKit.loginWithAuthToken(token)` | Log in with an auth token (production). Returns `Promise`. | | `CometChatUIKit.getLoggedinUser()` | Get the currently logged-in user. Returns `Promise`. | | `CometChatUIKit.logout()` | Log out the current user. Returns a Promise. | | `CometChatUIKit.createUser(user)` | Create a CometChat user (requires Auth Key). For server-side user management, see `cometchat-production`. | | `CometChatUIKit.updateUser(user)` | Update a CometChat user (requires Auth Key). | | `CometChatUIKit.isInitialized()` | Returns `boolean` — whether `init()` has been called. | **Usage** (bare-API illustration — in real code, wrap `login` in an in-flight guard so React StrictMode doesn't fire it twice; see `cometchat-core` § 2 for the `ensureLoggedIn` helper): ```typescript import { CometChatUIKit } from "@cometchat/chat-uikit-react"; await CometChatUIKit.init(settings); await CometChatUIKit.login("cometchat-uid-1"); ``` --- ### CometChatUIKitLoginListener Tracks the logged-in user synchronously. Unlike `CometChatUIKit.getLoggedinUser()` (which is async/Promise-based), this provides **synchronous** access to the current user — useful for guards and conditional rendering. **Key methods:** | Method | Description | |---|---| | `CometChatUIKitLoginListener.getLoggedInUser()` | Returns the currently logged-in `CometChat.User` synchronously, or `null` | **When to use which:** - `CometChatUIKit.getLoggedinUser()` — async, returns a Promise. Use in `useEffect` or async functions. - `CometChatUIKitLoginListener.getLoggedInUser()` — synchronous. Use for immediate checks (e.g., redirect if not logged in, guard a route). --- ### UIKitSettingsBuilder Builder class for creating the settings object passed to `CometChatUIKit.init()`. **Key methods:** | Method | Description | |---|---| | `.setAppId(appId: string)` | Set the CometChat app ID (required) | | `.setRegion(region: string)` | Set the region: `"us"`, `"eu"`, or `"in"` (required) | | `.setAuthKey(authKey: string)` | Set the auth key (required for `login(uid)` in dev mode) | | `.subscribePresenceForAllUsers()` | Enable presence (online/offline) for all users | | `.subscribePresenceForFriends()` | Enable presence only for friends list | | `.subscribePresenceForRoles(roles)` | Enable presence for specific user roles | | `.setAutoEstablishSocketConnection(bool)` | Control WebSocket auto-connect (default: true) | | `.setAdminHost(host)` | Override admin URL (dedicated deployments only) | | `.setClientHost(host)` | Override client URL (dedicated deployments only) | | `.build()` | Returns the settings object | **Usage:** ```typescript import { UIKitSettingsBuilder } from "@cometchat/chat-uikit-react"; const settings = new UIKitSettingsBuilder() .setAppId("your-app-id") .setRegion("us") .setAuthKey("your-auth-key") .subscribePresenceForAllUsers() .build(); ``` --- ## Composition patterns These are the standard ways to combine CometChat components into complete experiences. Use these as starting points, then customize with props. > **Composer note:** Both `CometChatMessageComposer` and > `CometChatCompactMessageComposer` exist. The compact variant includes > rich text editing by default. The sample app uses the compact variant > everywhere. Use whichever fits — the props are identical. ### Multi-conversation (two-pane) The most common pattern. A conversation list on the left, message view on the right. **Key details from the v6 sample app:** - Store the full `CometChat.Conversation` object (not just user/group) — you need it for `activeConversation` highlighting and conversation-level operations - Pass `activeConversation` to `CometChatConversations` so the selected item is visually highlighted - Derive user/group from the conversation at render time using `getConversationWith()` ```tsx import { useState } from "react"; import { CometChatConversations, CometChatMessageHeader, CometChatMessageList, CometChatCompactMessageComposer, } from "@cometchat/chat-uikit-react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; // The message list must scroll inside a flex column without pushing the // composer off-screen. Mirror the sample app's list wrapper. // .cc-msg-list { flex: 1 1 0; min-height: 0; overflow: hidden; } // .cc-msg-list > .cometchat { height: 100%; overflow: hidden; } function MultiConversation() { const [activeConversation, setActiveConversation] = useState(); // Derive user/group from the active conversation const entity = activeConversation?.getConversationWith(); const selectedUser = entity instanceof CometChat.User ? entity : undefined; const selectedGroup = entity instanceof CometChat.Group ? entity : undefined; return (
setActiveConversation(conv)} />
{selectedUser && ( <>
)} {selectedGroup && ( <>
)}
); } ``` --- ### Single thread One chat window for a known user or group. No conversation list. ```tsx import { CometChatMessageHeader, CometChatMessageList, CometChatCompactMessageComposer, } from "@cometchat/chat-uikit-react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; interface SingleThreadProps { user?: CometChat.User; group?: CometChat.Group; } // .cc-msg-list { flex: 1 1 0; min-height: 0; overflow: hidden; } // .cc-msg-list > .cometchat { height: 100%; overflow: hidden; } function SingleThread({ user, group }: SingleThreadProps) { return (
{user && } {group && }
{user && } {group && }
{user && } {group && }
); } ``` To target a specific user, resolve them first: ```tsx const [targetUser, setTargetUser] = useState(); useEffect(() => { CometChat.getUser("seller-uid-123").then(setTargetUser); }, []); if (!targetUser) return null; return ; ``` --- ### Full messenger (tab-based) A tab bar with Chats, Calls, Users, and Groups. Users can browse, start conversations, and make calls. ```tsx import { useState } from "react"; import { CometChatConversations, CometChatCallLogs, CometChatUsers, CometChatGroups, CometChatMessageHeader, CometChatMessageList, CometChatCompactMessageComposer, } from "@cometchat/chat-uikit-react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; // .cc-msg-list { flex: 1 1 0; min-height: 0; overflow: hidden; } // .cc-msg-list > .cometchat { height: 100%; overflow: hidden; } type Tab = "chats" | "calls" | "users" | "groups"; function FullMessenger() { const [activeTab, setActiveTab] = useState("chats"); const [activeConversation, setActiveConversation] = useState(); const [selectedUser, setSelectedUser] = useState(); const [selectedGroup, setSelectedGroup] = useState(); function selectUser(user: CometChat.User) { setSelectedUser(user); setSelectedGroup(undefined); } function selectGroup(group: CometChat.Group) { setSelectedUser(undefined); setSelectedGroup(group); } return (
{/* Tab content */}
{activeTab === "chats" && ( { setActiveConversation(conv); const entity = conv.getConversationWith(); if (entity instanceof CometChat.User) selectUser(entity); else if (entity instanceof CometChat.Group) selectGroup(entity); }} /> )} {activeTab === "calls" && ( { // Call log items show call details, not a message view. // Use the call's participants to start a new call or // navigate to the conversation. }} /> )} {activeTab === "users" && ( )} {activeTab === "groups" && ( )}
{/* Tab bar at the bottom */}
{(["chats", "calls", "users", "groups"] as Tab[]).map((tab) => ( ))}
{selectedUser && ( <>
)} {selectedGroup && ( <>
)}
); } ``` --- ### Threading Threading is NOT automatic. The kit's **default** is `hideReplyInThreadOption={false}` — so a "Reply in Thread" entry shows up in every message's action menu out of the box, **even when the integrator hasn't wired a thread panel**. A user who clicks it sees nothing happen. That's why every `` in the `cometchat-placement` patterns uses `hideReplyInThreadOption` by default. **To enable threading** in an experience that has room for a thread panel (typically a two-pane messenger or route-based chat — not a compact drawer or widget): 1. Remove the `hideReplyInThreadOption` prop from the main `CometChatMessageList`. 2. Wire `onThreadRepliesClick` to capture the thread message (pattern below). 3. Render the thread panel as a side panel or overlay. The thread panel has its OWN `CometChatMessageList` + `CometChatMessageComposer` scoped via `parentMessageId`. Full pattern: ```tsx import { useState } from "react"; import { CometChatMessageList, CometChatMessageComposer, CometChatThreadHeader, } from "@cometchat/chat-uikit-react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; // 1. In your main message view, capture the thread click: { setThreadMessage(message); setShowThread(true); }} /> // 2. Render the thread panel as a side panel: interface ThreadPanelProps { parentMessage: CometChat.BaseMessage; user?: CometChat.User; group?: CometChat.Group; onClose: () => void; } function ThreadPanel({ parentMessage, user, group, onClose }: ThreadPanelProps) { const parentId = parentMessage.getId(); return (
{user && } {group && } {user && } {group && }
); } ``` **Key details:** - `onThreadRepliesClick` receives the full `CometChat.BaseMessage` (not just an ID) - `CometChatThreadHeader` shows the parent message content + close button - The scoped `CometChatMessageList` with `parentMessageId` shows only thread replies - The scoped `CometChatMessageComposer` with `parentMessageId` sends replies to the thread --- ### Search integration Search overlays **alongside** the conversation list — it does NOT replace it. The conversations list stays mounted; search appears as a sibling panel. **Global search (across all conversations):** ```tsx import { useState } from "react"; import { CometChatConversations, CometChatSearch } from "@cometchat/chat-uikit-react"; function ConversationsWithSearch({ onSelectConversation }) { const [showSearch, setShowSearch] = useState(false); return (
{/* Conversations always stay mounted */} setShowSearch(true)} activeConversation={activeConversation} onItemClick={onSelectConversation} /> {/* Search overlays on top when active */} {showSearch && (
{ setShowSearch(false); onSelectConversation(conv); }} onMessageClicked={(msg) => { setShowSearch(false); // navigate to the message's conversation }} />
)}
); } ``` **In-conversation search (within the active chat):** ```tsx // Add search button to the message header: setShowMessageSearch(true)} /> // Show CometChatSearch scoped to the current user/group: {showMessageSearch && ( { setShowMessageSearch(false); // scroll to the message in the message list }} /> )} ``` --- ### Details panel User and group detail panels are **custom-built** — there is no pre-built `CometChatUserDetails` or `CometChatGroupDetails` export in the UI Kit. The v6 sample app has reference implementations at `sample-app/src/components/CometChatDetails/`. **For user details:** build a custom component using `CometChatAvatar` + user info + action buttons (block/unblock). Fetch the pattern from the sample app's `CometChatUserDetails.tsx`. **For group details:** build a custom component and use these real UI Kit components inside it: ```tsx // Open details from the message header: setShowDetails(true)} /> // Group details panel uses real kit components: {showDetails && selectedGroup && (
{/* CometChatGroupMembers is a real kit component */} { // Switch to 1:1 chat with this member }} /> {/* Banning is handled inside CometChatGroupMembers — there is no separate CometChatBannedMembers export in the v6 kit. */}
)} ``` **Important:** `CometChatGroupMembers` requires the `group` prop (it's the only required prop). The component handles member listing, search, scope changes, kick, and ban actions internally. --- ### Calls integration Add voice/video calling to your message view, plus incoming call handling at the app root. ```tsx // 1. Add call buttons to the message header: } /> // 2. Mount incoming call handler at the app root (outside any route): function App() { return ( <> {/* your routes */} ); } ``` `CometChatIncomingCall` must be mounted at the top level so it can show the incoming call overlay regardless of which page the user is on. `CometChatOutgoingCall` and `CometChatOngoingCall` are automatically rendered by the call flow.