> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Understand the component architecture, usage patterns, and all available components in the CometChat React UI Kit.

## Architecture

The UI Kit provides a set of independent, composable React components that wire together into complete chat layouts. A typical two-panel layout uses four core components:

* **CometChatConversations** — sidebar listing recent conversations
* **CometChatMessageHeader** — toolbar showing avatar, name, status, and typing indicator
* **CometChatMessageList** — scrollable message feed with reactions, receipts, and threads
* **CometChatMessageComposer** — rich text input with attachments, mentions, and voice notes

Data flow: selecting a conversation yields a `CometChat.User` or `CometChat.Group` object. Pass that object as a prop (`user` or `group`) to the message components. They handle SDK calls internally — the composer sends messages, the list receives them via real-time listeners.

All components must be rendered inside a `<CometChatProvider>` which provides shared context (theme, locale, events). SDK initialization and login must be completed before the provider mounts.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-llms-scoped-indexes/i4Q5Nw9DEcclqV3C/images/two_panel_layout_without_tabs_react_v7.png?fit=max&auto=format&n=i4Q5Nw9DEcclqV3C&q=85&s=4d8ada09085917afeecf04f8fc246c22" width="1440" height="800" data-path="images/two_panel_layout_without_tabs_react_v7.png" />
</Frame>

```tsx theme={null}
import {
  CometChatProvider,
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

function ChatApp() {
  const [user, setUser] = useState<CometChat.User | undefined>();

  return (
    <CometChatProvider>
      <div style={{ display: "flex", height: "100vh" }}>
        <CometChatConversations onItemClick={(conv) => setUser(conv.getConversationWith())} />
        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
          <CometChatMessageHeader user={user} />
          <CometChatMessageList user={user} />
          <CometChatMessageComposer user={user} />
        </div>
      </div>
    </CometChatProvider>
  );
}
```

***

## Flat API

All components — both feature and base — support the flat API. Render them in a single line with props, and they handle their layout internally.

```tsx theme={null}
<CometChatConversations onItemClick={handleClick} showSearchBar={false} />
```

This is the quickest way to get started. The component renders all its default sub-components (header, list, empty state, loading state, etc.) automatically.

***

## Compound Composition

For full layout control, use the compound pattern. Each feature component is a namespace with sub-components:

```tsx theme={null}
<CometChatConversations.Root onItemClick={handleClick}>
  {/* Only render what you need, and omit sub-components to hide them */}
  <CometChatConversations.View />
  <CometChatConversations.EmptyState />
</CometChatConversations.Root>
```

Key principles:

* **Root** initializes state, fetches data, and provides context to children.
* **Sub-components** read from context and render when their state is active.
* **Omit a sub-component** to hide it, no boolean props needed.
* **Add custom elements** anywhere inside Root alongside the sub-components.

Both APIs produce the same result. The flat API is shorthand for rendering Root with all sub-components in their default order.

***

## Component Categories

Components are organized into three categories:

### Feature Components

Feature components integrate with the CometChat SDK for data fetching, real-time events, and state management. They follow the compound pattern and support both flat and compound APIs.

Feature components:

* Own their data lifecycle (fetch, paginate, refresh)
* Subscribe to real-time SDK events (new messages, presence changes, typing indicators)
* Manage complex state via hooks and reducers
* Provide context to their sub-components

### Base Components

Base components are pure UI building blocks with no SDK integration. They accept props and render UI — no network calls, no real-time events. Feature components compose these internally. Base components support both flat API and compound composition.

***

## Feature Components

All feature components are imported from `@cometchat/chat-uikit-react`.

### Conversations and Lists

| Component | Purpose | Page |
| - | - | - |
| `CometChatConversations` | Scrollable list of recent conversations with real-time updates | [Conversations](/ui-kit/react/components/conversations) |
| `CometChatUsers` | Searchable list of users with selection support | [Users](/ui-kit/react/components/users) |
| `CometChatGroups` | Searchable list of groups with selection support | [Groups](/ui-kit/react/components/groups) |
| `CometChatGroupMembers` | List of group members with role-based actions | [Group Members](/ui-kit/react/components/group-members) |

### Messages

