> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-platform-docs-release.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 initializes the SDK connection and provides shared context (theme, locale, events).

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-platform-docs-release/wUW2WqlpbY0fwyuf/images/two_panel_layout_without_tabs_react_v7.png?fit=max&auto=format&n=wUW2WqlpbY0fwyuf&q=85&s=7a79b5140665a8d20e6fee074b4bd5d8" 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

Every feature component can be rendered in a single line. Pass props directly, the component handles its own layout internally.

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

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 use a plain namespace object (compound sub-components) but don't have the callable flat API shorthand.

Examples: Avatar, Button, Date, ContextMenu, SearchBar, ConfirmDialog, Popover, MediaRecorder, MessageBubble, Reactions.

### Bubble Components (Plugins)

Message bubble components (TextBubble, ImageBubble, FileBubble, AudioBubble, VideoBubble, StickerBubble, PollBubble, etc.) are part of the **Plugin system**. Each plugin handles a specific message type and provides the bubble component that renders it.

Bubble components are documented in the [Plugins](/ui-kit/react/v7/plugins/overview) section alongside their parent plugin. See [Plugins Overview](/ui-kit/react/v7/plugins/overview) for how to customize message rendering.

***

## 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/v7/components/conversations)           |
| `CometChatUsers`         | Searchable list of users with selection support                | [Users](/ui-kit/react/v7/components/cometchat-users)                 |
| `CometChatGroups`        | Searchable list of groups with selection support               | [Groups](/ui-kit/react/v7/components/cometchat-groups)               |
| `CometChatGroupMembers`  | List of group members with role-based actions                  | [Group Members](/ui-kit/react/v7/components/cometchat-group-members) |

### Messages

| Component                     | Purpose                                                                   | Page                                                                   |
| ----------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `CometChatMessageHeader`      | Toolbar with avatar, name, status, typing indicator, and call buttons     | [Message Header](/ui-kit/react/v7/components/message-header)           |
| `CometChatMessageList`        | Scrollable message feed with plugin-based bubble rendering                | [Message List](/ui-kit/react/v7/components/message-list)               |
| `CometChatMessageComposer`    | Rich text input with attachments, emoji, voice recording, and formatting  | [Message Composer](/ui-kit/react/v7/components/message-composer)       |
| `CometChatMessageBubble`      | Message bubble container with alignment, receipts, options, and reactions | [Message Bubble](/ui-kit/react/v7/components/message-bubble)           |
| `CometChatThreadHeader`       | Parent message bubble and reply count for threaded conversations          | [Thread Header](/ui-kit/react/v7/components/thread-header)             |
| `CometChatMessageInformation` | Message delivery and read receipt details panel                           | [Message Information](/ui-kit/react/v7/components/message-information) |
| `CometChatReactions`          | Reaction chips bar with reactor list popover                              | [Reactions](/ui-kit/react/v7/components/reactions)                     |
| `CometChatReactionList`       | Full reactor list with tabs and pagination                                | [Reaction List](/ui-kit/react/v7/components/reaction-list)             |
| `CometChatActionBubble`       | Renders group action and call action system messages                      | [Action Bubble](/ui-kit/react/v7/components/action-bubble)             |

### Calling

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

### Search and AI

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

***

## 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                                                            |
| ------------------------------ | ------------------------------------------------------------------ |
| `CometChatAvatar`              | User/group avatar with image and initials fallback                 |
| `CometChatButton`              | Styled button with icon, text, loading, and variant support        |
| `CometChatCheckbox`            | Checkbox input with label and controlled/uncontrolled support      |
| `CometChatChangeScope`         | Group member role/scope change selector                            |
| `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                |
| `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                 |
| `CometChatFlagMessageDialog`   | Modal dialog for reporting/flagging messages with reason selection |
| `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               |
| `CometChatActionSheet`         | Bottom sheet with grouped action items                             |
| `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/v7/theming">
    Customize colors, fonts, and spacing with CSS variables
  </Card>

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

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

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