| Component | Purpose | Page |
| - | - | - |
| `CometChatMessageHeader` | Toolbar with avatar, name, status, typing indicator, and call buttons | [Message Header](/ui-kit/react/components/message-header) |
| `CometChatMessageList` | Scrollable message feed with plugin-based bubble rendering | [Message List](/ui-kit/react/components/message-list) |
| `CometChatMessageComposer` | Rich text input with attachments, emoji, voice recording, and formatting | [Message Composer](/ui-kit/react/components/message-composer) |
| `CometChatMessageBubble` | Message bubble container with alignment, receipts, options, and reactions | [Message Bubble](/ui-kit/react/components/message-bubble) |
| `CometChatThreadHeader` | Parent message bubble and reply count for threaded conversations | [Thread Header](/ui-kit/react/components/thread-header) |
| `CometChatPinnedMessages` | Panel of the messages pinned in a conversation | [Pinned Messages](/ui-kit/react/components/pinned-messages) |
| `CometChatSavedMessages` | The current user's saved messages across all conversations | [Saved Messages](/ui-kit/react/components/saved-messages) |
| `CometChatMessageInformation` | Message delivery and read receipt details panel | [Message Information](/ui-kit/react/components/message-information) |
| `CometChatReactions` | Reaction chips bar with reactor list popover | [Reactions](/ui-kit/react/components/reactions) |
| `CometChatReactionList` | Full reactor list with tabs and pagination | [Reaction List](/ui-kit/react/components/reaction-list) |
| `CometChatFlagMessageDialog` | Modal dialog for reporting/flagging messages with reason selection | [Flag Message Dialog](/ui-kit/react/components/flag-message-dialog) |

### Message Bubbles

Message bubble components accept a `message` object and self-extract all required data (text, attachments, metadata, sender info). Unlike v6 where bubbles were purely presentational, v7 bubbles are self-contained — they derive their rendering state directly from the SDK message.

| Component | Message Type | Purpose | Page |
| - | - | - | - |
| `CometChatTextBubble` | `text` | Formatted text with mentions, URLs, markdown, and link previews | [Text Bubble](/ui-kit/react/components/text-bubble) |
| `CometChatImagesBubble` | `image` | Image grid with captions, batch grouping, and a fullscreen gallery | [Image Bubble](/ui-kit/react/components/image-bubble) |
| `CometChatVideosBubble` | `video` | Video grid with poster thumbnails, duration, and a fullscreen viewer | [Video Bubble](/ui-kit/react/components/video-bubble) |
| `CometChatAudiosBubble` | `audio` | Stacked audio player cards with seek, duration, and download | [Audio Bubble](/ui-kit/react/components/audio-bubble) |
| `CometChatVoiceNoteBubble` | `audio` (`voice_note`) | Waveform player for recorded voice notes | [Voice Note Bubble](/ui-kit/react/components/voice-note-bubble) |
| `CometChatFilesBubble` | `file` | Stacked file cards with type icons, size, and download | [File Bubble](/ui-kit/react/components/file-bubble) |
| `CometChatPollBubble` | `extension_poll` | Poll with options, voting, and results | [Poll Bubble](/ui-kit/react/components/poll-bubble) |
| `CometChatStickerBubble` | `extension_sticker` | Sticker image display | [Sticker Bubble](/ui-kit/react/components/sticker-bubble) |
| `CometChatCollaborativeDocumentBubble` | `extension_document` | Document collaboration link with join button | [Collaborative Document Bubble](/ui-kit/react/components/collaborative-document-bubble) |
| `CometChatCollaborativeWhiteboardBubble` | `extension_whiteboard` | Whiteboard collaboration link with join button | [Collaborative Whiteboard Bubble](/ui-kit/react/components/collaborative-whiteboard-bubble) |
| `CometChatCardBubble` | `card` (category) | Developer-defined card messages drawn by the `CometChatCardView` renderer | [Card Bubble](/ui-kit/react/components/card-bubble) |
| `CometChatGroupActionBubble` | `groupMember` | Group membership system messages (joined, left, kicked, banned, scope change) | [Group Action Bubble](/ui-kit/react/components/group-action-bubble) |
| `CometChatCallActionBubble` | `audio`, `video` (call category) | Call status system messages (missed, outgoing, incoming, ended) | [Call Action Bubble](/ui-kit/react/components/call-action-bubble) |
| `CometChatCallBubble` | `meeting` (custom) | Direct call / meeting invitation bubble | [Call Bubble](/ui-kit/react/components/call-bubble) |

### Calling

| Component | Purpose | Page |
| - | - | - |
| `CometChatCallButtons` | Voice and video call initiation buttons | [Call Buttons](/ui-kit/react/components/call-buttons) |
| `CometChatIncomingCall` | Incoming call notification with accept/decline | [Incoming Call](/ui-kit/react/components/incoming-call) |
| `CometChatOutgoingCall` | Outgoing call screen with cancel control | [Outgoing Call](/ui-kit/react/components/outgoing-call) |
| `CometChatCallLogs` | Scrollable list of call history | [Call Logs](/ui-kit/react/components/call-logs) |

### Search and AI

| Component | Purpose | Page |
| - | - | - |
| `CometChatSearch` | Unified search across conversations and messages | [Search](/ui-kit/react/components/search) |
| `CometChatAIAssistantChat` | AI agent chat with streaming, suggestions, and history | [AI Assistant](/ui-kit/react/components/ai-assistant-chat) |

***

## Base Components

Base components are imported from `@cometchat/chat-uikit-react`. They don't have individual doc pages — use the source types and Storybook for reference.

| Component | Purpose |
| - | - |
| `CometChatActionBubble` | Reusable pill-shaped system message bubble (used by GroupActionBubble and CallActionBubble) |
| `CometChatActionSheet` | Bottom sheet with grouped action items |
| `CometChatAvatar` | User/group avatar with image and initials fallback |
| `CometChatButton` | Styled button with icon, text, loading, and variant support |
| `CometChatChangeScope` | Group member role/scope change selector |
| `CometChatCheckbox` | Checkbox input with label and controlled/uncontrolled support |
| `CometChatConfirmDialog` | Confirmation dialog with customizable message and buttons |
| `CometChatContextMenu` | Options menu with top-row icons and overflow dropdown |
| `CometChatConversationStarter` | AI-generated conversation starter suggestions as clickable pills |
| `CometChatConversationSummary` | AI-generated conversation summary display |
| `CometChatDate` | Formatted date/time display with temporal bucketing |
| `CometChatDeleteBubble` | "This message was deleted" placeholder bubble |
| `CometChatDownloadButton` | Download button for file and media attachments |
| `CometChatEmojiKeyboard` | Emoji picker with category tabs and search |
| `CometChatErrorBoundary` | Error isolation wrapper with fallback UI and retry |
| `CometChatFormattingToolbar` | Rich text formatting toolbar (bold, italic, lists, links, code) |
| `CometChatFullScreenViewer` | Full-screen image/media viewer with download |
| `CometChatLinkDialog` | Dialog for inserting or editing hyperlinks |
| `CometChatLinkPopover` | Popover for previewing and editing links inline |
| `CometChatListItem` | Standardized list item with avatar, title, subtitle, and tail |
| `CometChatMediaRecorder` | Audio recording with timer, preview, and submit |
| `CometChatModerationView` | Content moderation indicator and action view |
| `CometChatPopover` | Positioning utility component for popovers and dropdowns |
| `CometChatRadioButton` | Radio button input with label support |
| `CometChatSearchBar` | Search input with clear button and keyboard handling |
| `CometChatSmartReplies` | AI-powered reply suggestions as clickable chips |
| `CometChatThreadView` | Inline thread reply indicator with reply count and unread dot |
| `CometChatToast` | Toast notification for transient feedback messages |
| `CometChatTypingIndicator` | Animated typing indicator with user attribution |

***

## Component API Pattern

All components share a consistent API surface for customization.

### Actions (Callbacks)

Callback props fire on user interactions. Override them to customize behavior:

```tsx theme={null}
<CometChatMessageList
  user={chatUser}
  onThreadRepliesClick={(message) => openThreadPanel(message)}
  onError={(error) => logError(error)}
/>
```

### Filters (RequestBuilder)

List components accept `RequestBuilder` props to control which data loads:

```tsx theme={null}
<CometChatConversations
  conversationsRequestBuilder={
    new CometChat.ConversationsRequestBuilder().setLimit(15)
  }
/>
```

Pass the builder instance — not the result of `.build()`.

### View Props

View props replace the visual content inside a component slot while keeping the default behavior wired:

```tsx theme={null}
<CometChatMessageComposer
  user={chatUser}
  sendButtonView={<MyCustomSendIcon />}
  headerView={<MyCustomHeader />}
  auxiliaryButtonView={<MyExtraButton />}
/>
```

For deeper control, use compound composition to replace entire slots including their behavior.

### CSS Styling

Components use CSS custom properties (design tokens). Override them on the `.cometchat` root or on component-specific selectors:

```css theme={null}
.cometchat {
  --cometchat-primary-color: #6851d6;
  --cometchat-font-family: "Inter", sans-serif;
}

.cometchat-message-list {
  --cometchat-background-color-01: #fafafa;
}
```

Component class names follow BEM convention: `.cometchat-component-name__element--modifier`.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing with CSS variables
  </Card>

  <Card title="Plugins" icon="puzzle-piece" href="/ui-kit/react/plugins/overview">
    Customize message rendering with the plugin system
  </Card>

  <Card title="Event System" icon="bolt" href="/ui-kit/react/event-system">
    Subscribe to real-time events across components
  </Card>

  <Card title="Guides" icon="book" href="/ui-kit/react/guide-threaded-messages">
    Task-oriented tutorials for common patterns
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.