# Building Cards
Source: https://www.cometchat.com/docs/card-builder/building-cards

Walk through the Card Builder editor — the canvas, the element palette, and the properties panel — to design, style, and save a card in the CometChat Dashboard.

This guide walks through designing a card in Card Builder, from a blank canvas to a saved template.

<Frame>
  <video aria-label="Building a card in Card Builder — adding a progress bar and status rows with variables" />
</Frame>

## The Editor

Card Builder is organized into three areas:

| Area                   | What it does                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------- |
| **Palette** (left)     | The elements and ready-made components you can add to a card.                         |
| **Canvas** (center)    | A live preview of your card as you build it. Select an element here to edit it.       |
| **Properties** (right) | Settings for the selected element, the card structure (tree), and overall card style. |

The top bar holds the card name, import and export, undo/redo, and **Save**.

<Frame>
  <img alt="Card Builder editor: the element palette on the left, the card canvas in the center, and the structure tree and properties on the right" />
</Frame>

## 1. Start a Card

When you open Card Builder, choose a starting point:

* **Template library** — pick a ready-made template (Product Card, Order Confirmation, and more) and customize it.
* **Blank card** — start from scratch.

<Frame>
  <img alt="The Card Builder template library, showing saved templates and ready-made templates to start from" />
</Frame>

## 2. Add Elements

Click an element in the palette to add it to your card. New elements are placed relative to your current selection — inside a selected layout element, or after the selected element. You can add content such as text, images, and buttons, and arrange them using layout elements like rows, columns, and grids. For the full list, see [Elements & Actions](/docs/card-builder/elements).

You can also add a **component** — a pre-built group of elements (for example a product card or an order timeline) — and then edit its pieces.

## 3. Arrange the Layout

By default, elements stack vertically. To change the layout:

* **Row** — place elements side by side.
* **Column** — group elements vertically inside a row.
* **Grid** — arrange elements in a grid.
* **Carousel** — let users scroll horizontally through items.

Use the structure tree in the properties panel to drag elements into a new order, nest them inside layouts, or remove them.

## 4. Style the Card

Select an element to edit its properties, or click an empty area of the card to edit the overall **card style**:

* **Background** — set a fill color, or make it transparent.
* **Corner radius** — round the card's corners.
* **Border** — add a border color and width.
* **Padding** — control the spacing inside the card.

### Light and Dark Mode

Colors are set separately for **light** and **dark** mode, so your card looks right in both. You can set a color for one mode and leave the other transparent.

## 5. Make It Interactive

Add an **action** to a button, icon button, link, or chip so it does something when tapped — open a URL, start a chat, send a message, make a call, and more. See [Elements & Actions](/docs/card-builder/elements#actions) for the full list.

## 6. Use Variables

Insert [variables](/docs/card-builder/elements#variables) — placeholders such as `{{user.name}}` or `{{order.id}}` — from the variable picker wherever you enter text or a URL. They're filled with real values when the card is sent, so a single card personalizes for every recipient. Available variables depend on where the card is used.

## 7. Notifications (Push)

A card is a message in CometChat. When that message triggers a push notification, the push can't show the full rich card — so the **Notification** tab is where you define the **notification text** for the message: the title and body shown in the push. A device preview shows how it will appear, and you can insert [variables](#6-use-variables) into the title and body so the notification is personalized per recipient.

<Frame>
  <img alt="The Notification tab in Card Builder, with a device preview showing how the push notification appears" />
</Frame>

## 8. Save

Give the card a name in the top bar and click **Save**. Saved cards are stored as templates so you can open them again from the template library, edit them, and reuse them.

***

Next: [Elements & Actions](/docs/card-builder/elements) — a reference of everything you can add to a card.


# Elements & Actions
Source: https://www.cometchat.com/docs/card-builder/elements

A reference of everything a card can contain — content, layout, and interactive elements, the actions a card can trigger, and the ready-made components you can add to a card.

A card is made up of **elements** arranged on the canvas. Interactive elements can trigger **actions**, and **components** give you ready-made groups of elements to start from. This page lists what's available.

## Elements

### Content

| Element        | Description                                                |
| -------------- | ---------------------------------------------------------- |
| **Text**       | A line or paragraph of text, with heading and body styles. |
| **Markdown**   | Rich text written in Markdown.                             |
| **Image**      | An image from a URL.                                       |
| **Icon**       | An icon from the built-in library or a custom image.       |
| **Avatar**     | A circular user or entity image.                           |
| **Badge**      | A small label, often for status or counts.                 |
| **Chip**       | A compact, tappable tag.                                   |
| **Code block** | Pre-formatted, monospaced text.                            |

### Layout

| Element       | Description                                       |
| ------------- | ------------------------------------------------- |
| **Row**       | Arranges elements side by side.                   |
| **Column**    | Groups elements vertically, usually inside a row. |
| **Grid**      | Arranges elements in a grid.                      |
| **Accordion** | Collapsible sections that expand on tap.          |
| **Tabs**      | Switch between sections of content.               |
| **Divider**   | A horizontal line to separate content.            |
| **Spacer**    | Empty space to control vertical rhythm.           |

Rows, columns, and grids can also have their own background color, corner radius, and border.

### Interactive

| Element         | Description                                  |
| --------------- | -------------------------------------------- |
| **Button**      | A labeled button that triggers an action.    |
| **Icon button** | An icon-only button that triggers an action. |
| **Link**        | Tappable text that triggers an action.       |

### Data

| Element          | Description                          |
| ---------------- | ------------------------------------ |
| **Table**        | Rows and columns of structured data. |
| **Progress bar** | A visual indicator of progress.      |

## Actions

Add an action to a button, icon button, link, or chip to make it interactive. When a user taps the element, the action runs.

| Action                | What it does                                  |
| --------------------- | --------------------------------------------- |
| **Open URL**          | Opens a web address.                          |
| **Chat with user**    | Starts a one-to-one conversation with a user. |
| **Chat with group**   | Opens a group conversation.                   |
| **Send message**      | Sends a message on the user's behalf.         |
| **Copy to clipboard** | Copies text to the clipboard.                 |
| **Download file**     | Downloads a file.                             |
| **Initiate call**     | Starts a voice or video call.                 |
| **API call**          | Makes a request to a configured endpoint.     |
| **Custom callback**   | Triggers custom handling in your app.         |

## Variables

Variables are placeholders you insert into text and URL fields, written as `{{name}}` (for example `{{user.name}}`). They're replaced with real values when the card is sent, letting one card adapt to each recipient. Insert them from the variable picker wherever you enter text.

## Components

Components are pre-built groups of elements you can add to a card and then edit. They're a fast way to start a common card:

| Component               | Use case                                             |
| ----------------------- | ---------------------------------------------------- |
| **Product Card**        | A product with image, details, and a call to action. |
| **Order Confirmation**  | Order summary with status.                           |
| **Order Tracking**      | A delivery timeline.                                 |
| **Event Card**          | Event details with date and location.                |
| **Announcement**        | News or an update.                                   |
| **Quick Reply Buttons** | Tappable response options.                           |
| **Feedback**            | A quick rating or response prompt.                   |
| **Data Table**          | Structured rows of data.                             |
| **Carousel**            | A horizontally scrollable set of cards.              |

## Fallback Text

Every card includes **fallback text** — what a CometChat UI Kit renders if it can't display the card itself (for example, if the card JSON is malformed or the client doesn't support cards). Always set it so the message still conveys its meaning.


# Building an Order Status Card
Source: https://www.cometchat.com/docs/card-builder/example-order-status

Step-by-step guide to building an interactive Order Status card from scratch in Card Builder — a heading, a progress bar, status rows with variables, a divider, and two action buttons in a row.

This guide builds an **Order Status** card from a blank canvas — the kind of card you might send when a customer's order ships. You'll add each element yourself: a heading, a progress bar, three status rows driven by variables, a divider, and two action buttons side by side.

## What You'll Build

A single card that shows order status at a glance and lets the customer act on it:

* An **Order Status** heading (heading style)
* A **progress bar** labelled **In Transit**, filled to the current stage
* Three rows — **Status**, **ETA**, and **Tracking #** — filled from `{{order.*}}` variables
* A **divider**
* Two buttons in a **row** — **Track** and **Contact Support**

## Prerequisites

* Access to **Card Builder** in your app — see [Overview](/docs/card-builder/overview) for how to open it.
* Familiarity with the editor layout — see [Building Cards](/docs/card-builder/building-cards).

## Steps

### Step 1 — Start a blank card

In the template library, click **+ New Card**. The editor opens with an empty canvas ("Click an element or component to add it here"). Switch the left palette to the **Elements** tab — elements are grouped under **Layout**, **Content**, **Data Display**, and **Actions**.

### Step 2 — Add the heading

From **Content**, click **Text** to add it, then in the **Element** tab set its content to `Order Status` and change its **Variant** to **heading2**.

<Frame>
  <video aria-label="Adding a Text element and setting it to the heading2 variant" />
</Frame>

### Step 3 — Add the progress bar and status rows

From **Data Display**, add a **Progress Bar**. In the Element tab set its **Value** to `60` and its **Label** to `In Transit` (the label renders just below the heading).

Then add three more **Text** elements and, in each, type the label and insert a [variable](/docs/card-builder/building-cards#6-use-variables) from the variable picker:

| Text element | Content                                |
| ------------ | -------------------------------------- |
| Status       | `Status: {{order.status}}`             |
| ETA          | `ETA: {{order.eta}}`                   |
| Tracking #   | `Tracking #: {{order.trackingNumber}}` |

Variables are resolved to real values when the card is sent, so one card personalizes for every order.

<Frame>
  <video aria-label="Adding a progress bar with an In Transit label and three status rows that use order variables" />
</Frame>

### Step 4 — Add a divider and the buttons

From **Layout**, add a **Divider**. Then add a **Row** so the buttons sit side by side — with the row selected, add a **Button** (it nests inside the row) and set its label to `Track`. Select the row again, add a second **Button**, and label it `Contact Support`.

<Frame>
  <video aria-label="Adding a divider and a row containing the Track and Contact Support buttons" />
</Frame>

### Step 5 — Give the buttons their actions

Select a button, scroll to the **Action** section, and choose an [action](/docs/card-builder/elements#actions):

* **Track** → **Open URL**, with the URL `https://example.com/track/{{order.trackingNumber}}` (variables work in URLs too).
* **Contact Support** → **Chat with user**, with the support agent's user ID.

<Frame>
  <video aria-label="Setting the Track button to Open URL and the Contact Support button to Chat with user" />
</Frame>

### Step 6 — Set the message type and fallback text

Open the **Card** tab. Set the message **Type** to `order_status` — a meaningful identifier your app can use to recognize this kind of card (it defaults to `custom_type`).

Then fill in **Fallback Text**. This is what a CometChat UI Kit renders if it ever **can't display the card itself** — for example if the card JSON is malformed or the client doesn't support cards — so the message still conveys its meaning. Because the card (and its buttons) won't be shown in that case, write plain copy that **stands on its own** and doesn't reference interactive elements like "tap Track". For this card:

> Your order is in transit. We'll notify you when it's out for delivery.

<Frame>
  <video aria-label="Typing the fallback text in the Card tab" />
</Frame>

### Step 7 — Save

Give the card a name (for example, **Order Status**) in the top bar and click **Save**. It now appears under **Saved Templates** and can be reused or edited any time.

<Frame>
  <img alt="The finished Order Status card in the Card Builder editor" />
</Frame>

## Next steps

* Browse what else a card can hold in [Elements & Actions](/docs/card-builder/elements).
* Reuse this card as a [saved template](/docs/card-builder/building-cards#8-save) for future orders.


# CometChat Card Builder
Source: https://www.cometchat.com/docs/card-builder/overview

Card Builder is a visual tool in the CometChat Dashboard for designing rich, interactive card messages — product cards, order confirmations, quick replies, and more — that your CometChat UI Kits render natively.

Card Builder is a visual tool in the [CometChat Dashboard](https://app.cometchat.com) for designing **card messages** — structured, interactive messages such as product cards, order confirmations, event invites, and quick-reply prompts.

Instead of sending plain text, you compose a card visually and CometChat UI Kits render it natively in your chat — with images, buttons, layouts, and actions that respond when a user taps them.

<Frame>
  <img alt="The CometChat Card Builder editor showing the element palette, the card canvas, and the properties panel" />
</Frame>

With Card Builder, you can:

* **Design cards visually** — add text, images, buttons, and layouts and see them on a live canvas.
* **Add interactivity** — wire buttons and links to actions like opening a URL, starting a chat, or making a call.
* **Use variables** — insert placeholders such as `{{user.name}}` that are filled in when the card is sent.
* **Preview in light and dark mode** — set colors for each mode and see the result instantly.
* **Save and reuse templates** — store finished cards and load them again whenever you need them.

## What You Can Build

Start from a blank card, or from a ready-made template — Product Card, Order Confirmation, Order Tracking, Event Card, Announcement, Quick Reply Buttons, and more. See the full set in [Components](/docs/card-builder/elements#components).

## How to Open Card Builder

Card Builder opens in a new browser tab from the dashboard:

* **For chat** — open your app in the [CometChat Dashboard](https://app.cometchat.com), expand **Chat & Messaging** in the sidebar, and select **Card Builder**.
* **For an AI Agent** — open your agent and select **Card Builder** from the agent configuration menu.

<Frame>
  <img alt="The CometChat Dashboard sidebar with Chat & Messaging expanded and the Card Builder menu item highlighted" />
</Frame>

<Note>
  Card Builder is available to app owners, admins, and developers.
</Note>

## The Design Workflow

1. **Choose a starting point** — open a blank card or a template from the library.
2. **Build the card** — add elements from the palette and arrange them with rows, columns, and grids.
3. **Style and preview** — set colors, spacing, and corner radius, and preview in light and dark mode.
4. **Add actions and variables** — make buttons interactive and insert `{{placeholder}}` values.
5. **Save** — save the card as a template to reuse it later.

Continue to [Building Cards](/docs/card-builder/building-cards) for a walkthrough of the editor, or see [Elements & Actions](/docs/card-builder/elements) for everything a card can contain.


# Card JSON Schema
Source: https://www.cometchat.com/docs/card-builder/schema

The complete JSON schema a card must conform to — for developers generating cards programmatically, such as from a BYOA agent or a Custom API Tool.

Every card is a JSON document that conforms to the **CometChat Card Message Schema**. [Card Builder](/docs/card-builder/overview) produces conforming JSON automatically, so you only need this page if you generate cards **programmatically** — for example, from a [BYOA agent](/docs/ai-agents/cometchat-ag-ui-byoa) or a [Custom API Tool](/docs/ai-agents/agent-builder/tools/overview).

The schema is **Draft-07**.

<Note>
  Data placeholders (`{{variable}}`) must be **resolved before the card is sent** — the backend passes the JSON through as-is and does not substitute them.
</Note>

## Root structure

| Field          | Required | Type   | Notes                                                                                                                 |
| -------------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------- |
| `version`      | Yes      | string | Always `"1.0"` (the string, not a number).                                                                            |
| `body`         | Yes      | array  | The card's elements, rendered top to bottom. Must be non-empty.                                                       |
| `style`        | Yes      | object | Card-level style. Its `background` is required; `borderRadius`, `borderColor`, `borderWidth`, `padding` are optional. |
| `fallbackText` | Yes      | string | Plain text shown when a client can't render the card. Always set it.                                                  |

```jsonc theme={null}
{
  "version": "1.0",
  "style": { "background": { "light": "#FFFFFF", "dark": "#1C1C1E" } },
  "body": [ /* one or more elements */ ],
  "fallbackText": "Your order #1234 has shipped"
}
```

<Note>
  **Push notifications are not part of the card.** When a card is sent, the *message's* `data.text` carries the push/preview text — set from the **Notification** tab in Card Builder, falling back to `fallbackText`. The card JSON itself has no notification field.
</Note>

## Colors

Color fields are **objects with explicit light- and dark-mode values**, so a card looks right in both themes. Each side is a 6-digit hex string or `"transparent"`:

```jsonc theme={null}
"background": { "light": "#FFFFFF", "dark": "#1C1C1E" }
```

Use `"transparent"` to apply no color for one mode while setting the other, and **omit the property entirely** if you don't need a color override (where allowed — note `style.background` is required).

## Elements

Every element needs a unique `id` and a `type`. The `type` determines its other required fields. No element may include properties not defined for its type (`additionalProperties: false`).

| Element `type` | Required fields (besides `id`/`type`)         |
| -------------- | --------------------------------------------- |
| `text`         | `content`                                     |
| `markdown`     | `content`                                     |
| `image`        | `url`                                         |
| `icon`         | `name` or `url` (at least one)                |
| `avatar`       | —                                             |
| `badge`        | `text`                                        |
| `chip`         | `text`                                        |
| `codeBlock`    | `content`                                     |
| `divider`      | —                                             |
| `spacer`       | `height`                                      |
| `row`          | `items` (non-empty)                           |
| `column`       | `items` (non-empty)                           |
| `grid`         | `items` (non-empty)                           |
| `accordion`    | `header`, `body` (non-empty)                  |
| `tabs`         | `tabs` (non-empty, each `{ label, content }`) |
| `button`       | `label`, `action`                             |
| `iconButton`   | `icon`, `action`                              |
| `link`         | `text`, `action`                              |
| `table`        | `columns` (non-empty), `rows`                 |
| `progressBar`  | `value` (0–100)                               |

For a description of each element, see [Elements & Actions](/docs/card-builder/elements).

## Actions

Add an `action` to a `button`, `iconButton`, `link`, or `chip`. Every action needs a `type` plus its required fields.

| Action `type`     | Required fields                                         |
| ----------------- | ------------------------------------------------------- |
| `openUrl`         | `url` (optional `openIn`: `browser` \| `webview`)       |
| `chatWithUser`    | `uid`                                                   |
| `chatWithGroup`   | `guid`                                                  |
| `sendMessage`     | `text`                                                  |
| `copyToClipboard` | `value`                                                 |
| `downloadFile`    | `url`                                                   |
| `initiateCall`    | `callType` (`audio` \| `video`) **and** `uid` or `guid` |
| `apiCall`         | `url` (optional `method`, `headers`, `body`)            |
| `customCallback`  | — (just `type`)                                         |

## Variables

Insert variables as `{{name}}` (for example `{{user.name}}`, `{{order.id}}`) into text and URL fields. They personalize a single card per recipient, but **must be resolved before sending** — when an agent sends a card, instruct it to fill them in first.

## Full JSON Schema

This is the complete schema. Validate generated cards against it (any Draft-07 validator, e.g. Ajv) before sending.

<Accordion title="CometChat Card Message Schema (Draft-07)">
  ```json theme={null}
  {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://schema.cometchat.com/card/v1.0",
    "title": "CometChat Card Message Schema",
    "description": "Schema for rich, interactive message cards rendered natively by CometChat UI Kits. Used by the Dashboard Card Builder, external developers via API, and AI Agents for structured message generation. Data placeholders ({{variable}}) must be resolved before sending — the backend passes JSON through as-is.",
    "type": "object",
    "required": [
      "version",
      "body",
      "style",
      "fallbackText"
    ],
    "additionalProperties": false,
    "properties": {
      "version": {
        "type": "string",
        "const": "1.0",
        "description": "Schema version. Always '1.0' for this release."
      },
      "body": {
        "type": "array",
        "description": "Ordered list of elements rendered top-to-bottom (vertical stack). This is always vertical. Use 'row' for horizontal, 'grid' for grid, or 'carousel' for scrollable horizontal layout.",
        "minItems": 1,
        "items": {
          "$ref": "#/definitions/element"
        }
      },
      "style": {
        "$ref": "#/definitions/cardStyle"
      },
      "fallbackText": {
        "type": "string",
        "description": "Plain text shown on older UI Kit versions that cannot render cards. Required for graceful degradation."
      }
    },
    "definitions": {
      "padding": {
        "description": "Padding. Single number applies to all sides, or specify per-side.",
        "oneOf": [
          {
            "type": "number",
            "minimum": 0
          },
          {
            "type": "object",
            "properties": {
              "top": {
                "type": "number",
                "minimum": 0
              },
              "right": {
                "type": "number",
                "minimum": 0
              },
              "bottom": {
                "type": "number",
                "minimum": 0
              },
              "left": {
                "type": "number",
                "minimum": 0
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "sizeOrPercentage": {
        "description": "Size in pixels (number) or percentage string (e.g. '50%').",
        "oneOf": [
          {
            "type": "number",
            "minimum": 0
          },
          {
            "type": "string",
            "pattern": "^\\d+(\\.\\d+)?%$"
          }
        ]
      },
      "colorSide": {
        "description": "A single color side value — either a 6-digit hex or 'transparent' for transparent/default.",
        "oneOf": [
          {
            "type": "string",
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "description": "6-digit hex color for this mode."
          },
          {
            "type": "string",
            "const": "transparent",
            "description": "Transparent/default — no color override for this mode."
          }
        ]
      },
      "colorValue": {
        "type": "object",
        "description": "Color value with explicit light and dark mode values. Each side is either a 6-digit hex or 'transparent'. Use 'transparent' to apply no color for a specific mode while setting a color for the other. Omit the property entirely if no color override is needed for either mode.",
        "required": [
          "light",
          "dark"
        ],
        "additionalProperties": false,
        "properties": {
          "light": {
            "$ref": "#/definitions/colorSide",
            "description": "Color for light mode."
          },
          "dark": {
            "$ref": "#/definitions/colorSide",
            "description": "Color for dark mode."
          }
        }
      },
      "iconRef": {
        "type": "object",
        "description": "Reference to an icon. Use 'name' for built-in icons from the icon library, or 'url' for custom icon URLs. At least one must be provided. If both are present, 'url' takes precedence for rendering while 'name' serves as a fallback identifier.",
        "anyOf": [
          {
            "required": [
              "name"
            ]
          },
          {
            "required": [
              "url"
            ]
          }
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "Icon name from the built-in icon library (e.g. 'check', 'star', 'calendar_today')."
          },
          "url": {
            "type": "string",
            "description": "Direct URL to the icon image asset. Takes precedence over 'name' for rendering."
          }
        }
      },
      "action": {
        "description": "An action triggered by user interaction (button tap, link click, toggle change).",
        "oneOf": [
          {
            "type": "object",
            "title": "openUrl",
            "required": [
              "type",
              "url"
            ],
            "additionalProperties": false,
            "properties": {
              "type": {
                "const": "openUrl"
              },
              "url": {
                "type": "string",
                "description": "URL to open. Supports {{placeholder}}."
              },
              "openIn": {
                "type": "string",
                "enum": [
                  "browser",
                  "webview"
                ],
                "default": "browser"
              }
            }
          },
          {
            "type": "object",
            "title": "chatWithUser",
            "required": [
              "type",
              "uid"
            ],
            "additionalProperties": false,
            "properties": {
              "type": {
                "const": "chatWithUser"
              },
              "uid": {
                "type": "string",
                "description": "CometChat user uid."
              }
            }
          },
          {
            "type": "object",
            "title": "chatWithGroup",
            "required": [
              "type",
              "guid"
            ],
            "additionalProperties": false,
            "properties": {
              "type": {
                "const": "chatWithGroup"
              },
              "guid": {
                "type": "string",
                "description": "CometChat group guid."
              }
            }
          },
          {
            "type": "object",
            "title": "sendMessage",
            "required": [
              "type",
              "text"
            ],
            "additionalProperties": false,
            "properties": {
              "type": {
                "const": "sendMessage"
              },
              "text": {
                "type": "string"
              },
              "receiverUid": {
                "type": "string",
                "description": "Send to a specific user. If omitted along with receiverGuid, sends in the current conversation."
              },
              "receiverGuid": {
                "type": "string",
                "description": "Send to a specific group. If omitted along with receiverUid, sends in the current conversation."
              }
            }
          },
          {
            "type": "object",
            "title": "copyToClipboard",
            "required": [
              "type",
              "value"
            ],
            "additionalProperties": false,
            "properties": {
              "type": {
                "const": "copyToClipboard"
              },
              "value": {
                "type": "string"
              }
            }
          },
          {
            "type": "object",
            "title": "downloadFile",
            "required": [
              "type",
              "url"
            ],
            "additionalProperties": false,
            "properties": {
              "type": {
                "const": "downloadFile"
              },
              "url": {
                "type": "string"
              },
              "filename": {
                "type": "string"
              }
            }
          },
          {
            "type": "object",
            "title": "initiateCall",
            "required": [
              "type",
              "callType"
            ],
            "anyOf": [
              {
                "required": [
                  "uid"
                ]
              },
              {
                "required": [
                  "guid"
                ]
              }
            ],
            "additionalProperties": false,
            "properties": {
              "type": {
                "const": "initiateCall"
              },
              "uid": {
                "type": "string",
                "description": "User uid for 1:1 call."
              },
              "guid": {
                "type": "string",
                "description": "Group guid for group call."
              },
              "callType": {
                "type": "string",
                "enum": [
                  "audio",
                  "video"
                ]
              }
            }
          },
          {
            "type": "object",
            "title": "apiCall",
            "required": [
              "type",
              "url"
            ],
            "additionalProperties": false,
            "properties": {
              "type": {
                "const": "apiCall"
              },
              "url": {
                "type": "string"
              },
              "method": {
                "type": "string",
                "enum": [
                  "GET",
                  "POST",
                  "PUT",
                  "DELETE"
                ],
                "default": "POST"
              },
              "headers": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "body": {
                "type": "object"
              }
            }
          },
          {
            "type": "object",
            "title": "customCallback",
            "required": [
              "type"
            ],
            "additionalProperties": false,
            "properties": {
              "type": {
                "const": "customCallback"
              }
            }
          }
        ]
      },
      "element": {
        "description": "A UI element inside a card. Discriminated by the 'type' field.",
        "oneOf": [
          {
            "$ref": "#/definitions/elements/text"
          },
          {
            "$ref": "#/definitions/elements/image"
          },
          {
            "$ref": "#/definitions/elements/icon"
          },
          {
            "$ref": "#/definitions/elements/avatar"
          },
          {
            "$ref": "#/definitions/elements/badge"
          },
          {
            "$ref": "#/definitions/elements/divider"
          },
          {
            "$ref": "#/definitions/elements/spacer"
          },
          {
            "$ref": "#/definitions/elements/chip"
          },
          {
            "$ref": "#/definitions/elements/progressBar"
          },
          {
            "$ref": "#/definitions/elements/codeBlock"
          },
          {
            "$ref": "#/definitions/elements/markdown"
          },
          {
            "$ref": "#/definitions/elements/row"
          },
          {
            "$ref": "#/definitions/elements/column"
          },
          {
            "$ref": "#/definitions/elements/grid"
          },
          {
            "$ref": "#/definitions/elements/accordion"
          },
          {
            "$ref": "#/definitions/elements/tabs"
          },
          {
            "$ref": "#/definitions/elements/button"
          },
          {
            "$ref": "#/definitions/elements/iconButton"
          },
          {
            "$ref": "#/definitions/elements/link"
          },
          {
            "$ref": "#/definitions/elements/table"
          }
        ]
      },
      "elements": {
        "text": {
          "type": "object",
          "title": "Text",
          "description": "Renders text content. Supports data placeholders {{var}}.",
          "required": [
            "id",
            "type",
            "content"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "text"
            },
            "content": {
              "type": "string",
              "description": "Text content. Supports {{placeholder}} syntax."
            },
            "variant": {
              "type": "string",
              "enum": [
                "title",
                "heading1",
                "heading2",
                "heading3",
                "heading4",
                "body",
                "caption1",
                "caption2"
              ],
              "default": "body",
              "description": "Typography level: title (32px), heading1 (24px), heading2 (20px), heading3 (18px), heading4 (16px), body (14px), caption1 (12px), caption2 (10px)."
            },
            "color": {
              "$ref": "#/definitions/colorValue"
            },
            "align": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right",
                "justify"
              ],
              "default": "left"
            },
            "fontWeight": {
              "type": "string",
              "enum": [
                "regular",
                "medium",
                "bold"
              ],
              "default": "regular",
              "description": "Maps to UI Kit weights: regular (400), medium (500), bold (700)."
            },
            "maxLines": {
              "type": "integer",
              "minimum": 1
            },
            "padding": {
              "$ref": "#/definitions/padding"
            }
          }
        },
        "image": {
          "type": "object",
          "title": "Image",
          "description": "Renders an image. URL supports {{placeholder}}.",
          "required": [
            "id",
            "type",
            "url"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "image"
            },
            "url": {
              "type": "string",
              "description": "Image source URL. Supports {{placeholder}}."
            },
            "altText": {
              "type": "string"
            },
            "fit": {
              "type": "string",
              "enum": [
                "cover",
                "contain",
                "fill"
              ],
              "default": "cover"
            },
            "width": {
              "$ref": "#/definitions/sizeOrPercentage"
            },
            "height": {
              "$ref": "#/definitions/sizeOrPercentage"
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0
            },
            "padding": {
              "$ref": "#/definitions/padding"
            }
          }
        },
        "icon": {
          "type": "object",
          "title": "Icon",
          "description": "Renders an icon from the icon library or a custom URL. Use 'name' for built-in icons, or 'url' for custom icon URLs. At least one of 'name' or 'url' must be provided.",
          "required": [
            "id",
            "type"
          ],
          "anyOf": [
            {
              "required": [
                "name"
              ]
            },
            {
              "required": [
                "url"
              ]
            }
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "icon"
            },
            "name": {
              "type": "string",
              "description": "Icon name from the built-in icon library (e.g. 'check', 'star', 'calendar_today')."
            },
            "url": {
              "type": "string",
              "description": "Direct URL to the icon image asset. Takes precedence over 'name' for rendering."
            },
            "size": {
              "type": "number",
              "minimum": 0
            },
            "color": {
              "$ref": "#/definitions/colorValue"
            },
            "backgroundColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0
            },
            "padding": {
              "type": "number",
              "minimum": 0,
              "description": "Padding around the icon in px."
            }
          }
        },
        "avatar": {
          "type": "object",
          "title": "Avatar",
          "description": "Renders a user avatar with image or fallback initials.",
          "required": [
            "id",
            "type"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "avatar"
            },
            "imageUrl": {
              "type": "string",
              "description": "Avatar image URL. Supports {{placeholder}}."
            },
            "fallbackInitials": {
              "type": "string",
              "maxLength": 2
            },
            "size": {
              "type": "number",
              "minimum": 0,
              "description": "Size in density-independent pixels. Suggested presets: 28 (small), 36 (medium), 48 (large)."
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0,
              "description": "Corner radius in px. Set to half of size for circle, ~size/4 for rounded."
            },
            "backgroundColor": {
              "$ref": "#/definitions/colorValue",
              "description": "Background color for the fallback initials circle."
            },
            "fontSize": {
              "type": "number",
              "minimum": 0,
              "description": "Font size for fallback initials in px."
            },
            "fontWeight": {
              "type": "string",
              "enum": [
                "regular",
                "medium",
                "bold"
              ],
              "description": "Font weight for fallback initials."
            }
          }
        },
        "badge": {
          "type": "object",
          "title": "Badge",
          "description": "Renders a small label badge (e.g. status, priority).",
          "required": [
            "id",
            "type",
            "text"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "badge"
            },
            "text": {
              "type": "string"
            },
            "color": {
              "$ref": "#/definitions/colorValue"
            },
            "size": {
              "type": "number",
              "minimum": 0,
              "description": "Badge height in px. Suggested presets: 20 (small), 24 (medium)."
            },
            "backgroundColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderWidth": {
              "type": "number",
              "minimum": 0
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0
            },
            "padding": {
              "$ref": "#/definitions/padding"
            },
            "fontSize": {
              "type": "number",
              "minimum": 0,
              "description": "Font size in px."
            }
          }
        },
        "divider": {
          "type": "object",
          "title": "Divider",
          "description": "Renders a horizontal line separator.",
          "required": [
            "id",
            "type"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "divider"
            },
            "color": {
              "$ref": "#/definitions/colorValue"
            },
            "thickness": {
              "type": "number",
              "minimum": 0
            },
            "margin": {
              "type": "number",
              "minimum": 0,
              "description": "Top and bottom margin in px."
            }
          }
        },
        "spacer": {
          "type": "object",
          "title": "Spacer",
          "description": "Adds vertical empty space.",
          "required": [
            "id",
            "type",
            "height"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "spacer"
            },
            "height": {
              "type": "number",
              "minimum": 0
            }
          }
        },
        "chip": {
          "type": "object",
          "title": "Chip",
          "description": "Renders a compact label chip, optionally with an icon.",
          "required": [
            "id",
            "type",
            "text"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "chip"
            },
            "text": {
              "type": "string"
            },
            "color": {
              "$ref": "#/definitions/colorValue"
            },
            "icon": {
              "$ref": "#/definitions/iconRef",
              "description": "Optional icon displayed in the chip."
            },
            "backgroundColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderWidth": {
              "type": "number",
              "minimum": 0
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0
            },
            "padding": {
              "$ref": "#/definitions/padding"
            },
            "fontSize": {
              "type": "number",
              "minimum": 0,
              "description": "Font size in px."
            }
          }
        },
        "progressBar": {
          "type": "object",
          "title": "Progress Bar",
          "description": "Renders a horizontal progress bar.",
          "required": [
            "id",
            "type",
            "value"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "progressBar"
            },
            "value": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "color": {
              "$ref": "#/definitions/colorValue"
            },
            "trackColor": {
              "$ref": "#/definitions/colorValue"
            },
            "height": {
              "type": "number",
              "minimum": 0
            },
            "label": {
              "type": "string"
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0
            },
            "labelFontSize": {
              "type": "number",
              "minimum": 0,
              "description": "Font size for the label text in px."
            },
            "labelColor": {
              "$ref": "#/definitions/colorValue",
              "description": "Color for the label text."
            }
          }
        },
        "codeBlock": {
          "type": "object",
          "title": "Code Block",
          "description": "Renders a code snippet with optional syntax highlighting label.",
          "required": [
            "id",
            "type",
            "content"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "codeBlock"
            },
            "content": {
              "type": "string"
            },
            "language": {
              "type": "string"
            },
            "backgroundColor": {
              "$ref": "#/definitions/colorValue"
            },
            "textColor": {
              "$ref": "#/definitions/colorValue"
            },
            "padding": {
              "$ref": "#/definitions/padding"
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0
            },
            "fontSize": {
              "type": "number",
              "minimum": 0,
              "description": "Font size in px."
            },
            "languageLabelFontSize": {
              "type": "number",
              "minimum": 0,
              "description": "Font size for the language label in px."
            },
            "languageLabelColor": {
              "$ref": "#/definitions/colorValue",
              "description": "Color for the language label text."
            }
          }
        },
        "markdown": {
          "type": "object",
          "title": "Markdown",
          "description": "Renders markdown content.",
          "required": [
            "id",
            "type",
            "content"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "markdown"
            },
            "content": {
              "type": "string"
            },
            "baseFontSize": {
              "type": "number",
              "minimum": 0
            },
            "linkColor": {
              "$ref": "#/definitions/colorValue"
            },
            "color": {
              "$ref": "#/definitions/colorValue"
            },
            "lineHeight": {
              "type": "number",
              "minimum": 0,
              "description": "Line height multiplier (e.g. 1.5)."
            }
          }
        },
        "row": {
          "type": "object",
          "title": "Row",
          "description": "Horizontal layout container. Children are arranged left-to-right. Use 'scrollable' for horizontal scroll with optional snap and peek (carousel behavior).",
          "required": [
            "id",
            "type",
            "items"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "row"
            },
            "items": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/element"
              },
              "minItems": 1
            },
            "gap": {
              "type": "number",
              "minimum": 0
            },
            "align": {
              "type": "string",
              "enum": [
                "start",
                "center",
                "end",
                "spaceBetween",
                "spaceAround"
              ],
              "default": "start"
            },
            "crossAlign": {
              "type": "string",
              "enum": [
                "start",
                "center",
                "end"
              ],
              "default": "start",
              "description": "Cross-axis (vertical) alignment of children within the row."
            },
            "wrap": {
              "type": "boolean",
              "default": false
            },
            "scrollable": {
              "type": "boolean",
              "default": false,
              "description": "Enable horizontal scrolling when items overflow the card width."
            },
            "peek": {
              "type": "number",
              "minimum": 0,
              "description": "Pixels of the next item visible when scrollable. Only applies when scrollable is true."
            },
            "snap": {
              "type": "string",
              "enum": [
                "item",
                "free"
              ],
              "default": "item",
              "description": "Snap behavior when scrolling. Only applies when scrollable is true."
            },
            "padding": {
              "$ref": "#/definitions/padding"
            },
            "backgroundColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0
            },
            "borderColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderWidth": {
              "type": "number",
              "minimum": 0
            }
          }
        },
        "column": {
          "type": "object",
          "title": "Column",
          "description": "Vertical layout container. Children are arranged top-to-bottom.",
          "required": [
            "id",
            "type",
            "items"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "column"
            },
            "items": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/element"
              },
              "minItems": 1
            },
            "gap": {
              "type": "number",
              "minimum": 0
            },
            "align": {
              "type": "string",
              "enum": [
                "start",
                "center",
                "end",
                "stretch"
              ],
              "default": "start"
            },
            "crossAlign": {
              "type": "string",
              "enum": [
                "start",
                "center",
                "end"
              ],
              "default": "start",
              "description": "Cross-axis (horizontal) alignment of children within the column."
            },
            "padding": {
              "$ref": "#/definitions/padding"
            },
            "backgroundColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0
            },
            "borderColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderWidth": {
              "type": "number",
              "minimum": 0
            }
          }
        },
        "grid": {
          "type": "object",
          "title": "Grid",
          "description": "Grid layout with 2-4 columns. Items fill left-to-right, top-to-bottom.",
          "required": [
            "id",
            "type",
            "items"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "grid"
            },
            "items": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/element"
              },
              "minItems": 1
            },
            "columns": {
              "type": "integer",
              "enum": [
                2,
                3,
                4
              ],
              "default": 2
            },
            "gap": {
              "type": "number",
              "minimum": 0
            },
            "padding": {
              "$ref": "#/definitions/padding"
            },
            "backgroundColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0
            },
            "borderColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderWidth": {
              "type": "number",
              "minimum": 0
            }
          }
        },
        "accordion": {
          "type": "object",
          "title": "Accordion",
          "description": "Collapsible section with a header and expandable body.",
          "required": [
            "id",
            "type",
            "header",
            "body"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "accordion"
            },
            "header": {
              "type": "string"
            },
            "headerIcon": {
              "$ref": "#/definitions/iconRef",
              "description": "Optional icon displayed in the accordion header."
            },
            "body": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/element"
              },
              "minItems": 1
            },
            "expandedByDefault": {
              "type": "boolean",
              "default": false
            },
            "border": {
              "type": "boolean"
            },
            "padding": {
              "$ref": "#/definitions/padding"
            },
            "fontSize": {
              "type": "number",
              "minimum": 0,
              "description": "Font size for the header text in px."
            },
            "fontWeight": {
              "type": "string",
              "enum": [
                "regular",
                "medium",
                "bold"
              ],
              "description": "Font weight for the header text."
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0
            }
          }
        },
        "tabs": {
          "type": "object",
          "title": "Tabs",
          "description": "Tabbed container. Each tab has a label and content elements.",
          "required": [
            "id",
            "type",
            "tabs"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "tabs"
            },
            "tabs": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object",
                "required": [
                  "label",
                  "content"
                ],
                "additionalProperties": false,
                "properties": {
                  "label": {
                    "type": "string"
                  },
                  "content": {
                    "type": "array",
                    "items": {
                      "$ref": "#/definitions/element"
                    },
                    "minItems": 1
                  }
                }
              }
            },
            "defaultActiveTab": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "tabAlign": {
              "type": "string",
              "enum": [
                "start",
                "center",
                "stretch"
              ],
              "default": "start"
            },
            "tabPadding": {
              "$ref": "#/definitions/padding",
              "description": "Padding inside each tab label."
            },
            "contentPadding": {
              "$ref": "#/definitions/padding",
              "description": "Padding inside the tab content area."
            },
            "fontSize": {
              "type": "number",
              "minimum": 0,
              "description": "Font size for tab labels in px."
            }
          }
        },
        "button": {
          "type": "object",
          "title": "Button",
          "description": "A clickable button that triggers an action.",
          "required": [
            "id",
            "type",
            "label",
            "action"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "button"
            },
            "label": {
              "type": "string"
            },
            "action": {
              "$ref": "#/definitions/action"
            },
            "backgroundColor": {
              "$ref": "#/definitions/colorValue"
            },
            "textColor": {
              "$ref": "#/definitions/colorValue"
            },
            "icon": {
              "$ref": "#/definitions/iconRef",
              "description": "Optional icon displayed in the button."
            },
            "iconPosition": {
              "type": "string",
              "enum": [
                "left",
                "right"
              ],
              "default": "left"
            },
            "size": {
              "type": "number",
              "minimum": 0,
              "description": "Button height in px. Suggested presets: 32 (small), 40 (medium), 48 (large)."
            },
            "fullWidth": {
              "type": "boolean",
              "default": false
            },
            "borderColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderWidth": {
              "type": "number",
              "minimum": 0
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0
            },
            "padding": {
              "$ref": "#/definitions/padding"
            },
            "fontSize": {
              "type": "number",
              "minimum": 0,
              "description": "Font size in px."
            }
          }
        },
        "iconButton": {
          "type": "object",
          "title": "Icon Button",
          "description": "A compact icon-only button.",
          "required": [
            "id",
            "type",
            "icon",
            "action"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "iconButton"
            },
            "icon": {
              "$ref": "#/definitions/iconRef",
              "description": "Icon to display in the button."
            },
            "action": {
              "$ref": "#/definitions/action"
            },
            "size": {
              "type": "number",
              "minimum": 0
            },
            "color": {
              "$ref": "#/definitions/colorValue"
            },
            "backgroundColor": {
              "$ref": "#/definitions/colorValue"
            },
            "borderRadius": {
              "type": "number",
              "minimum": 0,
              "description": "Corner radius in px. Set to half of size for circle, 0 for square."
            }
          }
        },
        "link": {
          "type": "object",
          "title": "Link",
          "description": "An inline text link that triggers an action.",
          "required": [
            "id",
            "type",
            "text",
            "action"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "link"
            },
            "text": {
              "type": "string"
            },
            "action": {
              "$ref": "#/definitions/action"
            },
            "color": {
              "$ref": "#/definitions/colorValue"
            },
            "underline": {
              "type": "boolean",
              "default": true
            },
            "fontSize": {
              "type": "number",
              "minimum": 0,
              "description": "Font size in px."
            }
          }
        },
        "table": {
          "type": "object",
          "title": "Table",
          "description": "Renders a data table with headers and rows.",
          "required": [
            "id",
            "type",
            "columns",
            "rows"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique element identifier. Must be unique across all elements in the card."
            },
            "type": {
              "const": "table"
            },
            "columns": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "minItems": 1,
              "description": "Header labels."
            },
            "rows": {
              "type": "array",
              "items": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "description": "Row data. Cell values support {{placeholder}}."
            },
            "headerBackgroundColor": {
              "$ref": "#/definitions/colorValue"
            },
            "border": {
              "type": "boolean"
            },
            "stripedRows": {
              "type": "boolean"
            },
            "cellPadding": {
              "type": "number",
              "minimum": 0,
              "description": "Padding inside each cell in px."
            },
            "fontSize": {
              "type": "number",
              "minimum": 0,
              "description": "Font size for table content in px."
            },
            "stripedRowColor": {
              "$ref": "#/definitions/colorValue",
              "description": "Background color for striped rows."
            },
            "borderColor": {
              "$ref": "#/definitions/colorValue",
              "description": "Color for table borders."
            }
          }
        }
      },
      "cardStyle": {
        "type": "object",
        "description": "Visual settings for the message card container.",
        "required": [
          "background"
        ],
        "additionalProperties": false,
        "properties": {
          "background": {
            "$ref": "#/definitions/colorValue",
            "description": "Background color for the card container. Required: UI Kits always expect a background key. Provide an explicit color per mode, or set 'transparent' per side when no fill is wanted. If this key is omitted, the card inherits a color from its surrounding context, which is incorrect."
          },
          "borderRadius": {
            "type": "number",
            "minimum": 0,
            "description": "Corner radius in px."
          },
          "borderColor": {
            "$ref": "#/definitions/colorValue"
          },
          "borderWidth": {
            "type": "number",
            "minimum": 0
          },
          "padding": {
            "$ref": "#/definitions/padding"
          }
        }
      }
    }
  }
  ```
</Accordion>


# UI Kit Builder Settings
Source: https://www.cometchat.com/docs/chat-builder/android/builder-settings

Configure Android UI Kit Builder settings for messaging, AI helpers, calling, layout, theming, and generated Kotlin options.

The `CometChatBuilderSettings` object controls everything the Android UI Kit Builder renders—messaging, AI helpers, calls, layout, theming, and more. This object is auto-generated by the UI Kit Builder Settings Gradle plugin from your `cometchat-builder-settings.json` configuration file.

<Info>
  **For developers customizing their chat UI**: The `CometChatBuilderSettings.kt` file is generated automatically when you build your project. Edit the `cometchat-builder-settings.json` file to enable/disable features like messaging, calls, AI copilot, and theming. See the [Integration Guide](/docs/chat-builder/android/integration) for setup.
</Info>

## Top-level Structure

The generated `CometChatBuilderSettings` object in Kotlin follows this structure:

```kotlin theme={null}
object CometChatBuilderSettings {
    object ChatFeatures {
        object CoreMessagingExperience { /* Boolean constants */ }
        object DeeperUserEngagement { /* Boolean constants */ }
        object AiUserCopilot { /* Boolean constants */ }
        object UserManagement { /* Boolean constants */ }
        object GroupManagement { /* Boolean constants */ }
        object ModeratorControls { /* Boolean constants */ }
        object PrivateMessagingWithinGroups { /* Boolean constants */ }
        object InAppSounds { /* Boolean constants */ }
    }
    object CallFeatures {
        object VoiceAndVideoCalling { /* Boolean constants */ }
    }
    object Layout { /* Layout constants */ }
    object Style {
        object Color { /* Color constants */ }
        object Typography { /* Typography constants */ }
    }
}
```

***

<Tip>
  All boolean settings follow the same pattern: `true` enables the feature and shows its UI elements, `false` hides them completely.
</Tip>

## 1. Chat Features (`chatFeatures`)

### 1.1 Core Messaging Experience (`coreMessagingExperience`)

Essential messaging features: typing indicators, media sharing, message actions, and presence.

| Setting                                                               | Type    | What It Does                                                                        |
| --------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| Typing indicator (`typingIndicator`)                                  | boolean | Shows "typing..." indicator when someone is composing a message                     |
| Thread conversation & replies (`threadConversationAndReplies`)        | boolean | Enables threaded replies to specific messages, creating nested conversation threads |
| Photos sharing (`photosSharing`)                                      | boolean | Allows users to share images from device or camera                                  |
| Video sharing (`videoSharing`)                                        | boolean | Allows users to share video files                                                   |
| Audio sharing (`audioSharing`)                                        | boolean | Allows users to share audio files (mp3, wav, etc.)                                  |
| File sharing (`fileSharing`)                                          | boolean | Allows users to share documents (PDF, DOC, etc.)                                    |
| Edit messages (`editMessage`)                                         | boolean | Lets users modify their sent messages; edited messages show "(edited)" label        |
| Delete messages (`deleteMessage`)                                     | boolean | Lets users remove their sent messages                                               |
| Message delivery and read receipts (`messageDeliveryAndReadReceipts`) | boolean | Shows delivery (✓) and read (✓✓) status indicators on messages                      |
| User & friends presence (`userAndFriendsPresence`)                    | boolean | Shows online/offline status dot next to user avatars                                |
| Conversation and Advanced Search (`conversationAndAdvancedSearch`)    | boolean | Enables search across messages, users, and conversations                            |
| Moderation (`moderation`)                                             | boolean | Enables blocked message feedback for messages blocked by moderation rules           |
| Quoted Replies (`quotedReplies`)                                      | boolean | Lets users quote a message when replying, showing the original above their response |
| Mark as Unread (`markAsUnread`)                                       | boolean | Lets users mark a conversation as unread to revisit later                           |

<Tip>
  Empower users with a seamless chat experience—reply to specific messages with
  quoted replies, mark conversations as unread for later, and search across all
  chats instantly. Learn more about [Core Features](/docs/ui-kit/android/core-features).
</Tip>

### 1.2 Deeper User Engagement (`deeperUserEngagement`)

Interactive features: mentions, reactions, polls, voice notes, and collaborative tools.

| Setting                                              | Type    | What It Does                                                                                |
| ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| Mentions (`mentions`)                                | boolean | Lets users @mention specific people in a message to notify them                             |
| Mention All (`mentionAll`)                           | boolean | Lets users type @all to notify every member in a group chat                                 |
| Reactions (`reactions`)                              | boolean | Lets users add emoji reactions (👍 ❤️ 😂 etc.) to messages                                  |
| Message Translation (`messageTranslation`)           | boolean | Translates messages to user's preferred language. Requires Dashboard setup                  |
| Polls (`polls`)                                      | boolean | Lets users create polls with multiple options for group voting. Requires Dashboard setup    |
| Collaborative Whiteboard (`collaborativeWhiteboard`) | boolean | Opens a shared whiteboard for real-time drawing and collaboration. Requires Dashboard setup |
| Collaborative Document (`collaborativeDocument`)     | boolean | Creates shared documents for real-time collaborative editing. Requires Dashboard setup      |
| Voice Notes (`voiceNotes`)                           | boolean | Lets users record and send voice messages                                                   |
| Emojis (`emojis`)                                    | boolean | Shows emoji picker in composer for browsing and inserting emojis                            |
| Stickers (`stickers`)                                | boolean | Lets users send sticker images from available packs. Requires Dashboard setup               |
| User Info (`userInfo`)                               | boolean | Lets users tap on another user's avatar to view their profile                               |
| Group Info (`groupInfo`)                             | boolean | Lets users tap on group header to view group details and member list                        |

<Tip>
  Configure these features based on your app's requirements. Learn more about
  [Extensions](/docs/ui-kit/android/extensions).
</Tip>

### 1.3 AI User Copilot (`aiUserCopilot`)

AI-powered features to help users start and navigate conversations.

| Setting                                      | Type    | What It Does                                                                                  |
| -------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| Conversation Starter (`conversationStarter`) | boolean | Shows AI-suggested opening messages when starting a new chat. Requires OpenAI API key         |
| Conversation Summary (`conversationSummary`) | boolean | Generates an AI-powered summary of the conversation. Requires OpenAI API key                  |
| Smart Reply (`smartReply`)                   | boolean | Shows AI-suggested quick reply options based on conversation context. Requires OpenAI API key |

<Tip>
  AI User Copilot features require an OpenAI API key. Configure it in the [CometChat Dashboard](https://app.cometchat.com) under **AI > Settings**. Learn more about [AI Features](/docs/ui-kit/android/ai-features).
</Tip>

### 1.4 User Management (`userManagement`)

| Setting                      | Type    | What It Does                                                      |
| ---------------------------- | ------- | ----------------------------------------------------------------- |
| Friends Only (`friendsOnly`) | boolean | Restricts chat to friends list only; Users tab shows only friends |

### 1.5 Group Management (`groupManagement`)

Control what users can do with groups.

| Setting                                      | Type    | What It Does                                                      |
| -------------------------------------------- | ------- | ----------------------------------------------------------------- |
| Create Group (`createGroup`)                 | boolean | Lets users create new public or private groups                    |
| Add Members to Groups (`addMembersToGroups`) | boolean | Lets group admins/owners invite users to join the group           |
| Join/Leave Group (`joinLeaveGroup`)          | boolean | Lets users join public groups and leave groups they're in         |
| Delete Group (`deleteGroup`)                 | boolean | Lets group owners permanently delete a group and all its messages |
| View Group Members (`viewGroupMembers`)      | boolean | Shows member list in group info                                   |

### 1.6 Moderator Controls (`moderatorControls`)

Admin tools for managing group members and content.

| Setting                                         | Type    | What It Does                                                           |
| ----------------------------------------------- | ------- | ---------------------------------------------------------------------- |
| Report Message (`reportMessage`)                | boolean | Lets users flag messages for moderator review in Dashboard             |
| Kick Users (`kickUsers`)                        | boolean | Lets admins/moderators remove a user from a group (they can rejoin)    |
| Ban Users (`banUsers`)                          | boolean | Lets admins/moderators permanently remove a user and prevent rejoining |
| Promote/Demote Members (`promoteDemoteMembers`) | boolean | Lets group owners change member roles (member, moderator, admin)       |

<Tip>
  To enable content moderation, set `moderation` to `true` in Core Messaging Experience and `reportMessage` to `true` in Moderator Controls,
  then configure your moderation rules in the [CometChat Dashboard](https://app.cometchat.com). See [Rules Management](/docs/moderation/getting-started#setting-up-moderation-rules) for setup details.
</Tip>

### 1.7 Private Messaging Within Groups (`privateMessagingWithinGroups`)

Allow direct messages between group members.

| Setting                                                                    | Type    | What It Does                                                       |
| -------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| Send Private Message to Group Members (`sendPrivateMessageToGroupMembers`) | boolean | Lets users start a 1:1 chat with a group member from their profile |

### 1.8 In-App Sounds (`inAppSounds`)

Control sound notifications for incoming and outgoing messages.

| Setting                                         | Type    | What It Does                                 |
| ----------------------------------------------- | ------- | -------------------------------------------- |
| Incoming Message Sound (`incomingMessageSound`) | boolean | Plays a sound when a new message is received |
| Outgoing Message Sound (`outgoingMessageSound`) | boolean | Plays a sound when a message is sent         |

<Tip>
  These toggles control the default message sounds. To use custom audio files or manage sound playback programmatically, see the [Sound Manager](/docs/ui-kit/android/sound-manager).
</Tip>

***

## 2. Call Features (`callFeatures`)

### 2.1 Voice and Video Calling (`voiceAndVideoCalling`)

Enable voice and video calling capabilities.

| Setting                                         | Type    | What It Does                                                                |
| ----------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| 1:1 Voice Calling (`oneOnOneVoiceCalling`)      | boolean | Shows phone icon in 1:1 chat header for starting voice calls                |
| 1:1 Video Calling (`oneOnOneVideoCalling`)      | boolean | Shows video camera icon in 1:1 chat header for starting video calls         |
| Group Video Conference (`groupVideoConference`) | boolean | Shows video camera icon in group chat header for starting group video calls |
| Group Voice Conference (`groupVoiceConference`) | boolean | Shows phone icon in group chat header for starting group voice calls        |

<Tip>
  Learn more about [Call Features](/docs/ui-kit/android/call-features).
</Tip>

***

## 3. Layout (`layout`)

Control the overall UI structure and navigation.

| Setting                      | Type      | What It Does                                                                         |
| ---------------------------- | --------- | ------------------------------------------------------------------------------------ |
| With Sidebar (`withSideBar`) | boolean   | Shows navigation bar with tabs (Chats, Calls, Users, Groups)                         |
| Tabs (`tabs`)                | string\[] | Array of tabs to show: `'chats'`, `'calls'`, `'users'`, `'groups'`                   |
| Chat Type (`chatType`)       | string    | Default conversation type on load: `'user'` for 1:1 chats, `'group'` for group chats |

<Tip>
  Set `withSideBar: false` for embedded chat widgets or single-conversation
  views where navigation isn't needed.
</Tip>

***

## 4. Style (`style`)

Customize colors, fonts, and theme appearance.

### 4.1 Theme

| Setting         | Type   | What It Does                                                                             |
| --------------- | ------ | ---------------------------------------------------------------------------------------- |
| Theme (`theme`) | string | Controls light/dark mode: `'light'`, `'dark'`, or `'system'` (matches device preference) |

<Tip>
  Use `theme: "system"` to automatically match the user's device preference.
  Preview your `brandColor` in both light and dark modes for contrast.

  [Learn more about UI Kit Theming](/docs/ui-kit/android/theme-introduction) for additional customizations.
</Tip>

### 4.2 Colors

| Setting                                     | Type   | What It Does                                                                             |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| Brand Color (`brandColor`)                  | string | Primary accent color (hex) for buttons, links, active states. Example: `"#6852D6"`       |
| Primary Text Light (`primaryTextLight`)     | string | Main text color in light mode (hex). Example: `"#141414"`                                |
| Primary Text Dark (`primaryTextDark`)       | string | Main text color in dark mode (hex). Example: `"#FFFFFF"`                                 |
| Secondary Text Light (`secondaryTextLight`) | string | Secondary text color in light mode (hex) for timestamps, subtitles. Example: `"#727272"` |
| Secondary Text Dark (`secondaryTextDark`)   | string | Secondary text color in dark mode (hex) for timestamps, subtitles. Example: `"#989898"`  |

<Tip>
  Match `brandColor` to your app's primary accent color. Use your app's
  existing text colors for `primaryTextLight` and `primaryTextDark` to maintain
  brand consistency.
</Tip>

### 4.3 Typography

| Setting       | Type   | What It Does                                                          |
| ------------- | ------ | --------------------------------------------------------------------- |
| Font (`font`) | string | Font family: `'roboto'`, `'arial'`, `'inter'`, or `'times new roman'` |
| Size (`size`) | string | Text size and spacing: `'default'`, `'compact'`, or `'comfortable'`   |

***

## Settings Overview

Below is the complete settings structure with default values. Update these in your `cometchat-builder-settings.json` file to customize your chat experience.

```json theme={null}
{
  "builderId": "your-builder-id",
  "settings": {
    "chatFeatures": {
      "coreMessagingExperience": {
        "typingIndicator": true,
        "threadConversationAndReplies": true,
        "photosSharing": true,
        "videoSharing": true,
        "audioSharing": true,
        "fileSharing": true,
        "editMessage": true,
        "deleteMessage": true,
        "messageDeliveryAndReadReceipts": true,
        "userAndFriendsPresence": true,
        "conversationAndAdvancedSearch": true,
        "moderation": true,
        "quotedReplies": false,
        "markAsUnread": false
      },
      "deeperUserEngagement": {
        "mentions": true,
        "mentionAll": true,
        "reactions": true,
        "messageTranslation": true,
        "polls": true,
        "collaborativeWhiteboard": true,
        "collaborativeDocument": true,
        "voiceNotes": true,
        "emojis": true,
        "stickers": true,
        "userInfo": true,
        "groupInfo": true
      },
      "aiUserCopilot": {
        "conversationStarter": false,
        "conversationSummary": false,
        "smartReply": false
      },
      "userManagement": {
        "friendsOnly": false
      },
      "groupManagement": {
        "createGroup": true,
        "addMembersToGroups": true,
        "joinLeaveGroup": true,
        "deleteGroup": true,
        "viewGroupMembers": true
      },
      "moderatorControls": {
        "kickUsers": true,
        "banUsers": true,
        "promoteDemoteMembers": true,
        "reportMessage": true
      },
      "privateMessagingWithinGroups": {
        "sendPrivateMessageToGroupMembers": true
      },
      "inAppSounds": {
        "incomingMessageSound": true,
        "outgoingMessageSound": true
      }
    },
    "callFeatures": {
      "voiceAndVideoCalling": {
        "oneOnOneVoiceCalling": true,
        "oneOnOneVideoCalling": true,
        "groupVideoConference": true,
        "groupVoiceConference": true
      }
    },
    "layout": {
      "withSideBar": true,
      "tabs": ["chats", "calls", "users", "groups"],
      "chatType": "user"
    },
    "style": {
      "theme": "system",
      "color": {
        "brandColor": "#6852D6",
        "primaryTextLight": "#141414",
        "primaryTextDark": "#FFFFFF",
        "secondaryTextLight": "#727272",
        "secondaryTextDark": "#989898"
      },
      "typography": {
        "font": "roboto",
        "size": "default"
      }
    }
  }
}
```

***

## Dashboard Feature Requirements

Some features require additional configuration in the [CometChat Dashboard](https://app.cometchat.com) before they can be used:

<Note>
  **AI Copilot Features** (Conversation Starter, Conversation Summary, Smart Reply)

  * Requires an OpenAI API key configured in the Dashboard under **AI > Settings**
  * Enable the specific AI features you want to use
</Note>

<Note>
  **Stickers**

  * Requires sticker packs to be configured in the Dashboard under **Chat & Messaging > Stickers**
  * Upload or select sticker packs for your users
</Note>

<Note>
  **Polls**

  * Requires the Polls extension to be enabled in the Dashboard under **Extensions > Polls**
</Note>

<Note>
  **Collaborative Whiteboard & Document**

  * Requires the respective extensions to be enabled in the Dashboard under **Extensions**
</Note>

<Note>
  **Message Translation**

  * Requires the Message Translation extension to be enabled in the Dashboard under **Extensions > Message Translation**
  * Configure your preferred translation provider
</Note>

<Note>
  **Moderation**

  * Requires moderation rules to be configured in the Dashboard under **Moderation > Rules**
  * Set up content filtering and blocking rules
</Note>

***

## Next Steps

<CardGroup>
  <Card title="Directory Structure" href="/chat-builder/android/builder-dir-structure">
    Understand the organization of the builder components and generated code.
  </Card>

  <Card title="Customizations" href="/chat-builder/android/builder-customisations">
    Modify component props, styling, and behavior for deeper customization.
  </Card>
</CardGroup>


# UI Kit Builder Integration
Source: https://www.cometchat.com/docs/chat-builder/android/integration

Step-by-step guide to integrating CometChat's UI Kit Builder into your Android application using either the Gradle Plugin or Module Import method.

This guide demonstrates how to integrate the **UI Kit Builder** configuration system into your Android application. You can easily integrate the same configuration system into your own Android application by following these guided steps.

<Frame>
  <img />
</Frame>

***

## Prerequisites

Before getting started, make sure you have:

* **Android Studio** (latest version recommended)
* **Android Device or Emulator** with Android API level 26 (Android 8.0) or above
* **Java 11** or above
* **Internet connection** (required for CometChat services)

***

## Complete Integration Workflow

1. **Design Your Chat Experience** - Use the UI Kit Builder to customize layouts, features, and styling.
2. **Review and Export** - Review which features will be enabled in your Dashboard, toggle them on/off, and download the generated code package.
3. **Preview Customizations** - Optionally, preview the chat experience before integrating it into your project.
4. **Integration** - Integrate into your existing application using either the Gradle Plugin or Module Import method.
5. **Customize Further** - Explore advanced customization options to tailor the chat experience.

***

## Launch the UI Kit Builder

1. Log in to your [CometChat Dashboard](https://app.cometchat.com).
2. Select your application from the list.
3. Navigate to **Chat & Messaging** → **Get Started / Integrate** → **Android** → **Launch UI Kit Builder**.

***

## Integration Options

Choose one of the following integration methods based on your needs:

| Option                          | Best For                                                                         | Complexity |
| ------------------------------- | -------------------------------------------------------------------------------- | ---------- |
| **Gradle Plugin** (Recommended) | New projects or existing projects where you want full control over customization | Medium     |
| **Module Import**               | Quick integration when you want a ready-made module to plug-and-play             | Easy       |

***

## Option 1: Gradle Plugin Integration (Recommended)

This method gives you full control over customization and is recommended for most projects.

### Step 1: Add CometChat Repository

Add the CometChat Maven repository to your project-level `settings.gradle.kts` file in both `pluginManagement` and `dependencyResolutionManagement`:

```kotlin theme={null}
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
        maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
    }
}
```

### Step 2: Add Jetifier Flag

Add the Jetifier flag to your `gradle.properties` file:

```properties theme={null}
android.enableJetifier=true
```

### Step 3: Add UI Kit Dependencies

Add the CometChat UI Kit dependencies to your app-level `build.gradle.kts`:

```kotlin theme={null}
dependencies {
    // CometChat UIKit
    implementation("com.cometchat:chat-uikit-android:5.2.+")

    // (Optional) Include this if your app uses voice/video calling features
    implementation("com.cometchat:calls-sdk-android:4.3.+")
}
```

<Note>
  Version 5.2.+ is required for all BuilderSettingsHelper APIs to work correctly.
</Note>

### Step 4: Apply the Builder Settings Plugin

Add the UI Kit Builder Settings plugin to your app-level `build.gradle.kts`:

```kotlin theme={null}
plugins {
    id("com.android.application")
    kotlin("android")
    // Apply the UI Kit Builder settings plugin
    id("com.cometchat.builder.settings") version "5.0.1"
}
```

Sync your project to download the plugin dependencies.

### Step 5: Add Configuration JSON File

Copy the `cometchat-builder-settings.json` file from your exported code into your app module's root directory (same level as `build.gradle.kts`).

<Info>
  The `cometchat-builder-settings.json` file contains all your feature toggles, layout settings, and styling configuration from the UI Kit Builder.
</Info>

### Step 6: Build to Generate Settings

Build your project using Android Studio or run:

```bash theme={null}
./gradlew build
```

The Builder plugin will automatically generate:

* `CometChatBuilderSettings.kt` — Contains all feature flags and configuration constants
* Necessary styles in your theme

### Step 7: Copy BuilderSettingsHelper

Copy the `BuilderSettingsHelper.kt` file from the sample app to your project:

* **Source:** `src/main/java/com/cometchat/builder/BuilderSettingsHelper.kt`
* **Destination:** `src/main/java/com/yourpackage/BuilderSettingsHelper.kt`

<Note>
  Update the package declaration in `BuilderSettingsHelper.kt` to match your project's package name. Also remove the `applySettingsToBottomNavigationView` method if you're not using the sample app's navigation structure.
</Note>

### Step 7.1: Add Bottom Navigation Menu Resource

If you're using the sample app's navigation structure, copy the menu folder from the sample app to your project's resources:

* **Source:** `src/main/res/menu/builder_bottom_nav_menu.xml`
* **Destination:** `src/main/res/menu/builder_bottom_nav_menu.xml`

<Note>
  This menu resource is required if `BuilderSettingsHelper.kt` references `R.id.nav_chats`, `R.id.nav_calls`, `R.id.nav_users`, or `R.id.nav_groups`.
</Note>

### Step 8: Add Font Resources

Copy the `font` folder from the sample app to your project's resources:

* **Source:** `src/main/res/font`
* **Destination:** `src/main/res/font`

### Step 8.1: Add Required Permissions

Add the following permissions to your `AndroidManifest.xml` for camera, audio, storage, and internet access:

```xml theme={null}
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
```

### Step 9: Set the Builder Theme

Update your `AndroidManifest.xml` to use the UI Kit Builder theme:

```xml theme={null}
<application
    android:theme="@style/CometChat.Builder.Theme"
    ...>
</application>
```

### Step 9.1: Initialize CometChat UIKit

Before using any CometChat UI components, initialize the UIKit in your Application class or before launching any CometChat activities:

```kotlin theme={null}
val uiKitSettings = UIKitSettings.UIKitSettingsBuilder()
    .setAppId("YOUR_APP_ID")
    .setRegion("YOUR_REGION")
    .setAuthKey("YOUR_AUTH_KEY")
    .subscribePresenceForAllUsers()
    .build()

CometChatUIKit.init(context, uiKitSettings, object : CometChat.CallbackListener<String>() {
    override fun onSuccess(successMessage: String?) {
        // UIKit initialized successfully
    }
    override fun onError(e: CometChatException?) {
        // Handle initialization error
    }
})
```

<Note>
  Replace `YOUR_APP_ID`, `YOUR_REGION`, and `YOUR_AUTH_KEY` with your actual CometChat credentials from the Dashboard.
</Note>

### Step 10: Apply Settings to UI Components

Use the `BuilderSettingsHelper` to apply your configuration to CometChat UI components:

```kotlin theme={null}
import com.yourpackage.BuilderSettingsHelper

class MessagesActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Apply Builder settings to your UI components
        BuilderSettingsHelper.applySettingsToMessageHeader(binding.messageHeader)
        BuilderSettingsHelper.applySettingsToMessageList(binding.messageList)
        BuilderSettingsHelper.applySettingsToMessageComposer(binding.messageComposer)
    }
}
```

**Apply settings to other components:**

```kotlin theme={null}
// For Users component
BuilderSettingsHelper.applySettingsToUsers(binding.users)

// For Call Logs
BuilderSettingsHelper.applySettingsToCallLogs(binding.callLog)

// For Group Members
BuilderSettingsHelper.applySettingToGroupMembers(binding.groupMembers)
```

### Step 11: Access Generated Constants

You can access the generated constants directly in your code:

```kotlin theme={null}
import com.cometchat.builder.CometChatBuilderSettings

// Check if a feature is enabled
if (CometChatBuilderSettings.ChatFeatures.CoreMessagingExperience.PHOTOSSHARING) {
    // Enable photo sharing functionality
}

// Access styling constants
val brandColor = CometChatBuilderSettings.Style.Color.BRANDCOLOR
val fontSize = CometChatBuilderSettings.Style.Typography.SIZE
```

***

## Option 2: Import Sample App as Module

This method is ideal if you want a ready-made module to plug-and-play, or wish to migrate features from the sample app to your main app.

### Step 1: Run the Sample App

First, run the exported sample app from the CometChat Dashboard to verify it works correctly.

### Step 2: Update AndroidManifest.xml

In the sample app's `AndroidManifest.xml`:

* In the `<application>` tag, **remove all attributes except** `android:name`
* If your app already has its own `Application` class, remove the sample app's `android:name` from the `<application>` tag and extend your application class with `BuilderApplication`

### Step 3: Update build.gradle.kts

Modify the sample app's `build.gradle.kts`:

* Remove `com.cometchat.builder.settings` from the `plugins` block
* Change `id("com.android.application")` to `id("com.android.library")`

```kotlin theme={null}
plugins {
    id("com.android.library")
    kotlin("android")
}
```

<Note>
  If you have a Java project, change `kotlin("android")` to `id("org.jetbrains.kotlin.android") version "2.2.20"`.
</Note>

### Step 4: Import as Module

In Android Studio:

1. Go to **File** → **New** → **Import Module**
2. Select the sample app folder
3. Click **Finish**

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

### Step 5: Add Module Dependency

Add the module dependency to your app's `build.gradle.kts`:

```kotlin theme={null}
dependencies {
    implementation(project(":chat-builder"))
}
```

### Step 5.1: Set Builder Theme

In your app's `AndroidManifest.xml`, set the theme to use the UI Kit Builder theme:

```xml theme={null}
<application
    android:theme="@style/CometChat.Builder.Theme"
    ...>
</application>
```

### Step 6: Add Jetifier Flag

Add to your `gradle.properties`:

```properties theme={null}
android.enableJetifier=true
```

### Step 7: Add CometChat Repository

Add the CometChat repository to `settings.gradle.kts`:

```kotlin theme={null}
dependencyResolutionManagement {
    repositories {
        // ... other repositories
        maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
    }
}
```

### Step 8: Verify the Module

Ensure the imported module is visible in your project and contains all necessary files.

### Step 9: Launch Activities

Launch CometChat activities based on your app's state. Here's a complete MainActivity example:

```kotlin theme={null}
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Check login state and navigate accordingly
        if (CometChatUIKit.isInitialized() && CometChat.getLoggedInUser() != null) {
            startActivity(Intent(this, HomeActivity::class.java))
        } else {
            startActivity(Intent(this, SplashActivity::class.java))
        }
        finish()
    }
}
```

**If CometChat is not initialized or user is not logged in:**

```kotlin theme={null}
val intent = Intent(this@YourActivity, SplashActivity::class.java)
startActivity(intent)
```

**If the user is already logged in:**

```kotlin theme={null}
val intent = Intent(this@YourActivity, HomeActivity::class.java)
startActivity(intent)
```

**Open Messages screen for a User:**

```kotlin theme={null}
val UID: String = "UID"
val intent = Intent(this@YourActivity, MessagesActivity::class.java)
CometChat.getUser(UID, object : CometChat.CallbackListener<User?>() {
    override fun onSuccess(user: User?) {
        intent.putExtra("user", com.google.gson.Gson().toJson(user))
        startActivity(intent)
    }

    override fun onError(e: CometChatException?) {
        Log.e("TAG", "Error fetching user: ${e?.message}")
    }
})
```

**Open Messages screen for a Group:**

```kotlin theme={null}
val GUID: String = "GUID"
val intent = Intent(this@YourActivity, MessagesActivity::class.java)
CometChat.getGroup(GUID, object : CometChat.CallbackListener<Group?>() {
    override fun onSuccess(group: Group?) {
        intent.putExtra("group", com.google.gson.Gson().toJson(group))
        startActivity(intent)
    }

    override fun onError(e: CometChatException?) {
        Log.e("TAG", "Error fetching group: ${e?.message}")
    }
})
```

***

## Important Guidelines for Changes

<Note>
  **Functional Changes:**
  For enabling or disabling features and adjusting configurations, make the necessary updates in the `CometChatBuilderSettings.kt` file. This file contains all the feature flags and configuration constants.
</Note>

<Note>
  **UI and Theme-related Changes:**
  For any updates related to UI, such as colors, fonts, and styles, you should apply your changes in the `themes.xml` file of the module itself.
</Note>

***

## Troubleshooting

### Plugin Not Found

* Ensure you have internet connectivity during Gradle sync
* Check that the plugin version is correct: `5.0.1`
* Verify the CometChat Maven repository is added to `pluginManagement` in `settings.gradle.kts`

### CometChatBuilderSettings Not Generated

* Make sure `cometchat-builder-settings.json` is in the correct location (app module root directory)
* Clean and rebuild your project: **Build > Clean Project > Rebuild Project**
* Check the Gradle build output for any errors

### BuilderSettingsHelper Import Errors

* Verify you've updated the package declaration to match your project
* Check that all `CometChatBuilderSettings` imports are correct
* Ensure the Builder plugin has generated the settings file

***

## Next Steps

<CardGroup>
  <Card title="Builder Settings" href="/chat-builder/android/builder-settings">
    Understand the settings file and feature toggles.
  </Card>

  <Card title="Customizations" href="/chat-builder/android/builder-customisations">
    Adjust component props, behavior, and UI elements.
  </Card>

  <Card title="Directory Structure" href="/chat-builder/android/builder-dir-structure">
    See how the exported code is organized.
  </Card>

  <Card title="UI Kit Theme" href="/ui-kit/android/theme-introduction">
    Customize colors, typography, and styling to match your brand.
  </Card>
</CardGroup>


# CometChat UI Kit Builder For Android
Source: https://www.cometchat.com/docs/chat-builder/android/overview

CometChat UI Kit Builder for Android provides a pre-built interface to integrate a reliable, fully-featured chat experience into new or existing apps.

The CometChat UI Kit Builder for Android provides a pre-built user interface kit that developers can use to quickly integrate a reliable & fully-featured chat experience into an existing or a new app.

<Frame>
  <img />
</Frame>

***

## What is UI Kit Builder?

UI Kit Builder is CometChat's configuration system that allows you to customize chat features, UI components, and styling through a simple JSON configuration file. The builder plugin automatically generates Kotlin constants and applies styling based on your configuration.

***

## Benefits of Using UI Kit Builder

| Benefit             | Description                                |
| ------------------- | ------------------------------------------ |
| Easy Configuration  | Change features without modifying code     |
| Type-Safe Constants | Auto-generated Kotlin constants            |
| Consistent Styling  | Automatic theme generation                 |
| Feature Toggling    | Enable/disable features dynamically        |
| No Code Changes     | Modify behavior through JSON configuration |

***

## Available Builder Settings Categories

The Builder configuration supports the following categories:

| Category                  | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| Core Messaging Experience | Basic chat features (typing, file sharing, etc.)           |
| Deeper User Engagement    | Advanced features (reactions, polls, translation)          |
| AI User Copilot           | AI-powered features (smart replies, conversation starters) |
| Group Management          | Group creation, member management                          |
| Moderator Controls        | User moderation (kick, ban, promote)                       |
| Voice & Video Calling     | Call-related features                                      |
| Layout & Styling          | UI customization and theming                               |

***

## Try Live Demo

Experience the CometChat UI Kit Builder in action:

<CardGroup>
  <Card title="Launch Live Demo" icon="play" href="https://preview.cometchat.com/" />
</CardGroup>

***

## Next Steps

<CardGroup>
  <Card title="Integration Guide" icon="code" href="/chat-builder/android/integration">
    Step-by-step instructions to integrate the UI Kit Builder into your Android project.
  </Card>

  <Card title="Builder Settings" icon="sliders" href="/chat-builder/android/builder-settings">
    Complete reference of all configuration options available in CometChatBuilderSettings.
  </Card>

  <Card title="Customizations" icon="paintbrush" href="/chat-builder/android/builder-customisations">
    Learn how to customize components using BuilderSettingsHelper.
  </Card>

  <Card title="Directory Structure" icon="folder-tree" href="/chat-builder/android/builder-dir-structure">
    Understand the organization of the exported Builder code.
  </Card>
</CardGroup>

***

## Helpful Resources

<CardGroup>
  <Card title="Android Builder App" href="https://play.google.com/store/apps/details?id=com.cometchat.builder.java&hl=en_IN&pli=1">
    Experience the power of CometChat UI Kit with this interactive app
  </Card>

  <Card title="UI Kit Source Code" href="https://github.com/cometchat/cometchat-uikit-android/tree/v5">
    Access the complete Android UI Kit source code
  </Card>

  <Card title="Figma Design File" href="https://www.figma.com/community/file/1444324233177163609/cometchat-ui-kit-for-android">
    UI design resources for customization and prototyping
  </Card>

  <Card title="Create Support Ticket" href="https://help.cometchat.com/hc/en-us/requests/new">
    Get assistance from our support team with any questions or issues
  </Card>
</CardGroup>


# Customizing Your UI Kit Builder
Source: https://www.cometchat.com/docs/chat-builder/nextjs/builder-customisations

Customize Next.js UI Kit Builder components by adjusting CometChat app props, styling, group messages, and behavior.

The `CometChatSettings.ts` file handles basic feature toggles. For deeper customizations, modify component props or source code directly.

***

## **App-Level Customizations**

These ready-to-use props on the `CometChatApp` component let you quickly adjust common behaviors without modifying any internal components.

### **Group Action Messages**

Control the visibility of group action messages using the `showGroupActionMessages` prop:

```jsx theme={null}
<CometChatApp showGroupActionMessages={true} />
```

* `true` (default) — Group action messages are **visible**
* `false` — Group action messages are **hidden**

### **Auto Open First Item**

Control whether the first item in lists automatically opens on render using the `autoOpenFirstItem` prop:

```jsx theme={null}
<CometChatApp autoOpenFirstItem={false} />
```

* `true` (default) — The first item in conversation list, user list, or group list opens automatically on first render
* `false` — No item opens until the user clicks on one

***

## **Component-Level Customizations**

For more advanced customizations tailored to your app's needs, you can modify individual UI Kit components directly.

### **How to Customize**

1. Find the component in the [UI Kit Components Overview](/docs/ui-kit/react/components-overview)
2. Check available props and customization options
3. Update props or edit the component source code

Below are some examples to help you get started with common customizations like date formats, conversation subtitles, and send buttons.

### **Custom Date Format**

Customize how sticky date headers appear in the message list.

**Component**: [Message List](/docs/ui-kit/react/message-list) → [`stickyDateTimeFormat`](/docs/ui-kit/react/message-list#sticky-datetime-format)

```jsx lines theme={null}
import {
  CometChatMessageList,
  CalendarObject,
} from "@cometchat/chat-uikit-react";

const dateFormat = new CalendarObject({
  today: "hh:mm A", // "10:30 AM"
  yesterday: "[Yesterday]",
  otherDays: "DD/MM/YYYY", // "25/05/2025"
});

<CometChatMessageList user={chatUser} stickyDateTimeFormat={dateFormat} />;
```

<Frame>
  <img />
</Frame>

**Default format** (for reference):

```javascript lines theme={null}
new CalendarObject({
  today: "today",
  yesterday: "yesterday",
  otherDays: "DD MMM, YYYY", // "25 Jan, 2025"
});
```

***

### **Custom Conversation Subtitle**

Show online status or member count instead of the default last message preview.

**Component**: [Conversations](/docs/ui-kit/react/conversations) → [`subtitleView`](/docs/ui-kit/react/conversations#subtitleview)

```jsx lines theme={null}
"use client";

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

const customSubtitleView = (conversation) => {
  if (conversation.getConversationType() === "user") {
    const user = conversation.getConversationWith();
    return (
      <span>{user.getStatus() === "online" ? "🟢 Online" : "⚫ Offline"}</span>
    );
  } else {
    const group = conversation.getConversationWith();
    return <span>{group.getMembersCount()} members</span>;
  }
};

<CometChatConversations subtitleView={customSubtitleView} />;
```

***

### **Custom Send Button**

Replace the default send button with your brand's icon.

**Component**: [Message Composer](/docs/ui-kit/react/message-composer) → [`sendButtonView`](/docs/ui-kit/react/message-composer#sendbuttonview)

```jsx lines theme={null}
"use client";

import {
  CometChatMessageComposer,
  CometChatButton,
} from "@cometchat/chat-uikit-react";

const brandedSendButton = (
  <CometChatButton
    iconURL="/icons/brand-send.svg"
    onClick={() => {
      // Your custom send logic
    }}
  />
);

<CometChatMessageComposer user={chatUser} sendButtonView={brandedSendButton} />;
```

```css lines theme={null}
/* Style the custom send button */
.cometchat-message-composer .cometchat-button {
  background: #6852d6;
  border-radius: 50%;
}

.cometchat-message-composer .cometchat-button__icon {
  background: #ffffff;
}
```

***

## **Next Steps**

<CardGroup>
  <Card title="UI Kit Builder Settings" href="/chat-builder/nextjs/builder-settings">
    Configure feature toggles and behavior
  </Card>

  <Card title="Components Overview" href="/ui-kit/react/components-overview">
    Explore all available UI components
  </Card>

  <Card title="Theming" href="/ui-kit/react/theme">
    Customize colors, typography, and styling
  </Card>

  <Card title="Localization" href="/ui-kit/react/localize">
    Add multi-language support
  </Card>
</CardGroup>


# Directory Structure
Source: https://www.cometchat.com/docs/chat-builder/nextjs/builder-dir-structure

Overview of the CometChat UI Kit Builder directory layout for Next.js — understand where to find and customize components, settings, and styles.

The exported UI Kit Builder code lives in `src/CometChat/`. This guide helps you navigate the structure so you know exactly where to make changes.

<Tree>
  <Tree.Folder name="src">
    <Tree.Folder name="CometChat">
      <Tree.Folder name="assets">
        <Tree.File name="Icons, images, audio files" />
      </Tree.Folder>

      <Tree.Folder name="components">
        <Tree.File name="React components (UI elements)" />
      </Tree.Folder>

      <Tree.Folder name="context">
        <Tree.File name="React Context providers (state management)" />
      </Tree.Folder>

      <Tree.Folder name="locales">
        <Tree.File name="Translation files (en, fr, de, etc.)" />
      </Tree.Folder>

      <Tree.Folder name="styles">
        <Tree.File name="CSS files (mirrors components structure)" />
      </Tree.Folder>

      <Tree.Folder name="utils">
        <Tree.File name="Utility functions and helpers" />
      </Tree.Folder>

      <Tree.File name="CometChatApp.tsx" />

      <Tree.File name="CometChatSettings.ts" />

      <Tree.File name="customHooks.ts" />

      <Tree.File name="decl.d.ts" />

      <Tree.File name="styleConfig.ts" />
    </Tree.Folder>

    <Tree.File name="App.tsx" />

    <Tree.File name="index.tsx" />
  </Tree.Folder>
</Tree>

***

## Root Files

| File                   | Purpose                                                      |
| ---------------------- | ------------------------------------------------------------ |
| `CometChatApp.tsx`     | Main entry point — import this to render the chat experience |
| `CometChatSettings.ts` | Toggle features on/off (messaging, calls, AI copilot, etc.)  |
| `customHooks.ts`       | Custom React hooks used throughout the application           |
| `styleConfig.ts`       | Global styling configuration (colors, fonts, spacing)        |

***

## Key Folders

### `components/`

Each component folder contains the main `.tsx` file and associated hooks (`use*.ts`). These are the building blocks of your chat UI.

<Tree>
  <Tree.Folder name="components">
    <Tree.Folder name="CometChatAddMembers">
      <Tree.File name="Add members to groups" />
    </Tree.Folder>

    <Tree.Folder name="CometChatBannedMembers">
      <Tree.File name="Manage banned users" />
    </Tree.Folder>

    <Tree.Folder name="CometChatCallLog">
      <Tree.File name="Call history display" />
    </Tree.Folder>

    <Tree.Folder name="CometChatCreateGroup">
      <Tree.File name="Group creation flow" />
    </Tree.Folder>

    <Tree.Folder name="CometChatDetails">
      <Tree.File name="User/group details panel" />
    </Tree.Folder>

    <Tree.Folder name="CometChatHome">
      <Tree.File name="Main chat home screen" />
    </Tree.Folder>

    <Tree.Folder name="CometChatJoinGroup">
      <Tree.File name="Join group flow" />
    </Tree.Folder>

    <Tree.Folder name="CometChatLogin">
      <Tree.File name="Login screen" />
    </Tree.Folder>

    <Tree.Folder name="CometChatMessages">
      <Tree.File name="Message list and composer" />
    </Tree.Folder>

    <Tree.Folder name="CometChatSelector">
      <Tree.File name="Conversation/user selector" />
    </Tree.Folder>

    <Tree.Folder name="CometChatTransferOwnership">
      <Tree.File name="Transfer group ownership" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

### `context/`

State management for the chat application.

<Tree>
  <Tree.Folder name="context">
    <Tree.File name="AppContext.tsx" />

    <Tree.File name="CometChatContext.tsx" />

    <Tree.File name="appReducer.ts" />
  </Tree.Folder>
</Tree>

### `styles/`

CSS files organized to mirror the components structure. Each component has a corresponding style folder.

### `locales/`

Translation files for multi-language support. Add or modify JSON files here to customize text.

***

## Quick Reference: Where to Customize

| What you want to change | Where to look                 |
| ----------------------- | ----------------------------- |
| Enable/disable features | `CometChatSettings.ts`        |
| Theme colors & fonts    | `styleConfig.ts`              |
| Component-specific CSS  | `styles/<ComponentName>/`     |
| Text & translations     | `locales/<lang>/<lang>.json`  |
| Component behavior      | `components/<ComponentName>/` |

<Note>
  Prefer using settings and CSS overrides. For extensive changes, create wrapper
  components instead of modifying core files directly.
</Note>

***

## Next Steps

<CardGroup>
  <Card title="UI Kit Builder Settings" href="/chat-builder/nextjs/builder-settings">
    Configure feature toggles and behavior
  </Card>

  <Card title="Customizations" href="/chat-builder/nextjs/builder-customisations">
    Modify component props, styling, and behavior
  </Card>

  <Card title="Theming" href="/ui-kit/react/theme">
    Customize colors, typography, and styling
  </Card>

  <Card title="Localization" href="/ui-kit/react/localize">
    Add multi-language support
  </Card>
</CardGroup>


# UI Kit Builder Settings
Source: https://www.cometchat.com/docs/chat-builder/nextjs/builder-settings

Configure Next.js UI Kit Builder settings for messaging, AI helpers, calling, layout, theming, and agent tools.

The `CometChatSettings` object controls everything the Next.js UI Kit Builder renders—messaging, AI helpers, calls, layout, theming, and agent tools.

<Info>
  **For developers customizing their chat UI**: Edit `CometChatSettings.ts` to
  enable/disable features like messaging, calls, AI copilot, and theming. See
  [Integration Guide](/docs/chat-builder/nextjs/integration) for setup.
</Info>

## Top-level structure

```ts lines theme={null}
export interface CometChatSettings {
  chatFeatures: { ... }
  callFeatures: { ... }
  layout: { ... }
  style: { ... }
}
```

***

<Tip>
  All boolean settings follow the same pattern: `true` enables the feature and shows its UI elements, `false` hides them completely.
</Tip>

## 1. Chat Features (`chatFeatures`)

### 1.1 Core Messaging Experience (`coreMessagingExperience`)

Essential messaging features: typing indicators, media sharing, message actions, and presence.

| Setting                                                               | Type    | What It Does                                                                        |
| --------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| Typing indicator (`typingIndicator`)                                  | boolean | Shows "typing..." indicator when someone is composing a message                     |
| Thread conversation & replies (`threadConversationAndReplies`)        | boolean | Enables threaded replies to specific messages, creating nested conversation threads |
| Photos sharing (`photosSharing`)                                      | boolean | Allows users to share images from device or camera                                  |
| Video sharing (`videoSharing`)                                        | boolean | Allows users to share video files                                                   |
| Audio sharing (`audioSharing`)                                        | boolean | Allows users to share audio files (mp3, wav, etc.)                                  |
| File sharing (`fileSharing`)                                          | boolean | Allows users to share documents (PDF, DOC, etc.)                                    |
| Edit messages (`editMessage`)                                         | boolean | Lets users modify their sent messages; edited messages show "(edited)" label        |
| Delete messages (`deleteMessage`)                                     | boolean | Lets users remove their sent messages                                               |
| Message delivery and read receipts (`messageDeliveryAndReadReceipts`) | boolean | Shows delivery (✓) and read (✓✓) status indicators on messages                      |
| User & friends presence (`userAndFriendsPresence`)                    | boolean | Shows online/offline status dot next to user avatars                                |
| Conversation and Advanced Search (`conversationAndAdvancedSearch`)    | boolean | Enables search across messages, users, and conversations                            |
| Quoted Replies (`quotedReplies`)                                      | boolean | Lets users quote a message when replying, showing the original above their response |
| Mark as Unread (`markAsUnread`)                                       | boolean | Lets users mark a conversation as unread to revisit later                           |

<Tip>
  Empower users with a seamless chat experience—reply to specific messages with
  quoted replies, mark conversations as unread for later, and search across all
  chats instantly. Learn more about [Core
  Features](/docs/ui-kit/react/core-features).
</Tip>

### 1.2 Deeper User Engagement (`deeperUserEngagement`)

Interactive features: mentions, reactions, polls, voice notes, and collaborative tools.

| Setting                                              | Type    | What It Does                                                                                |
| ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| Mentions (`mentions`)                                | boolean | Lets users @mention specific people in a message to notify them                             |
| Mention All (`mentionAll`)                           | boolean | Lets users type @all to notify every member in a group chat                                 |
| Reactions (`reactions`)                              | boolean | Lets users add emoji reactions (👍 ❤️ 😂 etc.) to messages                                  |
| Message Translation (`messageTranslation`)           | boolean | Translates messages to user's preferred language. Requires Dashboard setup                  |
| Polls (`polls`)                                      | boolean | Lets users create polls with multiple options for group voting. Requires Dashboard setup    |
| Collaborative Whiteboard (`collaborativeWhiteboard`) | boolean | Opens a shared whiteboard for real-time drawing and collaboration. Requires Dashboard setup |
| Collaborative Document (`collaborativeDocument`)     | boolean | Creates shared documents for real-time collaborative editing. Requires Dashboard setup      |
| Voice Notes (`voiceNotes`)                           | boolean | Lets users record and send voice messages                                                   |
| Emojis (`emojis`)                                    | boolean | Shows emoji picker in composer for browsing and inserting emojis                            |
| Stickers (`stickers`)                                | boolean | Lets users send sticker images from available packs. Requires Dashboard setup               |
| User Info (`userInfo`)                               | boolean | Lets users tap on another user's avatar to view their profile                               |
| Group Info (`groupInfo`)                             | boolean | Lets users tap on group header to view group details and member list                        |
| Report Message (`reportMessage`)                     | boolean | Lets users flag inappropriate messages for review. Requires moderation setup                |

<Tip>
  Configure these features based on your app's requirements. Learn more about
  [Extensions](/docs/ui-kit/react/extensions).
</Tip>

### 1.3 AI User Copilot (`aiUserCopilot`)

AI-powered features to help users start and navigate conversations.

| Setting                                      | Type    | What It Does                                                                                  |
| -------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| Conversation Starter (`conversationStarter`) | boolean | Shows AI-suggested opening messages when starting a new chat. Requires OpenAI API key         |
| Conversation Summary (`conversationSummary`) | boolean | Generates an AI-powered summary of the conversation. Requires OpenAI API key                  |
| Smart Reply (`smartReply`)                   | boolean | Shows AI-suggested quick reply options based on conversation context. Requires OpenAI API key |

<Tip>
  AI User Copilot features require an OpenAI API key. Configure it in the [CometChat Dashboard](https://app.cometchat.com) under **Chat & Messaging > Settings**. Learn more about [AI Features](/docs/ui-kit/react/ai-features).
</Tip>

### 1.4 User Management (`userManagement`)

| Setting                      | Type    | What It Does                                                      |
| ---------------------------- | ------- | ----------------------------------------------------------------- |
| Friends Only (`friendsOnly`) | boolean | Restricts chat to friends list only; Users tab shows only friends |

### 1.5 Group Management (`groupManagement`)

Control what users can do with groups.

| Setting                                      | Type    | What It Does                                                      |
| -------------------------------------------- | ------- | ----------------------------------------------------------------- |
| Create Group (`createGroup`)                 | boolean | Lets users create new public or private groups                    |
| Add Members to Groups (`addMembersToGroups`) | boolean | Lets group admins/owners invite users to join the group           |
| Join/Leave Group (`joinLeaveGroup`)          | boolean | Lets users join public groups and leave groups they're in         |
| Delete Group (`deleteGroup`)                 | boolean | Lets group owners permanently delete a group and all its messages |
| View Group Members (`viewGroupMembers`)      | boolean | Shows member list in group info                                   |

### 1.6 Moderation (`moderatorControls`)

Admin tools for managing group members and content.

| Setting                                         | Type    | What It Does                                                                                                       |
| ----------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| Blocked message feedback (`moderation`)         | boolean | Enables blocked message feedback for blocked messages as per configured moderation rules. Requires Dashboard setup |
| Report Message (`reportMessage`)                | boolean | Lets users flag messages for moderator review in Dashboard                                                         |
| Kick Users (`kickUsers`)                        | boolean | Lets admins/moderators remove a user from a group (they can rejoin)                                                |
| Ban Users (`banUsers`)                          | boolean | Lets admins/moderators permanently remove a user and prevent rejoining                                             |
| Promote/Demote Members (`promoteDemoteMembers`) | boolean | Lets group owners change member roles (member, moderator, admin)                                                   |

<Tip>
  To enable content moderation, set `moderation` and `reportMessage` to `true`,
  then configure your moderation rules in the [CometChat
  Dashboard](https://app.cometchat.com). See [Rules
  Management](/docs/moderation/getting-started#setting-up-moderation-rules) for setup
  details.
</Tip>

### 1.7 Private Messaging Within Groups (`privateMessagingWithinGroups`)

Allow direct messages between group members.

| Setting                                                                    | Type    | What It Does                                                       |
| -------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| Send Private Message to Group Members (`sendPrivateMessageToGroupMembers`) | boolean | Lets users start a 1:1 chat with a group member from their profile |

### 1.8 In-App Sounds (`inAppSounds`)

Control sound notifications for incoming and outgoing messages.

| Setting                                         | Type    | What It Does                                 |
| ----------------------------------------------- | ------- | -------------------------------------------- |
| Incoming Message Sound (`incomingMessageSound`) | boolean | Plays a sound when a new message is received |
| Outgoing Message Sound (`outgoingMessageSound`) | boolean | Plays a sound when a message is sent         |

<Tip>
  These toggles control the default message sounds. To use custom audio files or manage sound playback programmatically, see the [Sound Manager](/docs/ui-kit/react/sound-manager).
</Tip>

***

## 2. Call Features (`callFeatures`)

### 2.1 Voice and Video Calling (`voiceAndVideoCalling`)

Enable voice and video calling capabilities.

| Setting                                         | Type    | What It Does                                                                |
| ----------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| 1:1 Voice Calling (`oneOnOneVoiceCalling`)      | boolean | Shows phone icon in 1:1 chat header for starting voice calls                |
| 1:1 Video Calling (`oneOnOneVideoCalling`)      | boolean | Shows video camera icon in 1:1 chat header for starting video calls         |
| Group Video Conference (`groupVideoConference`) | boolean | Shows video camera icon in group chat header for starting group video calls |
| Group Voice Conference (`groupVoiceConference`) | boolean | Shows phone icon in group chat header for starting group voice calls        |

<Tip>
  Learn more about [Call Features](/docs/ui-kit/react/call-features#features).
</Tip>

***

## 3. Layout (`layout`)

Control the overall UI structure and navigation.

| Setting                      | Type      | What It Does                                                                         |
| ---------------------------- | --------- | ------------------------------------------------------------------------------------ |
| With Sidebar (`withSideBar`) | boolean   | Shows navigation sidebar with tabs (Chats, Calls, Users, Groups) on the left side    |
| Tabs (`tabs`)                | string\[] | Array of tabs to show: `'chats'`, `'calls'`, `'users'`, `'groups'`                   |
| Chat Type (`chatType`)       | string    | Default conversation type on load: `'user'` for 1:1 chats, `'group'` for group chats |

<Tip>
  Set `withSideBar: false` for embedded chat widgets or single-conversation
  views where navigation isn't needed.
</Tip>

***

## 4. Style (`style`)

Customize colors, fonts, and theme appearance.

### 4.1 Theme

| Setting         | Type   | What It Does                                                                             |
| --------------- | ------ | ---------------------------------------------------------------------------------------- |
| Theme (`theme`) | string | Controls light/dark mode: `'light'`, `'dark'`, or `'system'` (matches device preference) |

<Tip>
  Use `theme: "system"` to automatically match the user's device preference.
  Preview your `brandColor` in both light and dark modes for contrast.

  [Learn more about UI Kit Theming](/docs/ui-kit/react/theme) for additional customizations.
</Tip>

### 4.2 Colors

| Setting                                     | Type   | What It Does                                                                             |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| Brand Color (`brandColor`)                  | string | Primary accent color (hex) for buttons, links, active states. Example: `"#6852D6"`       |
| Primary Text Light (`primaryTextLight`)     | string | Main text color in light mode (hex). Example: `"#2B2B2B"`                                |
| Primary Text Dark (`primaryTextDark`)       | string | Main text color in dark mode (hex). Example: `"#FFFFFF"`                                 |
| Secondary Text Light (`secondaryTextLight`) | string | Secondary text color in light mode (hex) for timestamps, subtitles. Example: `"#727272"` |
| Secondary Text Dark (`secondaryTextDark`)   | string | Secondary text color in dark mode (hex) for timestamps, subtitles. Example: `"#989898"`  |

<Tip>
  Match `brandColor` to your website's primary accent color. Use your site's
  existing text colors for `primaryTextLight` and `primaryTextDark` to maintain
  brand consistency.
</Tip>

### 4.3 Typography

| Setting       | Type   | What It Does                                                          |
| ------------- | ------ | --------------------------------------------------------------------- |
| Font (`font`) | string | Font family: `'roboto'`, `'arial'`, `'inter'`, or `'times new roman'` |
| Size (`size`) | string | Text size and spacing: `'default'`, `'compact'`, or `'comfortable'`   |

***

## Settings Overview

Below is the complete settings structure with default values. Update these in `CometChatSettings.ts` to customize your chat experience.

```json lines theme={null}
{
  "chatFeatures": {
    "coreMessagingExperience": {
      "typingIndicator": true,
      "threadConversationAndReplies": true,
      "photosSharing": true,
      "videoSharing": true,
      "audioSharing": true,
      "fileSharing": true,
      "editMessage": true,
      "deleteMessage": true,
      "messageDeliveryAndReadReceipts": true,
      "userAndFriendsPresence": true,
      "conversationAndAdvancedSearch": true,
      "moderation": true,
      "quotedReplies": false,
      "markAsUnread": false
    },
    "deeperUserEngagement": {
      "mentions": true,
      "mentionAll": true,
      "reactions": true,
      "messageTranslation": true,
      "polls": true,
      "collaborativeWhiteboard": true,
      "collaborativeDocument": true,
      "voiceNotes": true,
      "emojis": true,
      "stickers": true,
      "userInfo": true,
      "groupInfo": true
    },
    "aiUserCopilot": {
      "conversationStarter": false,
      "conversationSummary": false,
      "smartReply": false
    },
    "userManagement": {
      "friendsOnly": false
    },
    "groupManagement": {
      "createGroup": true,
      "addMembersToGroups": true,
      "joinLeaveGroup": true,
      "deleteGroup": true,
      "viewGroupMembers": true
    },
    "moderatorControls": {
      "kickUsers": true,
      "banUsers": true,
      "promoteDemoteMembers": true,
      "reportMessage": true
    },
    "privateMessagingWithinGroups": {
      "sendPrivateMessageToGroupMembers": true
    },
    "inAppSounds": {
      "incomingMessageSound": true,
      "outgoingMessageSound": true
    }
  },
  "callFeatures": {
    "voiceAndVideoCalling": {
      "oneOnOneVoiceCalling": true,
      "oneOnOneVideoCalling": true,
      "groupVideoConference": true,
      "groupVoiceConference": true
    }
  },
  "layout": {
    "withSideBar": true,
    "tabs": ["chats", "calls", "users", "groups"],
    "chatType": "user"
  },
  "style": {
    "theme": "system",
    "color": {
      "brandColor": "#6852D6",
      "primaryTextLight": "#141414",
      "primaryTextDark": "#FFFFFF",
      "secondaryTextLight": "#727272",
      "secondaryTextDark": "#989898"
    },
    "typography": {
      "font": "roboto",
      "size": "default"
    }
  }
}
```

***

## Next Steps

<CardGroup>
  <Card title="Directory Structure" href="/chat-builder/nextjs/builder-dir-structure">
    Understand the organization of the builder components and generated code.
  </Card>

  <Card title="Customizations" href="/chat-builder/nextjs/builder-customisations">
    Modify component props, styling, and behavior for deeper customization.
  </Card>
</CardGroup>


# UI Kit Builder Integration
Source: https://www.cometchat.com/docs/chat-builder/nextjs/integration

Step-by-step guide to integrating CometChat UI Kit Builder into your Next.js app with user login and SSR handling.

The **UI Kit Builder** simplifies integrating CometChat's UI Kit into your Next.js application — quickly set up chat, customize UI elements, and add features without extensive coding.

<Frame>
  <img />
</Frame>

## **Complete Integration Workflow**

1. **Design Your Chat Experience** - Use the **UI Kit Builder** to customize layouts, features, and styling.
2. **Review and Export** - Review which features will be enabled in your Dashboard, toggle them on/off, and download the generated code package.
3. **Preview Customizations** - Optionally, preview the chat experience before integrating it into your project.
4. **Integration** - Integrate into your existing application.
5. **Customize Further** - Explore advanced customization options to tailor the chat experience.

<Frame>
  <iframe title="YouTube video" />
</Frame>

***

## **Launch the UI Kit Builder**

1. Log in to your [**CometChat Dashboard**](https://app.cometchat.com).
2. Select your application from the list.
3. Navigate to **Chat & Messaging** → **Get Started**.
4. Choose your platform and click **Launch UI Kit Builder**.

***

## **Review Your Export**

When you click **Export**, a "Review Your Export" modal appears (Step 1 of 3). This lets you:

* **Review features** — See which features will be enabled in your CometChat Dashboard based on your UI Kit configuration
* **Toggle features** — Turn individual features on/off before export
* **AI User Copilot** — Requires an OpenAI API key (you'll configure this in the next step)

<Frame>
  <img />
</Frame>

<Note>
  Only checked features will be enabled in your Dashboard. You can always modify
  these settings later in the [CometChat Dashboard](https://app.cometchat.com).
</Note>

***

## **Preview Customizations (Optional)**

Before integrating the **UI Kit Builder** into your project, you can preview the chat experience by following these steps. This step is completely optional and can be skipped if you want to directly integrate the **UI Kit Builder** into your project.

> You can preview the experience:
>
> 1. Open the `cometchat-app-react` folder.
> 2. Install dependencies:
>
> ```
> npm i
> ```
>
> 3. Run the app:
>
> ```powershell theme={null}
> npm start
> ```
>
> Your app credentials are already prepopulated in the exported code.

***

## **Integrate into Your Project**

### **Step 1: Install Dependencies**

```ruby theme={null}
npm install @cometchat/chat-uikit-react@6.3.11 @cometchat/calls-sdk-javascript
```

### **Step 2: Copy CometChat Folder**

Copy the `cometchat-app-react/src/CometChat` folder inside your `src/app` directory.

***

### **Step 3: Create & Initialize `CometChatNoSSR.tsx`**

Directory Structure:

```swift lines theme={null}
src/app/
├── CometChat/
└── CometChatNoSSR/
    └── CometChatNoSSR.tsx
```

src/app/CometChatNoSSR/CometChatNoSSR.tsx

```javascript lines highlight={11-13} theme={null}
import React, { useEffect } from "react";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
} from "@cometchat/chat-uikit-react";
import CometChatApp from "../CometChat/CometChatApp";
import { CometChatProvider } from "../CometChat/context/CometChatContext";
import { setupLocalization } from "../CometChat/utils/utils";

export const COMETCHAT_CONSTANTS = {
  APP_ID: "YOUR_APP_ID", // Replace with your App ID
  REGION: "YOUR_REGION", // Replace with your App Region
  AUTH_KEY: "YOUR_AUTH_KEY", // Replace with your Auth Key or leave blank if you are authenticating using Auth Token
};

const CometChatNoSSR: React.FC = () => {
  useEffect(() => {
    const UIKitSettings = new UIKitSettingsBuilder()
      .setAppId(COMETCHAT_CONSTANTS.APP_ID)
      .setRegion(COMETCHAT_CONSTANTS.REGION)
      .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(UIKitSettings)
      ?.then(() => {
        setupLocalization();
        console.log("Initialization completed successfully");
      })
      .catch((error) => console.error("Initialization failed", error));
  }, []);

  return (
    <div style={{ width: "100vw", height: "100vh" }}>
      <CometChatProvider>
        <CometChatApp />
      </CometChatProvider>
    </div>
  );
};

export default CometChatNoSSR;
```

<Info>
  Your app credentials (`APP_ID`, `AUTH_KEY`, `REGION`) are prepopulated in the exported code. If you need to use different credentials, you can find them in the Credentials block of your app's [Overview section](https://app.cometchat.com) on the CometChat Dashboard.
</Info>

***

### **Step 4: User Authentication**

CometChat uses a UID (User ID) to identify each user. After initialization, authenticate users to enable chat functionality.

You can either:

1. **Create new users** on the **[CometChat Dashboard](https://app.cometchat.com)**, **[CometChat SDK Method](/docs/ui-kit/react/methods#create-user)** or **[via the API](https://www.cometchat.com/docs/rest-api/users/create)**.

2. **Use pre-generated test users**: `cometchat-uid-1` through `cometchat-uid-5`

The **Login** method returns a **User object** containing all relevant details of the logged-in user.

**Login After Initialization**

Log in the user after initialization — useful when login happens later in your app flow (e.g., after a login form).

<Tabs>
  <Tab title="TypeScript">
    ```ts lines highlight={3} theme={null}
    import { CometChatUIKit } from "@cometchat/chat-uikit-react";

    const UID = "YOUR_UID"; // Replace with your actual UID

    CometChatUIKit.getLoggedinUser().then((user: CometChat.User | null) => {
      if (!user) {
        // If no user is logged in, proceed with login
        CometChatUIKit.login(UID)
          .then((user: CometChat.User) => {
            console.log("Login Successful:", { user });
            // Mount your app
          })
          .catch(console.log);
      } else {
        // If user is already logged in, mount your app
      }
    });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js lines highlight={3} theme={null}
    import { CometChatUIKit } from "@cometchat/chat-uikit-react";

    const UID = "YOUR_UID"; // Replace with your actual UID

    CometChatUIKit.getLoggedinUser().then((user) => {
      if (!user) {
        // If no user is logged in, proceed with login
        CometChatUIKit.login(UID)
          .then((user) => {
            console.log("Login Successful:", { user });
            // Mount your app
          })
          .catch(console.log);
      } else {
        // If user is already logged in, mount your app
      }
    });
    ```
  </Tab>
</Tabs>

**Login During Initialization**

Alternatively, log in the user immediately inside `CometChatUIKit.init()` — ideal for apps that authenticate on startup.

<Tabs>
  <Tab title="TypeScript">
    ```ts lines highlight={11-13} theme={null}
    import React, { useEffect } from "react";
    import {
      CometChatUIKit,
      UIKitSettingsBuilder,
    } from "@cometchat/chat-uikit-react";
    import CometChatApp from "../CometChat/CometChatApp";
    import { CometChatProvider } from "../CometChat/context/CometChatContext";
    import { setupLocalization } from "../CometChat/utils/utils";

    export const COMETCHAT_CONSTANTS = {
      APP_ID: "YOUR_APP_ID", // Replace with your App ID
      REGION: "YOUR_REGION", // Replace with your App Region
      AUTH_KEY: "YOUR_AUTH_KEY", // Replace with your Auth Key or leave blank if you are authenticating using Auth Token
    };

    const CometChatNoSSR: React.FC = () => {
      useEffect(() => {
        const UIKitSettings = new UIKitSettingsBuilder()
          .setAppId(COMETCHAT_CONSTANTS.APP_ID)
          .setRegion(COMETCHAT_CONSTANTS.REGION)
          .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
          .subscribePresenceForAllUsers()
          .build();

        CometChatUIKit.init(UIKitSettings)
          ?.then(() => {
            setupLocalization();
            console.log("Initialization completed successfully");

            const UID = "YOUR_UID"; // Replace with your actual UID

            CometChatUIKit.getLoggedinUser().then((user: CometChat.User | null) => {
              if (!user) {
                // If no user is logged in, proceed with login
                CometChatUIKit.login(UID)
                  .then((loggedInUser: CometChat.User) => {
                    console.log("Login Successful:", loggedInUser);
                    // Mount your app or perform post-login actions if needed
                  })
                  .catch((error) => {
                    console.error("Login failed:", error);
                  });
              } else {
                console.log("User already logged in:", user);
              }
            });
          })
          .catch((error) => console.error("Initialization failed", error));
      }, []);

      return (
        <div style={{ width: "100vw", height: "100vh" }}>
          <CometChatProvider>
            <CometChatApp />
          </CometChatProvider>
        </div>
      );
    };

    export default CometChatNoSSR;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js lines highlight={11-13} theme={null}
    import React, { useEffect } from "react";
    import {
      CometChatUIKit,
      UIKitSettingsBuilder,
    } from "@cometchat/chat-uikit-react";
    import CometChatApp from "../CometChat/CometChatApp";
    import { CometChatProvider } from "../CometChat/context/CometChatContext";
    import { setupLocalization } from "../CometChat/utils/utils";

    export const COMETCHAT_CONSTANTS = {
      APP_ID: "YOUR_APP_ID", // Replace with your App ID
      REGION: "YOUR_REGION", // Replace with your App Region
      AUTH_KEY: "YOUR_AUTH_KEY", // Replace with your Auth Key or leave blank if you are authenticating using Auth Token
    };

    const CometChatNoSSR = () => {
      useEffect(() => {
        const UIKitSettings = new UIKitSettingsBuilder()
          .setAppId(COMETCHAT_CONSTANTS.APP_ID)
          .setRegion(COMETCHAT_CONSTANTS.REGION)
          .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
          .subscribePresenceForAllUsers()
          .build();

        CometChatUIKit.init(UIKitSettings)
          ?.then(() => {
            setupLocalization();
            console.log("Initialization completed successfully");

            const UID = "YOUR_UID"; // Replace with your actual UID

            CometChatUIKit.getLoggedinUser().then((user) => {
              if (!user) {
                // If no user is logged in, proceed with login
                CometChatUIKit.login(UID)
                  .then((loggedInUser) => {
                    console.log("Login Successful:", loggedInUser);
                    // Mount your app or perform post-login actions if needed
                  })
                  .catch((error) => {
                    console.error("Login failed:", error);
                  });
              } else {
                console.log("User already logged in:", user);
              }
            });
          })
          .catch((error) => console.error("Initialization failed", error));
      }, []);

      return (
        <div style={{ width: "100vw", height: "100vh" }}>
          <CometChatProvider>
            <CometChatApp />
          </CometChatProvider>
        </div>
      );
    };

    export default CometChatNoSSR;
    ```
  </Tab>
</Tabs>

<Note>
  **Auth Key vs Auth Token**

  Auth Key is perfect for prototyping. For production apps, switch to Auth Token for secure authentication. See [Authentication and User Management](/docs/fundamentals/user-auth) for details.
</Note>

***

### **Step 5: Disable SSR & Render CometChat Component**

In this step, we’ll render the `CometChatApp` component and specifically disable **Server-Side Rendering (SSR)** for `CometChatNoSSR.tsx`. This targeted approach ensures the CometChat UI Kit Builder components load only on the client side, while the rest of your application remains fully compatible with SSR.

1. **Create a Wrapper File**: Add a new file that houses the `CometChatApp` component.
2. **Dynamically Import `CometChatNoSSR.tsx`**: In this file, use dynamic imports with `{ ssr: false }` to disable SSR only for the CometChat component, preventing SSR-related issues but preserving SSR for the rest of your code.

```javascript lines theme={null}
"use client";
import dynamic from "next/dynamic";

// Dynamically import CometChat component with SSR disabled
const CometChatComponent = dynamic(
  () => import("../app/CometChatNoSSR/CometChatNoSSR"),
  {
    ssr: false,
  },
);

export default function CometChatAppWrapper() {
  return (
    <div>
      <CometChatComponent />
    </div>
  );
}
```

Now, import and use the wrapper component in your project’s main entry file.

```javascript lines theme={null}
import CometChatAppWrapper from "./CometChatAppWrapper";

export default function Home() {
  return (
    <>
      {/* Other components or content */}
      <CometChatAppWrapper />
    </>
  );
}
```

<Note>
  Why disable SSR?

  CometChat UI Kit Builder relies on browser APIs like `window`, `document`, and WebSockets. Since Next.js renders on the server by default, we disable SSR for this component to avoid runtime errors.
</Note>

#### **Render with Default User and Group**

You can also render the component with default user and group selection:

```javascript lines highlight={12-14} theme={null}
import React, { useEffect, useState } from "react";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
} from "@cometchat/chat-uikit-react";
import CometChatApp from "../CometChat/CometChatApp";
import { CometChatProvider } from "../CometChat/context/CometChatContext";
import { setupLocalization } from "../CometChat/utils/utils";
import { CometChat } from "@cometchat/chat-sdk-javascript";

export const COMETCHAT_CONSTANTS = {
  APP_ID: "YOUR_APP_ID", // Replace with your App ID
  REGION: "YOUR_REGION", // Replace with your App Region
  AUTH_KEY: "YOUR_AUTH_KEY", // Replace with your Auth Key or leave blank if you are authenticating using Auth Token
};

// Functional Component
const CometChatNoSSR: React.FC = () => {
  const [user, setUser] = useState<CometChat.User | undefined>(undefined);

  const [selectedUser, setSelectedUser] = useState<CometChat.User | undefined>(
    undefined,
  );
  const [selectedGroup, setSelectedGroup] = useState<
    CometChat.Group | undefined
  >(undefined);

  useEffect(() => {
    const UIKitSettings = new UIKitSettingsBuilder()
      .setAppId(COMETCHAT_CONSTANTS.APP_ID)
      .setRegion(COMETCHAT_CONSTANTS.REGION)
      .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
      .subscribePresenceForAllUsers()
      .build();
    // Initialize CometChat UIKit
    CometChatUIKit.init(UIKitSettings)
      ?.then(() => {
        setupLocalization();
        console.log("Initialization completed successfully");
        CometChatUIKit.getLoggedinUser().then((loggedInUser) => {
          if (!loggedInUser) {
            CometChatUIKit.login("cometchat-uid-1") // Replace with your logged in user UID
              .then((user) => {
                console.log("Login Successful", { user });
                setUser(user);
              })
              .catch((error) => console.error("Login failed", error));
          } else {
            console.log("Already logged-in", { loggedInUser });
            setUser(loggedInUser);
          }
        });
      })
      .catch((error) => console.error("Initialization failed", error));
  }, []);

  useEffect(() => {
    if (user) {
      // Fetch user or group from CometChat SDK whose chat you want to load.

      /** Fetching User */
      const UID = "cometchat-uid-2"; // Replace with your actual UID
      CometChat.getUser(UID).then(
        (user) => {
          setSelectedUser(user);
        },
        (error) => {
          console.log("User fetching failed with error:", error);
        },
      );

      /** Fetching Group */
      // const GUID = "cometchat-guid-1"; // Replace with your actual GUID
      // CometChat.getGroup(GUID).then(
      //   (group) => {
      //    setSelectedGroup(group);
      //  },
      //  (error) => {
      //    console.log("User fetching failed with error:", error);
      //  }
      // );
    }
  }, [user]);

  return (
    /* The CometChatApp component requires a parent element with an explicit height and width
   to render properly. Ensure the container has defined dimensions, and adjust them as needed
   based on your layout requirements. */
    <div style={{ width: "100vw", height: "100dvh" }}>
      <CometChatProvider>
        {(selectedUser || selectedGroup) && (
          <CometChatApp user={selectedUser} group={selectedGroup} />
        )}
      </CometChatProvider>
    </div>
  );
};

export default CometChatNoSSR;
```

#### Without Sidebar Mode

When the sidebar is hidden via the **Without Sidebar** option in UI Kit Builder, the component renders a single chat type based on the `chatType` prop:

| `chatType` | Behavior                                                            |
| ---------- | ------------------------------------------------------------------- |
| `"user"`   | Displays one-on-one conversations with the selected or default user |
| `"group"`  | Displays group conversations with the selected or default group     |

Pass the `user` or `group` prop to specify which conversation opens by default.

***

### **Step 6: Run Your App**

Start your development server:

```bash theme={null}
npm run dev
```

***

## **Troubleshooting**

If you face any issues while integrating the builder in your app project, please check if you have the following configurations added to your `tsConfig.json`:

```json lines theme={null}
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "resolveJsonModule": true
  }
}
```

If your development server is running, restart it to ensure the new TypeScript configuration is picked up.

***

## **Next Steps**

You can continue customizing by editing the exported code directly — or return to the UI Kit Builder to adjust your configuration and re-export a fresh code package.

### **Customize in Code**

Modify the exported components, props, and styling directly in your project.

<CardGroup>
  <Card title="Customizations" href="/chat-builder/nextjs/builder-customisations">
    Adjust component props, behavior, and UI elements.
  </Card>

  <Card title="UI Kit Builder Settings" href="/chat-builder/nextjs/builder-settings">
    Understand the settings file and feature toggles.
  </Card>

  <Card title="Directory Structure" href="/chat-builder/nextjs/builder-dir-structure">
    See how the exported code is organized.
  </Card>

  <Card title="Advanced Theming" href="/ui-kit/react/theme">
    Customize colors, typography, and styling to match your brand.
  </Card>
</CardGroup>

### **Customize via UI Kit Builder**

Return to the Builder to update your configuration, then re-export and replace the code package. Any changes made in the UI Kit Builder will require you to re-export the code and follow the same integration steps above to integrate into your project.

<CardGroup>
  <Card title="Launch UI Kit Builder" icon="arrow-up-right-from-square" href="https://app.cometchat.com">
    Open the CometChat Dashboard to reconfigure and re-export.
  </Card>
</CardGroup>


# CometChat UI Kit Builder For Next.js
Source: https://www.cometchat.com/docs/chat-builder/nextjs/overview

CometChat UI Kit Builder for Next.js is a low-code development tool to design and configure fully-featured chat experiences.

It provides a set of prebuilt, production-ready messaging components backed by CometChat's real-time infrastructure.

With CometChat UI Kit Builder, you can:

* **Configure chat and calling features**
* **Apply theming and layout options**
* **Export Next.js-ready code**

The exported UI connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling.

## What You Can Configure

Toggle these features on or off directly in the UI Kit Builder. For a full reference of each setting, see [UI Kit Builder Settings](/docs/chat-builder/nextjs/builder-settings).

### Chat Features

| Category                            | Includes                                                                                                                                               |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Core Messaging Experience**       | Typing indicators, threads, media sharing (photos, video, audio, files), edit & delete messages, read receipts, search, quoted replies, mark as unread |
| **Deeper User Engagement**          | Mentions, @all mentions, reactions, message translation, polls, collaborative whiteboard & document, voice notes, emojis, stickers, user & group info  |
| **AI User Copilot**                 | Conversation starters, conversation summaries, smart replies                                                                                           |
| **User Management**                 | Friends-only mode                                                                                                                                      |
| **Group Management**                | Create groups, add members, join/leave, delete groups, view members                                                                                    |
| **Moderation**                      | Content moderation, report messages, kick/ban users, promote/demote members                                                                            |
| **Private Messaging Within Groups** | Direct messages between group members                                                                                                                  |
| **In-App Sounds**                   | Incoming & outgoing message sounds                                                                                                                     |

### Call Features

| Category                  | Includes                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------ |
| **Voice & Video Calling** | 1:1 voice calling, 1:1 video calling, group voice conference, group video conference |

### Layout

| Category    | Includes                                |
| ----------- | --------------------------------------- |
| **Sidebar** | With Sidebar or Without Sidebar mode    |
| **Tabs**    | Conversations, Call Logs, Users, Groups |

### Theming

| Category       | Includes                                                    |
| -------------- | ----------------------------------------------------------- |
| **Theme**      | System, Light, or Dark mode                                 |
| **Colors**     | Brand color, primary & secondary text colors (light & dark) |
| **Typography** | Font family, text sizing (default, compact, comfortable)    |

***

## How to Use UI Kit Builder

### 1. Design

Configure your chat layout, toggle features, and pick a theme using the UI Kit Builder.

<Frame>
  <img />
</Frame>

### 2. Export

Click **Export Code** to generate a production-ready Next.js codebase based on your configuration.

### 3. Integrate

Drop the exported code into your Next.js project, add your CometChat credentials, and run the app. See the [Integration Guide](/docs/chat-builder/nextjs/integration) for full steps.

***

## Try Live Demo

Experience the CometChat UI Kit Builder in action:

<CardGroup>
  <Card title="Launch Live Demo" icon="play" href="https://preview.cometchat.com/" />
</CardGroup>

or follow the video walkthrough below:

<Frame>
  <iframe title="YouTube video" />
</Frame>


# Customizing Your UI Kit Builder
Source: https://www.cometchat.com/docs/chat-builder/react-router/builder-customisations

Customize React Router UI Kit Builder components by adjusting CometChat app props, styling, group messages, and behavior.

The `CometChatSettings.ts` file handles basic feature toggles. For deeper customizations, modify component props or source code directly.

***

## **App-Level Customizations**

These ready-to-use props on the `CometChatApp` component let you quickly adjust common behaviors without modifying any internal components.

### **Group Action Messages**

Control the visibility of group action messages using the `showGroupActionMessages` prop:

```jsx theme={null}
<CometChatApp showGroupActionMessages={true} />
```

* `true` (default) — Group action messages are **visible**
* `false` — Group action messages are **hidden**

### **Auto Open First Item**

Control whether the first item in lists automatically opens on render using the `autoOpenFirstItem` prop:

```jsx theme={null}
<CometChatApp autoOpenFirstItem={false} />
```

* `true` (default) — The first item in conversation list, user list, or group list opens automatically on first render
* `false` — No item opens until the user clicks on one

***

## **Component-Level Customizations**

For more advanced customizations tailored to your app's needs, you can modify individual UI Kit components directly.

### **How to Customize**

1. Find the component in the [UI Kit Components Overview](/docs/ui-kit/react/components-overview)
2. Check available props and customization options
3. Update props or edit the component source code

Below are some examples to help you get started with common customizations like date formats, conversation subtitles, and send buttons.

### **Custom Date Format**

Customize how sticky date headers appear in the message list.

**Component**: [Message List](/docs/ui-kit/react/message-list) → [`stickyDateTimeFormat`](/docs/ui-kit/react/message-list#sticky-datetime-format)

```jsx lines theme={null}
import {
  CometChatMessageList,
  CalendarObject,
} from "@cometchat/chat-uikit-react";

const dateFormat = new CalendarObject({
  today: "hh:mm A", // "10:30 AM"
  yesterday: "[Yesterday]",
  otherDays: "DD/MM/YYYY", // "25/05/2025"
});

<CometChatMessageList user={chatUser} stickyDateTimeFormat={dateFormat} />;
```

<Frame>
  <img />
</Frame>

**Default format** (for reference):

```javascript lines theme={null}
new CalendarObject({
  today: "today",
  yesterday: "yesterday",
  otherDays: "DD MMM, YYYY", // "25 Jan, 2025"
});
```

***

### **Custom Conversation Subtitle**

Show online status or member count instead of the default last message preview.

**Component**: [Conversations](/docs/ui-kit/react/conversations) → [`subtitleView`](/docs/ui-kit/react/conversations#subtitleview)

```jsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatConversations } from "@cometchat/chat-uikit-react";

const customSubtitleView = (conversation) => {
  if (conversation.getConversationType() === "user") {
    const user = conversation.getConversationWith();
    return (
      <span>{user.getStatus() === "online" ? "🟢 Online" : "⚫ Offline"}</span>
    );
  } else {
    const group = conversation.getConversationWith();
    return <span>{group.getMembersCount()} members</span>;
  }
};

<CometChatConversations subtitleView={customSubtitleView} />;
```

***

### **Custom Send Button**

Replace the default send button with your brand's icon.

**Component**: [Message Composer](/docs/ui-kit/react/message-composer) → [`sendButtonView`](/docs/ui-kit/react/message-composer#sendbuttonview)

```jsx lines theme={null}
import {
  CometChatMessageComposer,
  CometChatButton,
} from "@cometchat/chat-uikit-react";

const brandedSendButton = (
  <CometChatButton
    iconURL="/icons/brand-send.svg"
    onClick={() => {
      // Your custom send logic
    }}
  />
);

<CometChatMessageComposer user={chatUser} sendButtonView={brandedSendButton} />;
```

```css lines theme={null}
/* Style the custom send button */
.cometchat-message-composer .cometchat-button {
  background: #6852d6;
  border-radius: 50%;
}

.cometchat-message-composer .cometchat-button__icon {
  background: #ffffff;
}
```

***

## **Next Steps**

<CardGroup>
  <Card title="UI Kit Builder Settings" href="/chat-builder/react-router/builder-settings">
    Configure feature toggles and behavior
  </Card>

  <Card title="Components Overview" href="/ui-kit/react/components-overview">
    Explore all available UI components
  </Card>

  <Card title="Theming" href="/ui-kit/react/theme">
    Customize colors, typography, and styling
  </Card>

  <Card title="Localization" href="/ui-kit/react/localize">
    Add multi-language support
  </Card>
</CardGroup>


# Directory Structure
Source: https://www.cometchat.com/docs/chat-builder/react-router/builder-dir-structure

Overview of the CometChat UI Kit Builder directory layout for React Router — understand where to find and customize components, settings, and styles.

The exported UI Kit Builder code lives in `src/CometChat/`. This guide helps you navigate the structure so you know exactly where to make changes.

<Tree>
  <Tree.Folder name="src">
    <Tree.Folder name="CometChat">
      <Tree.Folder name="assets">
        <Tree.File name="Icons, images, audio files" />
      </Tree.Folder>

      <Tree.Folder name="components">
        <Tree.File name="React components (UI elements)" />
      </Tree.Folder>

      <Tree.Folder name="context">
        <Tree.File name="React Context providers (state management)" />
      </Tree.Folder>

      <Tree.Folder name="locales">
        <Tree.File name="Translation files (en, fr, de, etc.)" />
      </Tree.Folder>

      <Tree.Folder name="styles">
        <Tree.File name="CSS files (mirrors components structure)" />
      </Tree.Folder>

      <Tree.Folder name="utils">
        <Tree.File name="Utility functions and helpers" />
      </Tree.Folder>

      <Tree.File name="CometChatApp.tsx" />

      <Tree.File name="CometChatSettings.ts" />

      <Tree.File name="customHooks.ts" />

      <Tree.File name="decl.d.ts" />

      <Tree.File name="styleConfig.ts" />
    </Tree.Folder>

    <Tree.File name="App.tsx" />

    <Tree.File name="index.tsx" />
  </Tree.Folder>
</Tree>

***

## Root Files

| File                   | Purpose                                                      |
| ---------------------- | ------------------------------------------------------------ |
| `CometChatApp.tsx`     | Main entry point — import this to render the chat experience |
| `CometChatSettings.ts` | Toggle features on/off (messaging, calls, AI copilot, etc.)  |
| `customHooks.ts`       | Custom React hooks used throughout the application           |
| `styleConfig.ts`       | Global styling configuration (colors, fonts, spacing)        |

***

## Key Folders

### `components/`

Each component folder contains the main `.tsx` file and associated hooks (`use*.ts`). These are the building blocks of your chat UI.

<Tree>
  <Tree.Folder name="components">
    <Tree.Folder name="CometChatAddMembers">
      <Tree.File name="Add members to groups" />
    </Tree.Folder>

    <Tree.Folder name="CometChatBannedMembers">
      <Tree.File name="Manage banned users" />
    </Tree.Folder>

    <Tree.Folder name="CometChatCallLog">
      <Tree.File name="Call history display" />
    </Tree.Folder>

    <Tree.Folder name="CometChatCreateGroup">
      <Tree.File name="Group creation flow" />
    </Tree.Folder>

    <Tree.Folder name="CometChatDetails">
      <Tree.File name="User/group details panel" />
    </Tree.Folder>

    <Tree.Folder name="CometChatHome">
      <Tree.File name="Main chat home screen" />
    </Tree.Folder>

    <Tree.Folder name="CometChatJoinGroup">
      <Tree.File name="Join group flow" />
    </Tree.Folder>

    <Tree.Folder name="CometChatLogin">
      <Tree.File name="Login screen" />
    </Tree.Folder>

    <Tree.Folder name="CometChatMessages">
      <Tree.File name="Message list and composer" />
    </Tree.Folder>

    <Tree.Folder name="CometChatSelector">
      <Tree.File name="Conversation/user selector" />
    </Tree.Folder>

    <Tree.Folder name="CometChatTransferOwnership">
      <Tree.File name="Transfer group ownership" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

### `context/`

State management for the chat application.

<Tree>
  <Tree.Folder name="context">
    <Tree.File name="AppContext.tsx" />

    <Tree.File name="CometChatContext.tsx" />

    <Tree.File name="appReducer.ts" />
  </Tree.Folder>
</Tree>

### `styles/`

CSS files organized to mirror the components structure. Each component has a corresponding style folder.

### `locales/`

Translation files for multi-language support. Add or modify JSON files here to customize text.

***

## Quick Reference: Where to Customize

| What you want to change | Where to look                 |
| ----------------------- | ----------------------------- |
| Enable/disable features | `CometChatSettings.ts`        |
| Theme colors & fonts    | `styleConfig.ts`              |
| Component-specific CSS  | `styles/<ComponentName>/`     |
| Text & translations     | `locales/<lang>/<lang>.json`  |
| Component behavior      | `components/<ComponentName>/` |

<Note>
  Prefer using settings and CSS overrides. For extensive changes, create wrapper
  components instead of modifying core files directly.
</Note>

***

## Next Steps

<CardGroup>
  <Card title="UI Kit Builder Settings" href="/chat-builder/react-router/builder-settings">
    Configure feature toggles and behavior
  </Card>

  <Card title="Customizations" href="/chat-builder/react-router/builder-customisations">
    Modify component props, styling, and behavior
  </Card>

  <Card title="Theming" href="/ui-kit/react/theme">
    Customize colors, typography, and styling
  </Card>

  <Card title="Localization" href="/ui-kit/react/localize">
    Add multi-language support
  </Card>
</CardGroup>


# UI Kit Builder Settings
Source: https://www.cometchat.com/docs/chat-builder/react-router/builder-settings

Configure React Router UI Kit Builder settings for messaging, AI helpers, calling, layout, theming, and agent tools.

The `CometChatSettings` object controls everything the React Router UI Kit Builder renders—messaging, AI helpers, calls, layout, theming, and agent tools.

<Info>
  **For developers customizing their chat UI**: Edit `CometChatSettings.ts` to
  enable/disable features like messaging, calls, AI copilot, and theming. See
  [Integration Guide](/docs/chat-builder/react-router/integration) for setup.
</Info>

## Top-level structure

```ts lines theme={null}
export interface CometChatSettings {
  chatFeatures: { ... }
  callFeatures: { ... }
  layout: { ... }
  style: { ... }
}
```

***

<Tip>
  All boolean settings follow the same pattern: `true` enables the feature and shows its UI elements, `false` hides them completely.
</Tip>

## 1. Chat Features (`chatFeatures`)

### 1.1 Core Messaging Experience (`coreMessagingExperience`)

Essential messaging features: typing indicators, media sharing, message actions, and presence.

| Setting                                                               | Type    | What It Does                                                                        |
| --------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| Typing indicator (`typingIndicator`)                                  | boolean | Shows "typing..." indicator when someone is composing a message                     |
| Thread conversation & replies (`threadConversationAndReplies`)        | boolean | Enables threaded replies to specific messages, creating nested conversation threads |
| Photos sharing (`photosSharing`)                                      | boolean | Allows users to share images from device or camera                                  |
| Video sharing (`videoSharing`)                                        | boolean | Allows users to share video files                                                   |
| Audio sharing (`audioSharing`)                                        | boolean | Allows users to share audio files (mp3, wav, etc.)                                  |
| File sharing (`fileSharing`)                                          | boolean | Allows users to share documents (PDF, DOC, etc.)                                    |
| Edit messages (`editMessage`)                                         | boolean | Lets users modify their sent messages; edited messages show "(edited)" label        |
| Delete messages (`deleteMessage`)                                     | boolean | Lets users remove their sent messages                                               |
| Message delivery and read receipts (`messageDeliveryAndReadReceipts`) | boolean | Shows delivery (✓) and read (✓✓) status indicators on messages                      |
| User & friends presence (`userAndFriendsPresence`)                    | boolean | Shows online/offline status dot next to user avatars                                |
| Conversation and Advanced Search (`conversationAndAdvancedSearch`)    | boolean | Enables search across messages, users, and conversations                            |
| Quoted Replies (`quotedReplies`)                                      | boolean | Lets users quote a message when replying, showing the original above their response |
| Mark as Unread (`markAsUnread`)                                       | boolean | Lets users mark a conversation as unread to revisit later                           |

<Tip>
  Empower users with a seamless chat experience—reply to specific messages with
  quoted replies, mark conversations as unread for later, and search across all
  chats instantly. Learn more about [Core
  Features](/docs/ui-kit/react/core-features).
</Tip>

### 1.2 Deeper User Engagement (`deeperUserEngagement`)

Interactive features: mentions, reactions, polls, voice notes, and collaborative tools.

| Setting                                              | Type    | What It Does                                                                                |
| ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| Mentions (`mentions`)                                | boolean | Lets users @mention specific people in a message to notify them                             |
| Mention All (`mentionAll`)                           | boolean | Lets users type @all to notify every member in a group chat                                 |
| Reactions (`reactions`)                              | boolean | Lets users add emoji reactions (👍 ❤️ 😂 etc.) to messages                                  |
| Message Translation (`messageTranslation`)           | boolean | Translates messages to user's preferred language. Requires Dashboard setup                  |
| Polls (`polls`)                                      | boolean | Lets users create polls with multiple options for group voting. Requires Dashboard setup    |
| Collaborative Whiteboard (`collaborativeWhiteboard`) | boolean | Opens a shared whiteboard for real-time drawing and collaboration. Requires Dashboard setup |
| Collaborative Document (`collaborativeDocument`)     | boolean | Creates shared documents for real-time collaborative editing. Requires Dashboard setup      |
| Voice Notes (`voiceNotes`)                           | boolean | Lets users record and send voice messages                                                   |
| Emojis (`emojis`)                                    | boolean | Shows emoji picker in composer for browsing and inserting emojis                            |
| Stickers (`stickers`)                                | boolean | Lets users send sticker images from available packs. Requires Dashboard setup               |
| User Info (`userInfo`)                               | boolean | Lets users tap on another user's avatar to view their profile                               |
| Group Info (`groupInfo`)                             | boolean | Lets users tap on group header to view group details and member list                        |
| Report Message (`reportMessage`)                     | boolean | Lets users flag inappropriate messages for review. Requires moderation setup                |

<Tip>
  Configure these features based on your app's requirements. Learn more about
  [Extensions](/docs/ui-kit/react/extensions).
</Tip>

### 1.3 AI User Copilot (`aiUserCopilot`)

AI-powered features to help users start and navigate conversations.

| Setting                                      | Type    | What It Does                                                                                  |
| -------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| Conversation Starter (`conversationStarter`) | boolean | Shows AI-suggested opening messages when starting a new chat. Requires OpenAI API key         |
| Conversation Summary (`conversationSummary`) | boolean | Generates an AI-powered summary of the conversation. Requires OpenAI API key                  |
| Smart Reply (`smartReply`)                   | boolean | Shows AI-suggested quick reply options based on conversation context. Requires OpenAI API key |

<Tip>
  AI User Copilot features require an OpenAI API key. Configure it in the [CometChat Dashboard](https://app.cometchat.com) under **Chat & Messaging > Settings**. Learn more about [AI Features](/docs/ui-kit/react/ai-features).
</Tip>

### 1.4 User Management (`userManagement`)

| Setting                      | Type    | What It Does                                                      |
| ---------------------------- | ------- | ----------------------------------------------------------------- |
| Friends Only (`friendsOnly`) | boolean | Restricts chat to friends list only; Users tab shows only friends |

### 1.5 Group Management (`groupManagement`)

Control what users can do with groups.

| Setting                                      | Type    | What It Does                                                      |
| -------------------------------------------- | ------- | ----------------------------------------------------------------- |
| Create Group (`createGroup`)                 | boolean | Lets users create new public or private groups                    |
| Add Members to Groups (`addMembersToGroups`) | boolean | Lets group admins/owners invite users to join the group           |
| Join/Leave Group (`joinLeaveGroup`)          | boolean | Lets users join public groups and leave groups they're in         |
| Delete Group (`deleteGroup`)                 | boolean | Lets group owners permanently delete a group and all its messages |
| View Group Members (`viewGroupMembers`)      | boolean | Shows member list in group info                                   |

### 1.6 Moderation (`moderatorControls`)

Admin tools for managing group members and content.

| Setting                                         | Type    | What It Does                                                                                                       |
| ----------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| Blocked message feedback (`moderation`)         | boolean | Enables blocked message feedback for blocked messages as per configured moderation rules. Requires Dashboard setup |
| Report Message (`reportMessage`)                | boolean | Lets users flag messages for moderator review in Dashboard                                                         |
| Kick Users (`kickUsers`)                        | boolean | Lets admins/moderators remove a user from a group (they can rejoin)                                                |
| Ban Users (`banUsers`)                          | boolean | Lets admins/moderators permanently remove a user and prevent rejoining                                             |
| Promote/Demote Members (`promoteDemoteMembers`) | boolean | Lets group owners change member roles (member, moderator, admin)                                                   |

<Tip>
  To enable content moderation, set `moderation` and `reportMessage` to `true`,
  then configure your moderation rules in the [CometChat
  Dashboard](https://app.cometchat.com). See [Rules
  Management](/docs/moderation/getting-started#setting-up-moderation-rules) for setup
  details.
</Tip>

### 1.7 Private Messaging Within Groups (`privateMessagingWithinGroups`)

Allow direct messages between group members.

| Setting                                                                    | Type    | What It Does                                                       |
| -------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| Send Private Message to Group Members (`sendPrivateMessageToGroupMembers`) | boolean | Lets users start a 1:1 chat with a group member from their profile |

### 1.8 In-App Sounds (`inAppSounds`)

Control sound notifications for incoming and outgoing messages.

| Setting                                         | Type    | What It Does                                 |
| ----------------------------------------------- | ------- | -------------------------------------------- |
| Incoming Message Sound (`incomingMessageSound`) | boolean | Plays a sound when a new message is received |
| Outgoing Message Sound (`outgoingMessageSound`) | boolean | Plays a sound when a message is sent         |

<Tip>
  These toggles control the default message sounds. To use custom audio files or manage sound playback programmatically, see the [Sound Manager](/docs/ui-kit/react/sound-manager).
</Tip>

***

## 2. Call Features (`callFeatures`)

### 2.1 Voice and Video Calling (`voiceAndVideoCalling`)

Enable voice and video calling capabilities.

| Setting                                         | Type    | What It Does                                                                |
| ----------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| 1:1 Voice Calling (`oneOnOneVoiceCalling`)      | boolean | Shows phone icon in 1:1 chat header for starting voice calls                |
| 1:1 Video Calling (`oneOnOneVideoCalling`)      | boolean | Shows video camera icon in 1:1 chat header for starting video calls         |
| Group Video Conference (`groupVideoConference`) | boolean | Shows video camera icon in group chat header for starting group video calls |
| Group Voice Conference (`groupVoiceConference`) | boolean | Shows phone icon in group chat header for starting group voice calls        |

<Tip>
  Learn more about [Call Features](/docs/ui-kit/react/call-features#features).
</Tip>

***

## 3. Layout (`layout`)

Control the overall UI structure and navigation.

| Setting                      | Type      | What It Does                                                                         |
| ---------------------------- | --------- | ------------------------------------------------------------------------------------ |
| With Sidebar (`withSideBar`) | boolean   | Shows navigation sidebar with tabs (Chats, Calls, Users, Groups) on the left side    |
| Tabs (`tabs`)                | string\[] | Array of tabs to show: `'chats'`, `'calls'`, `'users'`, `'groups'`                   |
| Chat Type (`chatType`)       | string    | Default conversation type on load: `'user'` for 1:1 chats, `'group'` for group chats |

<Tip>
  Set `withSideBar: false` for embedded chat widgets or single-conversation
  views where navigation isn't needed.
</Tip>

***

## 4. Style (`style`)

Customize colors, fonts, and theme appearance.

### 4.1 Theme

| Setting         | Type   | What It Does                                                                             |
| --------------- | ------ | ---------------------------------------------------------------------------------------- |
| Theme (`theme`) | string | Controls light/dark mode: `'light'`, `'dark'`, or `'system'` (matches device preference) |

<Tip>
  Use `theme: "system"` to automatically match the user's device preference.
  Preview your `brandColor` in both light and dark modes for contrast.

  [Learn more about UI Kit Theming](/docs/ui-kit/react/theme) for additional customizations.
</Tip>

### 4.2 Colors

| Setting                                     | Type   | What It Does                                                                             |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| Brand Color (`brandColor`)                  | string | Primary accent color (hex) for buttons, links, active states. Example: `"#6852D6"`       |
| Primary Text Light (`primaryTextLight`)     | string | Main text color in light mode (hex). Example: `"#2B2B2B"`                                |
| Primary Text Dark (`primaryTextDark`)       | string | Main text color in dark mode (hex). Example: `"#FFFFFF"`                                 |
| Secondary Text Light (`secondaryTextLight`) | string | Secondary text color in light mode (hex) for timestamps, subtitles. Example: `"#727272"` |
| Secondary Text Dark (`secondaryTextDark`)   | string | Secondary text color in dark mode (hex) for timestamps, subtitles. Example: `"#989898"`  |

<Tip>
  Match `brandColor` to your website's primary accent color. Use your site's
  existing text colors for `primaryTextLight` and `primaryTextDark` to maintain
  brand consistency.
</Tip>

### 4.3 Typography

| Setting       | Type   | What It Does                                                          |
| ------------- | ------ | --------------------------------------------------------------------- |
| Font (`font`) | string | Font family: `'roboto'`, `'arial'`, `'inter'`, or `'times new roman'` |
| Size (`size`) | string | Text size and spacing: `'default'`, `'compact'`, or `'comfortable'`   |

***

## Settings Overview

Below is the complete settings structure with default values. Update these in `CometChatSettings.ts` to customize your chat experience.

```json lines theme={null}
{
  "chatFeatures": {
    "coreMessagingExperience": {
      "typingIndicator": true,
      "threadConversationAndReplies": true,
      "photosSharing": true,
      "videoSharing": true,
      "audioSharing": true,
      "fileSharing": true,
      "editMessage": true,
      "deleteMessage": true,
      "messageDeliveryAndReadReceipts": true,
      "userAndFriendsPresence": true,
      "conversationAndAdvancedSearch": true,
      "moderation": true,
      "quotedReplies": false,
      "markAsUnread": false
    },
    "deeperUserEngagement": {
      "mentions": true,
      "mentionAll": true,
      "reactions": true,
      "messageTranslation": true,
      "polls": true,
      "collaborativeWhiteboard": true,
      "collaborativeDocument": true,
      "voiceNotes": true,
      "emojis": true,
      "stickers": true,
      "userInfo": true,
      "groupInfo": true
    },
    "aiUserCopilot": {
      "conversationStarter": false,
      "conversationSummary": false,
      "smartReply": false
    },
    "userManagement": {
      "friendsOnly": false
    },
    "groupManagement": {
      "createGroup": true,
      "addMembersToGroups": true,
      "joinLeaveGroup": true,
      "deleteGroup": true,
      "viewGroupMembers": true
    },
    "moderatorControls": {
      "kickUsers": true,
      "banUsers": true,
      "promoteDemoteMembers": true,
      "reportMessage": true
    },
    "privateMessagingWithinGroups": {
      "sendPrivateMessageToGroupMembers": true
    },
    "inAppSounds": {
      "incomingMessageSound": true,
      "outgoingMessageSound": true
    }
  },
  "callFeatures": {
    "voiceAndVideoCalling": {
      "oneOnOneVoiceCalling": true,
      "oneOnOneVideoCalling": true,
      "groupVideoConference": true,
      "groupVoiceConference": true
    }
  },
  "layout": {
    "withSideBar": true,
    "tabs": ["chats", "calls", "users", "groups"],
    "chatType": "user"
  },
  "style": {
    "theme": "system",
    "color": {
      "brandColor": "#6852D6",
      "primaryTextLight": "#141414",
      "primaryTextDark": "#FFFFFF",
      "secondaryTextLight": "#727272",
      "secondaryTextDark": "#989898"
    },
    "typography": {
      "font": "roboto",
      "size": "default"
    }
  }
}
```

***

## Next Steps

<CardGroup>
  <Card title="Directory Structure" href="/chat-builder/react-router/builder-dir-structure">
    Understand the organization of the builder components and generated code.
  </Card>

  <Card title="Customizations" href="/chat-builder/react-router/builder-customisations">
    Modify component props, styling, and behavior for deeper customization.
  </Card>
</CardGroup>


# UI Kit Builder Integration
Source: https://www.cometchat.com/docs/chat-builder/react-router/integration

Add CometChat UI Kit Builder to React Router apps with configurable chat features, themes, layouts, login, and SSR support.

The **UI Kit Builder** simplifies integrating CometChat's UI Kit into your React Router application — quickly set up chat, customize UI elements, and add features without extensive coding.

<Frame>
  <img />
</Frame>

## **Complete Integration Workflow**

1. **Design Your Chat Experience** - Use the **UI Kit Builder** to customize layouts, features, and styling.
2. **Review and Export** - Review which features will be enabled in your Dashboard, toggle them on/off, and download the generated code package.
3. **Preview Customizations** - Optionally, preview the chat experience before integrating it into your project.
4. **Integration** - Integrate into your existing application.
5. **Customize Further** - Explore advanced customization options to tailor the chat experience.

<Frame>
  <iframe title="YouTube video" />
</Frame>

***

## **Launch the UI Kit Builder**

1. Log in to your [**CometChat Dashboard**](https://app.cometchat.com).
2. Select your application from the list.
3. Navigate to **Chat & Messaging** → **Get Started**.
4. Choose your platform and click **Launch UI Kit Builder**.

***

## **Review Your Export**

When you click **Export**, a "Review Your Export" modal appears (Step 1 of 3). This lets you:

* **Review features** — See which features will be enabled in your CometChat Dashboard based on your UI Kit configuration
* **Toggle features** — Turn individual features on/off before export
* **AI User Copilot** — Requires an OpenAI API key (you'll configure this in the next step)

<Frame>
  <img />
</Frame>

<Note>
  Only checked features will be enabled in your Dashboard. You can always modify
  these settings later in the [CometChat Dashboard](https://app.cometchat.com).
</Note>

***

## **Preview Customizations (Optional)**

Before integrating the **UI Kit Builder** into your project, you can preview the chat experience by following these steps. This step is completely optional and can be skipped if you want to directly integrate the **UI Kit Builder** into your project.

> You can preview the experience:
>
> 1. Open the `cometchat-app-react` folder.
> 2. Install dependencies:
>
> ```
> npm i
> ```
>
> 3. Run the app:
>
> ```powershell theme={null}
> npm start
> ```
>
> Your app credentials are already prepopulated in the exported code.

***

## **Integrate into Your Project**

Follow these steps to integrate CometChat UI Kit Builder into your existing React Router project:

### **Step 1: Install Dependencies**

Run the following command to install the required dependencies:

```ruby theme={null}
npm install @cometchat/chat-uikit-react@6.3.11 @cometchat/calls-sdk-javascript
```

### **Step 2: Copy CometChat Folder**

Copy the `cometchat-app-react/src/CometChat` folder into your project's `src` directory.

### **Step 3: Initialize CometChat UI Kit**

Initialize CometChat in your app's entry file. Select your setup:

<Tabs>
  <Tab title="Vite">
    ```tsx lines highlight={12-14} src/main.tsx theme={null}
    import { createRoot } from "react-dom/client";
    import "./index.css";
    import App from "./App.tsx";
    import {
      UIKitSettingsBuilder,
      CometChatUIKit,
    } from "@cometchat/chat-uikit-react";
    import { setupLocalization } from "./CometChat/utils/utils.ts";
    import { CometChatProvider } from "./CometChat/context/CometChatContext";

    export const COMETCHAT_CONSTANTS = {
      APP_ID: "YOUR_APP_ID", // Replace with your App ID
      REGION: "YOUR_REGION", // Replace with your App Region
      AUTH_KEY: "YOUR_AUTH_KEY", // Replace with your Auth Key or leave blank if you are authenticating using Auth Token
    };

    const uiKitSettings = new UIKitSettingsBuilder()
      .setAppId(COMETCHAT_CONSTANTS.APP_ID)
      .setRegion(COMETCHAT_CONSTANTS.REGION)
      .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(uiKitSettings)?.then(() => {
      setupLocalization();
      createRoot(document.getElementById("root")!).render(
        <CometChatProvider>
          <App />
        </CometChatProvider>,
      );
    });
    ```
  </Tab>

  <Tab title="CRA">
    ```tsx lines highlight={12-14} src/index.tsx theme={null}
    import React from "react";
    import ReactDOM from "react-dom/client";
    import App from "./App";
    import {
      UIKitSettingsBuilder,
      CometChatUIKit,
    } from "@cometchat/chat-uikit-react";
    import { setupLocalization } from "./CometChat/utils/utils";
    import { CometChatProvider } from "./CometChat/context/CometChatContext";

    export const COMETCHAT_CONSTANTS = {
      APP_ID: "YOUR_APP_ID", // Replace with your App ID
      REGION: "YOUR_REGION", // Replace with your App Region
      AUTH_KEY: "YOUR_AUTH_KEY", // Replace with your Auth Key or leave blank if you are authenticating using Auth Token
    };

    const uiKitSettings = new UIKitSettingsBuilder()
      .setAppId(COMETCHAT_CONSTANTS.APP_ID)
      .setRegion(COMETCHAT_CONSTANTS.REGION)
      .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(uiKitSettings)?.then(() => {
      setupLocalization();
      ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
        <CometChatProvider>
          <App />
        </CometChatProvider>,
      );
    });
    ```
  </Tab>
</Tabs>

<Info>
  Your app credentials (`APP_ID`, `AUTH_KEY`, `REGION`) are prepopulated in the exported code. If you need to use different credentials, you can find them in the Credentials block of your app's [Overview section](https://app.cometchat.com) on the CometChat Dashboard.
</Info>

### **Step 4: User Authentication**

CometChat uses a UID (User ID) to identify each user. After initialization, authenticate users to enable chat functionality.

You can either:

1. **Create new users** on the **[CometChat Dashboard](https://app.cometchat.com)**, **[CometChat SDK Method](/docs/ui-kit/react/methods#create-user)** or **[via the API](https://www.cometchat.com/docs/rest-api/users/create)**.

2. **Use pre-generated test users**: `cometchat-uid-1` through `cometchat-uid-5`

The **Login** method returns a **User object** containing all relevant details of the logged-in user.

**Login After Initialization**

Log in the user after initialization — useful when login happens later in your app flow (e.g., after a login form).

<Tabs>
  <Tab title="TypeScript">
    ```ts lines highlight={3} theme={null}
    import { CometChatUIKit } from "@cometchat/chat-uikit-react";

    const UID = "YOUR_UID"; // Replace with your actual UID

    CometChatUIKit.getLoggedinUser().then((user: CometChat.User | null) => {
      if (!user) {
        // If no user is logged in, proceed with login
        CometChatUIKit.login(UID)
          .then((user: CometChat.User) => {
            console.log("Login Successful:", { user });
            // Mount your app
          })
          .catch(console.log);
      } else {
        // If user is already logged in, mount your app
      }
    });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js lines highlight={3} theme={null}
    import { CometChatUIKit } from "@cometchat/chat-uikit-react";

    const UID = "YOUR_UID"; // Replace with your actual UID

    CometChatUIKit.getLoggedinUser().then((user) => {
      if (!user) {
        // If no user is logged in, proceed with login
        CometChatUIKit.login(UID)
          .then((user) => {
            console.log("Login Successful:", { user });
            // Mount your app
          })
          .catch(console.log);
      } else {
        // If user is already logged in, mount your app
      }
    });
    ```
  </Tab>
</Tabs>

**Login During Initialization**

Alternatively, log in the user immediately inside `CometChatUIKit.init()` — ideal for apps that authenticate on startup.

<Tabs>
  <Tab title="TypeScript">
    ```ts lines highlight={12-14, 27} theme={null}
    import React from "react";
    import ReactDOM from "react-dom/client";
    import App from "./App";
    import {
      UIKitSettingsBuilder,
      CometChatUIKit,
    } from "@cometchat/chat-uikit-react";
    import { setupLocalization } from "./CometChat/utils/utils";
    import { CometChatProvider } from "./CometChat/context/CometChatContext";

    export const COMETCHAT_CONSTANTS = {
      APP_ID: "YOUR_APP_ID", // Replace with your App ID
      REGION: "YOUR_REGION", // Replace with your App Region
      AUTH_KEY: "YOUR_AUTH_KEY", // Replace with your Auth Key or leave blank if you are authenticating using Auth Token
    };

    const uiKitSettings = new UIKitSettingsBuilder()
      .setAppId(COMETCHAT_CONSTANTS.APP_ID)
      .setRegion(COMETCHAT_CONSTANTS.REGION)
      .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(uiKitSettings)?.then(() => {
      setupLocalization();

      const UID = "YOUR_UID"; // Replace with your actual UID

      CometChatUIKit.getLoggedinUser().then((user: CometChat.User | null) => {
        if (!user) {
          CometChatUIKit.login(UID)
            .then((loggedUser: CometChat.User) => {
              console.log("Login Successful:", loggedUser);
              // Mount your app
              ReactDOM.createRoot(
                document.getElementById("root") as HTMLElement,
              ).render(
                <CometChatProvider>
                  <App />
                </CometChatProvider>,
              );
            })
            .catch((error) => console.error("Login Failed:", error));
        } else {
          // User already logged in, mount app directly
          console.log("User already logged in:", user);
          ReactDOM.createRoot(
            document.getElementById("root") as HTMLElement,
          ).render(
            <CometChatProvider>
              <App />
            </CometChatProvider>,
          );
        }
      });
    });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js lines highlight={12-14, 27} theme={null}
    import React from "react";
    import ReactDOM from "react-dom/client";
    import App from "./App";
    import {
      UIKitSettingsBuilder,
      CometChatUIKit,
    } from "@cometchat/chat-uikit-react";
    import { setupLocalization } from "./CometChat/utils/utils";
    import { CometChatProvider } from "./CometChat/context/CometChatContext";

    export const COMETCHAT_CONSTANTS = {
      APP_ID: "YOUR_APP_ID", // Replace with your App ID
      REGION: "YOUR_REGION", // Replace with your App Region
      AUTH_KEY: "YOUR_AUTH_KEY", // Replace with your Auth Key or leave blank if you are authenticating using Auth Token
    };

    const uiKitSettings = new UIKitSettingsBuilder()
      .setAppId(COMETCHAT_CONSTANTS.APP_ID)
      .setRegion(COMETCHAT_CONSTANTS.REGION)
      .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(uiKitSettings)?.then(() => {
      setupLocalization();

      const UID = "YOUR_UID"; // Replace with your actual UID

      CometChatUIKit.getLoggedinUser().then((user) => {
        if (!user) {
          CometChatUIKit.login(UID)
            .then((loggedUser) => {
              console.log("Login Successful:", loggedUser);
              // Mount your app
              ReactDOM.createRoot(document.getElementById("root")).render(
                <CometChatProvider>
                  <App />
                </CometChatProvider>,
              );
            })
            .catch((error) => console.error("Login Failed:", error));
        } else {
          // User already logged in, mount app directly
          console.log("User already logged in:", user);
          ReactDOM.createRoot(document.getElementById("root")).render(
            <CometChatProvider>
              <App />
            </CometChatProvider>,
          );
        }
      });
    });
    ```
  </Tab>
</Tabs>

<Note>
  **Auth Key vs Auth Token**

  Auth Key is perfect for prototyping. For production apps, switch to Auth Token for secure authentication. See [Authentication and User Management](/docs/fundamentals/user-auth) for details.
</Note>

***

### **Step 5: Render the CometChatApp Component**

Render the chat UI by adding `CometChatApp` to your component:

```javascript lines theme={null}
import CometChatApp from "./CometChat/CometChatApp";

const App = () => {
  return (
    /* CometChatApp requires a parent with explicit height & width to render correctly.
     Adjust the height and width as needed.
     */
    <div style={{ width: "100vw", height: "100vh" }}>
      <CometChatApp />
    </div>
  );
};

export default App;
```

#### **Render with Default User and Group**

You can also render the component with default user and group selection:

<Tabs>
  <Tab title="TypeScript">
    ```tsx lines highlight={12} theme={null}
    import { useEffect, useState } from "react";
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import CometChatApp from "./CometChat/CometChatApp";
    const App = () => {
      const [selectedUser, setSelectedUser] = useState<CometChat.User | undefined>(
        undefined,
      );
      const [selectedGroup, setSelectedGroup] = useState<
        CometChat.Group | undefined
      >(undefined);
      useEffect(() => {
        const UID = "cometchat-uid-2"; // Replace with your User ID
        CometChat.getUser(UID).then(setSelectedUser).catch(console.error);
        // const GUID = "cometchat-guid-1"; // Replace with your Group ID
        // CometChat.getGroup(GUID).then(setSelectedGroup).catch(console.error);
      }, []);
      return (
        /* CometChatApp requires a parent with explicit height & width to render correctly.
          Adjust the height and width as needed.
         */
        <div style={{ width: "100vw", height: "100vh" }}>
          <CometChatApp user={selectedUser} group={selectedGroup} />
        </div>
      );
    };
    export default App;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx lines highlight={8} theme={null}
    import { useEffect, useState } from "react";
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import CometChatApp from "./CometChat/CometChatApp";
    const App = () => {
      const [selectedUser, setSelectedUser] = useState(undefined);
      const [selectedGroup, setSelectedGroup] = useState(undefined);
      useEffect(() => {
        const UID = "cometchat-uid-2"; // Replace with your User ID
        CometChat.getUser(UID).then(setSelectedUser).catch(console.error);
        // const GUID = "cometchat-guid-1"; // Replace with your Group ID
        // CometChat.getGroup(GUID).then(setSelectedGroup).catch(console.error);
      }, []);
      return (
        /* CometChatApp requires a parent with explicit height & width to render correctly.
          Adjust the height and width as needed.
         */
        <div style={{ width: "100vw", height: "100vh" }}>
          <CometChatApp user={selectedUser} group={selectedGroup} />
        </div>
      );
    };
    export default App;
    ```
  </Tab>
</Tabs>

#### Without Sidebar Mode

When the sidebar is hidden via the **Without Sidebar** option in UI Kit Builder, the component renders a single chat type based on the `chatType` prop:

| `chatType` | Behavior                                                            |
| ---------- | ------------------------------------------------------------------- |
| `"user"`   | Displays one-on-one conversations with the selected or default user |
| `"group"`  | Displays group conversations with the selected or default group     |

Pass the `user` or `group` prop to specify which conversation opens by default.

### **Step 6: Run the App**

Start your application with the appropriate command based on your setup:

<Tabs>
  <Tab title="Vite / Next.js">
    ```bash theme={null}
    npm run dev
    ```
  </Tab>

  <Tab title="Create React App (CRA)">
    ```bash theme={null}
    npm start
    ```
  </Tab>
</Tabs>

***

## **Troubleshooting**

If you face any issues while integrating the builder in your app project, please check if you have the following configurations added to your `tsConfig.json`:

```json theme={null}
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "resolveJsonModule": true
  }
}
```

If your development server is running, restart it to ensure the new TypeScript configuration is picked up.

***

## **Next Steps**

You can continue customizing by editing the exported code directly — or return to the UI Kit Builder to adjust your configuration and re-export a fresh code package.

### **Customize in Code**

Modify the exported components, props, and styling directly in your project.

<CardGroup>
  <Card title="Customizations" href="/chat-builder/react-router/builder-customisations">
    Adjust component props, behavior, and UI elements.
  </Card>

  <Card title="UI Kit Builder Settings" href="/chat-builder/react-router/builder-settings">
    Understand the settings file and feature toggles.
  </Card>

  <Card title="Directory Structure" href="/chat-builder/react-router/builder-dir-structure">
    See how the exported code is organized.
  </Card>

  <Card title="Advanced Theming" href="/ui-kit/react/theme">
    Customize colors, typography, and styling to match your brand.
  </Card>
</CardGroup>

### **Customize via UI Kit Builder**

Return to the Builder to update your configuration, then re-export and replace the code package. Any changes made in the UI Kit Builder will require you to re-export the code and follow the same integration steps above to integrate into your project.

<CardGroup>
  <Card title="Launch UI Kit Builder" icon="arrow-up-right-from-square" href="https://app.cometchat.com">
    Open the CometChat Dashboard to reconfigure and re-export.
  </Card>
</CardGroup>


# CometChat UI Kit Builder For React Router
Source: https://www.cometchat.com/docs/chat-builder/react-router/overview

CometChat UI Kit Builder for React Router is a low-code development tool to design and configure fully-featured chat experiences.

It provides a set of prebuilt, production-ready messaging components backed by CometChat's real-time infrastructure.

With CometChat UI Kit Builder, you can:

* **Configure chat and calling features**
* **Apply theming and layout options**
* **Export React Router-ready code**

The exported UI connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling.

## What You Can Configure

Toggle these features on or off directly in the UI Kit Builder. For a full reference of each setting, see [UI Kit Builder Settings](/docs/chat-builder/react-router/builder-settings).

### Chat Features

| Category                            | Includes                                                                                                                                               |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Core Messaging Experience**       | Typing indicators, threads, media sharing (photos, video, audio, files), edit & delete messages, read receipts, search, quoted replies, mark as unread |
| **Deeper User Engagement**          | Mentions, @all mentions, reactions, message translation, polls, collaborative whiteboard & document, voice notes, emojis, stickers, user & group info  |
| **AI User Copilot**                 | Conversation starters, conversation summaries, smart replies                                                                                           |
| **User Management**                 | Friends-only mode                                                                                                                                      |
| **Group Management**                | Create groups, add members, join/leave, delete groups, view members                                                                                    |
| **Moderation**                      | Content moderation, report messages, kick/ban users, promote/demote members                                                                            |
| **Private Messaging Within Groups** | Direct messages between group members                                                                                                                  |
| **In-App Sounds**                   | Incoming & outgoing message sounds                                                                                                                     |

### Call Features

| Category                  | Includes                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------ |
| **Voice & Video Calling** | 1:1 voice calling, 1:1 video calling, group voice conference, group video conference |

### Layout

| Category    | Includes                                |
| ----------- | --------------------------------------- |
| **Sidebar** | With Sidebar or Without Sidebar mode    |
| **Tabs**    | Conversations, Call Logs, Users, Groups |

### Theming

| Category       | Includes                                                    |
| -------------- | ----------------------------------------------------------- |
| **Theme**      | System, Light, or Dark mode                                 |
| **Colors**     | Brand color, primary & secondary text colors (light & dark) |
| **Typography** | Font family, text sizing (default, compact, comfortable)    |

***

## How to Use UI Kit Builder

### 1. Design

Configure your chat layout, toggle features, and pick a theme using the UI Kit Builder.

<Frame>
  <img />
</Frame>

### 2. Export

Click **Export Code** to generate a production-ready React Router codebase based on your configuration.

### 3. Integrate

Drop the exported code into your React Router project, add your CometChat credentials, and run the app. See the [Integration Guide](/docs/chat-builder/react-router/integration) for full steps.

***

## Try Live Demo

Experience the CometChat UI Kit Builder in action:

<CardGroup>
  <Card title="Launch Live Demo" icon="play" href="https://preview.cometchat.com/" />
</CardGroup>

or follow the video walkthrough below:

<Frame>
  <iframe title="YouTube video" />
</Frame>


# Customizing Your UI Kit Builder
Source: https://www.cometchat.com/docs/chat-builder/react/builder-customisations

Customize React UI Kit Builder components by adjusting CometChat app props, styling, group messages, and behavior.

The `CometChatSettings.ts` file handles basic feature toggles. For deeper customizations, modify component props or source code directly.

***

## **App-Level Customizations**

These ready-to-use props on the `CometChatApp` component let you quickly adjust common behaviors without modifying any internal components.

### **Group Action Messages**

Control the visibility of group action messages using the `showGroupActionMessages` prop:

```jsx theme={null}
<CometChatApp showGroupActionMessages={true} />
```

* `true` (default) — Group action messages are **visible**
* `false` — Group action messages are **hidden**

### **Auto Open First Item**

Control whether the first item in lists automatically opens on render using the `autoOpenFirstItem` prop:

```jsx theme={null}
<CometChatApp autoOpenFirstItem={false} />
```

* `true` (default) — The first item in conversation list, user list, or group list opens automatically on first render
* `false` — No item opens until the user clicks on one

***

## **Component-Level Customizations**

For more advanced customizations tailored to your app's needs, you can modify individual UI Kit components directly.

### **How to Customize**

1. Find the component in the [UI Kit Components Overview](/docs/ui-kit/react/components-overview)
2. Check available props and customization options
3. Update props or edit the component source code

Below are some examples to help you get started with common customizations like date formats, conversation subtitles, and send buttons.

### **Custom Date Format**

Customize how sticky date headers appear in the message list.

**Component**: [Message List](/docs/ui-kit/react/message-list) → [`stickyDateTimeFormat`](/docs/ui-kit/react/message-list#sticky-datetime-format)

```jsx lines theme={null}
import {
  CometChatMessageList,
  CalendarObject,
} from "@cometchat/chat-uikit-react";

const dateFormat = new CalendarObject({
  today: "hh:mm A", // "10:30 AM"
  yesterday: "[Yesterday]",
  otherDays: "DD/MM/YYYY", // "25/05/2025"
});

<CometChatMessageList user={chatUser} stickyDateTimeFormat={dateFormat} />;
```

<Frame>
  <img />
</Frame>

**Default format** (for reference):

```javascript lines theme={null}
new CalendarObject({
  today: "today",
  yesterday: "yesterday",
  otherDays: "DD MMM, YYYY", // "25 Jan, 2025"
});
```

***

### **Custom Conversation Subtitle**

Show online status or member count instead of the default last message preview.

**Component**: [Conversations](/docs/ui-kit/react/conversations) → [`subtitleView`](/docs/ui-kit/react/conversations#subtitleview)

```jsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatConversations } from "@cometchat/chat-uikit-react";

const customSubtitleView = (conversation) => {
  if (conversation.getConversationType() === "user") {
    const user = conversation.getConversationWith();
    return (
      <span>{user.getStatus() === "online" ? "🟢 Online" : "⚫ Offline"}</span>
    );
  } else {
    const group = conversation.getConversationWith();
    return <span>{group.getMembersCount()} members</span>;
  }
};

<CometChatConversations subtitleView={customSubtitleView} />;
```

***

### **Custom Send Button**

Replace the default send button with your brand's icon.

**Component**: [Message Composer](/docs/ui-kit/react/message-composer) → [`sendButtonView`](/docs/ui-kit/react/message-composer#sendbuttonview)

```jsx lines theme={null}
import {
  CometChatMessageComposer,
  CometChatButton,
} from "@cometchat/chat-uikit-react";

const brandedSendButton = (
  <CometChatButton
    iconURL="/icons/brand-send.svg"
    onClick={() => {
      // Your custom send logic
    }}
  />
);

<CometChatMessageComposer user={chatUser} sendButtonView={brandedSendButton} />;
```

```css lines theme={null}
/* Style the custom send button */
.cometchat-message-composer .cometchat-button {
	background: #6852d6;
	border-radius: 50%;
}

.cometchat-message-composer .cometchat-button__icon {
	background: #ffffff;
}
```

***

## **Next Steps**

<CardGroup>
  <Card title="UI Kit Builder Settings" href="/chat-builder/react/builder-settings">
    Configure feature toggles and behavior
  </Card>

  <Card title="Components Overview" href="/ui-kit/react/components-overview">
    Explore all available UI components
  </Card>

  <Card title="Theming" href="/ui-kit/react/theme">
    Customize colors, typography, and styling
  </Card>

  <Card title="Localization" href="/ui-kit/react/localize">
    Add multi-language support
  </Card>
</CardGroup>


# Directory Structure
Source: https://www.cometchat.com/docs/chat-builder/react/builder-dir-structure

Overview of the CometChat UI Kit Builder directory layout for React — understand where to find and customize components, settings, and styles.

The exported UI Kit Builder code lives in `src/CometChat/`. This guide helps you navigate the structure so you know exactly where to make changes.

<Tree>
  <Tree.Folder name="src">
    <Tree.Folder name="CometChat">
      <Tree.Folder name="assets">
        <Tree.File name="Icons, images, audio files" />
      </Tree.Folder>

      <Tree.Folder name="components">
        <Tree.File name="React components (UI elements)" />
      </Tree.Folder>

      <Tree.Folder name="context">
        <Tree.File name="React Context providers (state management)" />
      </Tree.Folder>

      <Tree.Folder name="locales">
        <Tree.File name="Translation files (en, fr, de, etc.)" />
      </Tree.Folder>

      <Tree.Folder name="styles">
        <Tree.File name="CSS files (mirrors components structure)" />
      </Tree.Folder>

      <Tree.Folder name="utils">
        <Tree.File name="Utility functions and helpers" />
      </Tree.Folder>

      <Tree.File name="CometChatApp.tsx" />

      <Tree.File name="CometChatSettings.ts" />

      <Tree.File name="customHooks.ts" />

      <Tree.File name="decl.d.ts" />

      <Tree.File name="styleConfig.ts" />
    </Tree.Folder>

    <Tree.File name="App.tsx" />

    <Tree.File name="index.tsx" />
  </Tree.Folder>
</Tree>

***

## Root Files

| File                   | Purpose                                                      |
| ---------------------- | ------------------------------------------------------------ |
| `CometChatApp.tsx`     | Main entry point — import this to render the chat experience |
| `CometChatSettings.ts` | Toggle features on/off (messaging, calls, AI copilot, etc.)  |
| `customHooks.ts`       | Custom React hooks used throughout the application           |
| `styleConfig.ts`       | Global styling configuration (colors, fonts, spacing)        |

***

## Key Folders

### `components/`

Each component folder contains the main `.tsx` file and associated hooks (`use*.ts`). These are the building blocks of your chat UI.

<Tree>
  <Tree.Folder name="components">
    <Tree.Folder name="CometChatAddMembers">
      <Tree.File name="Add members to groups" />
    </Tree.Folder>

    <Tree.Folder name="CometChatBannedMembers">
      <Tree.File name="Manage banned users" />
    </Tree.Folder>

    <Tree.Folder name="CometChatCallLog">
      <Tree.File name="Call history display" />
    </Tree.Folder>

    <Tree.Folder name="CometChatCreateGroup">
      <Tree.File name="Group creation flow" />
    </Tree.Folder>

    <Tree.Folder name="CometChatDetails">
      <Tree.File name="User/group details panel" />
    </Tree.Folder>

    <Tree.Folder name="CometChatHome">
      <Tree.File name="Main chat home screen" />
    </Tree.Folder>

    <Tree.Folder name="CometChatJoinGroup">
      <Tree.File name="Join group flow" />
    </Tree.Folder>

    <Tree.Folder name="CometChatLogin">
      <Tree.File name="Login screen" />
    </Tree.Folder>

    <Tree.Folder name="CometChatMessages">
      <Tree.File name="Message list and composer" />
    </Tree.Folder>

    <Tree.Folder name="CometChatSelector">
      <Tree.File name="Conversation/user selector" />
    </Tree.Folder>

    <Tree.Folder name="CometChatTransferOwnership">
      <Tree.File name="Transfer group ownership" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

### `context/`

State management for the chat application.

<Tree>
  <Tree.Folder name="context">
    <Tree.File name="AppContext.tsx" />

    <Tree.File name="CometChatContext.tsx" />

    <Tree.File name="appReducer.ts" />
  </Tree.Folder>
</Tree>

### `styles/`

CSS files organized to mirror the components structure. Each component has a corresponding style folder.

### `locales/`

Translation files for multi-language support. Add or modify JSON files here to customize text.

***

## Quick Reference: Where to Customize

| What you want to change | Where to look                 |
| ----------------------- | ----------------------------- |
| Enable/disable features | `CometChatSettings.ts`        |
| Theme colors & fonts    | `styleConfig.ts`              |
| Component-specific CSS  | `styles/<ComponentName>/`     |
| Text & translations     | `locales/<lang>/<lang>.json`  |
| Component behavior      | `components/<ComponentName>/` |

<Note>
  Prefer using settings and CSS overrides. For extensive changes, create wrapper
  components instead of modifying core files directly.
</Note>

***

## Next Steps

<CardGroup>
  <Card title="UI Kit Builder Settings" href="/chat-builder/react/builder-settings">
    Configure feature toggles and behavior
  </Card>

  <Card title="Customizations" href="/chat-builder/react/builder-customisations">
    Modify component props, styling, and behavior
  </Card>

  <Card title="Theming" href="/ui-kit/react/theme">
    Customize colors, typography, and styling
  </Card>

  <Card title="Localization" href="/ui-kit/react/localize">
    Add multi-language support
  </Card>
</CardGroup>


# UI Kit Builder Settings
Source: https://www.cometchat.com/docs/chat-builder/react/builder-settings

Configure React UI Kit Builder settings for messaging, AI helpers, calling, layout, theming, and agent tools.

The `CometChatSettings` object controls everything the React UI Kit Builder renders—messaging, AI helpers, calls, layout, theming, and agent tools.

<Info>
  **For developers customizing their chat UI**: Edit `CometChatSettings.ts` to
  enable/disable features like messaging, calls, AI copilot, and theming. See
  [Integration Guide](/docs/chat-builder/react/integration) for setup.
</Info>

## Top-level structure

```ts lines theme={null}
export interface CometChatSettings {
  chatFeatures: { ... }
  callFeatures: { ... }
  layout: { ... }
  style: { ... }
}
```

***

<Tip>
  All boolean settings follow the same pattern: `true` enables the feature and shows its UI elements, `false` hides them completely.
</Tip>

## 1. Chat Features (`chatFeatures`)

### 1.1 Core Messaging Experience (`coreMessagingExperience`)

Essential messaging features: typing indicators, media sharing, message actions, and presence.

| Setting                                                               | Type    | What It Does                                                                        |
| --------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| Typing indicator (`typingIndicator`)                                  | boolean | Shows "typing..." indicator when someone is composing a message                     |
| Thread conversation & replies (`threadConversationAndReplies`)        | boolean | Enables threaded replies to specific messages, creating nested conversation threads |
| Photos sharing (`photosSharing`)                                      | boolean | Allows users to share images from device or camera                                  |
| Video sharing (`videoSharing`)                                        | boolean | Allows users to share video files                                                   |
| Audio sharing (`audioSharing`)                                        | boolean | Allows users to share audio files (mp3, wav, etc.)                                  |
| File sharing (`fileSharing`)                                          | boolean | Allows users to share documents (PDF, DOC, etc.)                                    |
| Edit messages (`editMessage`)                                         | boolean | Lets users modify their sent messages; edited messages show "(edited)" label        |
| Delete messages (`deleteMessage`)                                     | boolean | Lets users remove their sent messages                                               |
| Message delivery and read receipts (`messageDeliveryAndReadReceipts`) | boolean | Shows delivery (✓) and read (✓✓) status indicators on messages                      |
| User & friends presence (`userAndFriendsPresence`)                    | boolean | Shows online/offline status dot next to user avatars                                |
| Conversation and Advanced Search (`conversationAndAdvancedSearch`)    | boolean | Enables search across messages, users, and conversations                            |
| Quoted Replies (`quotedReplies`)                                      | boolean | Lets users quote a message when replying, showing the original above their response |
| Mark as Unread (`markAsUnread`)                                       | boolean | Lets users mark a conversation as unread to revisit later                           |

<Tip>
  Empower users with a seamless chat experience—reply to specific messages with
  quoted replies, mark conversations as unread for later, and search across all
  chats instantly. Learn more about [Core
  Features](/docs/ui-kit/react/core-features).
</Tip>

### 1.2 Deeper User Engagement (`deeperUserEngagement`)

Interactive features: mentions, reactions, polls, voice notes, and collaborative tools.

| Setting                                              | Type    | What It Does                                                                                |
| ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| Mentions (`mentions`)                                | boolean | Lets users @mention specific people in a message to notify them                             |
| Mention All (`mentionAll`)                           | boolean | Lets users type @all to notify every member in a group chat                                 |
| Reactions (`reactions`)                              | boolean | Lets users add emoji reactions (👍 ❤️ 😂 etc.) to messages                                  |
| Message Translation (`messageTranslation`)           | boolean | Translates messages to user's preferred language. Requires Dashboard setup                  |
| Polls (`polls`)                                      | boolean | Lets users create polls with multiple options for group voting. Requires Dashboard setup    |
| Collaborative Whiteboard (`collaborativeWhiteboard`) | boolean | Opens a shared whiteboard for real-time drawing and collaboration. Requires Dashboard setup |
| Collaborative Document (`collaborativeDocument`)     | boolean | Creates shared documents for real-time collaborative editing. Requires Dashboard setup      |
| Voice Notes (`voiceNotes`)                           | boolean | Lets users record and send voice messages                                                   |
| Emojis (`emojis`)                                    | boolean | Shows emoji picker in composer for browsing and inserting emojis                            |
| Stickers (`stickers`)                                | boolean | Lets users send sticker images from available packs. Requires Dashboard setup               |
| User Info (`userInfo`)                               | boolean | Lets users tap on another user's avatar to view their profile                               |
| Group Info (`groupInfo`)                             | boolean | Lets users tap on group header to view group details and member list                        |
| Report Message (`reportMessage`)                     | boolean | Lets users flag inappropriate messages for review. Requires moderation setup                |

<Tip>
  Configure these features based on your app's requirements. Learn more about
  [Extensions](/docs/ui-kit/react/extensions).
</Tip>

### 1.3 AI User Copilot (`aiUserCopilot`)

AI-powered features to help users start and navigate conversations.

| Setting                                      | Type    | What It Does                                                                                  |
| -------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| Conversation Starter (`conversationStarter`) | boolean | Shows AI-suggested opening messages when starting a new chat. Requires OpenAI API key         |
| Conversation Summary (`conversationSummary`) | boolean | Generates an AI-powered summary of the conversation. Requires OpenAI API key                  |
| Smart Reply (`smartReply`)                   | boolean | Shows AI-suggested quick reply options based on conversation context. Requires OpenAI API key |

<Tip>
  AI User Copilot features require an OpenAI API key. Configure it in the [CometChat Dashboard](https://app.cometchat.com) under **Chat & Messaging > Settings**. Learn more about [AI Features](/docs/ui-kit/react/ai-features).
</Tip>

### 1.4 User Management (`userManagement`)

| Setting                      | Type    | What It Does                                                      |
| ---------------------------- | ------- | ----------------------------------------------------------------- |
| Friends Only (`friendsOnly`) | boolean | Restricts chat to friends list only; Users tab shows only friends |

### 1.5 Group Management (`groupManagement`)

Control what users can do with groups.

| Setting                                      | Type    | What It Does                                                      |
| -------------------------------------------- | ------- | ----------------------------------------------------------------- |
| Create Group (`createGroup`)                 | boolean | Lets users create new public or private groups                    |
| Add Members to Groups (`addMembersToGroups`) | boolean | Lets group admins/owners invite users to join the group           |
| Join/Leave Group (`joinLeaveGroup`)          | boolean | Lets users join public groups and leave groups they're in         |
| Delete Group (`deleteGroup`)                 | boolean | Lets group owners permanently delete a group and all its messages |
| View Group Members (`viewGroupMembers`)      | boolean | Shows member list in group info                                   |

### 1.6 Moderation (`moderatorControls`)

Admin tools for managing group members and content.

| Setting                                         | Type    | What It Does                                                                                                       |
| ----------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| Blocked message feedback (`moderation`)         | boolean | Enables blocked message feedback for blocked messages as per configured moderation rules. Requires Dashboard setup |
| Report Message (`reportMessage`)                | boolean | Lets users flag messages for moderator review in Dashboard                                                         |
| Kick Users (`kickUsers`)                        | boolean | Lets admins/moderators remove a user from a group (they can rejoin)                                                |
| Ban Users (`banUsers`)                          | boolean | Lets admins/moderators permanently remove a user and prevent rejoining                                             |
| Promote/Demote Members (`promoteDemoteMembers`) | boolean | Lets group owners change member roles (member, moderator, admin)                                                   |

<Tip>
  To enable content moderation, set `moderation` and `reportMessage` to `true`,
  then configure your moderation rules in the [CometChat
  Dashboard](https://app.cometchat.com). See [Rules
  Management](/docs/moderation/getting-started#setting-up-moderation-rules) for setup
  details.
</Tip>

### 1.7 Private Messaging Within Groups (`privateMessagingWithinGroups`)

Allow direct messages between group members.

| Setting                                                                    | Type    | What It Does                                                       |
| -------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| Send Private Message to Group Members (`sendPrivateMessageToGroupMembers`) | boolean | Lets users start a 1:1 chat with a group member from their profile |

### 1.8 In-App Sounds (`inAppSounds`)

Control sound notifications for incoming and outgoing messages.

| Setting                                         | Type    | What It Does                                 |
| ----------------------------------------------- | ------- | -------------------------------------------- |
| Incoming Message Sound (`incomingMessageSound`) | boolean | Plays a sound when a new message is received |
| Outgoing Message Sound (`outgoingMessageSound`) | boolean | Plays a sound when a message is sent         |

<Tip>
  These toggles control the default message sounds. To use custom audio files or manage sound playback programmatically, see the [Sound Manager](/docs/ui-kit/react/sound-manager).
</Tip>

***

## 2. Call Features (`callFeatures`)

### 2.1 Voice and Video Calling (`voiceAndVideoCalling`)

Enable voice and video calling capabilities.

| Setting                                         | Type    | What It Does                                                                |
| ----------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| 1:1 Voice Calling (`oneOnOneVoiceCalling`)      | boolean | Shows phone icon in 1:1 chat header for starting voice calls                |
| 1:1 Video Calling (`oneOnOneVideoCalling`)      | boolean | Shows video camera icon in 1:1 chat header for starting video calls         |
| Group Video Conference (`groupVideoConference`) | boolean | Shows video camera icon in group chat header for starting group video calls |
| Group Voice Conference (`groupVoiceConference`) | boolean | Shows phone icon in group chat header for starting group voice calls        |

<Tip>
  Learn more about [Call Features](/docs/ui-kit/react/call-features#features).
</Tip>

***

## 3. Layout (`layout`)

Control the overall UI structure and navigation.

| Setting                      | Type      | What It Does                                                                         |
| ---------------------------- | --------- | ------------------------------------------------------------------------------------ |
| With Sidebar (`withSideBar`) | boolean   | Shows navigation sidebar with tabs (Chats, Calls, Users, Groups) on the left side    |
| Tabs (`tabs`)                | string\[] | Array of tabs to show: `'chats'`, `'calls'`, `'users'`, `'groups'`                   |
| Chat Type (`chatType`)       | string    | Default conversation type on load: `'user'` for 1:1 chats, `'group'` for group chats |

<Tip>
  Set `withSideBar: false` for embedded chat widgets or single-conversation
  views where navigation isn't needed.
</Tip>

***

## 4. Style (`style`)

Customize colors, fonts, and theme appearance.

### 4.1 Theme

| Setting         | Type   | What It Does                                                                             |
| --------------- | ------ | ---------------------------------------------------------------------------------------- |
| Theme (`theme`) | string | Controls light/dark mode: `'light'`, `'dark'`, or `'system'` (matches device preference) |

<Tip>
  Use `theme: "system"` to automatically match the user's device preference.
  Preview your `brandColor` in both light and dark modes for contrast.

  [Learn more about UI Kit Theming](/docs/ui-kit/react/theme) for additional customizations.
</Tip>

### 4.2 Colors

| Setting                                     | Type   | What It Does                                                                             |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| Brand Color (`brandColor`)                  | string | Primary accent color (hex) for buttons, links, active states. Example: `"#6852D6"`       |
| Primary Text Light (`primaryTextLight`)     | string | Main text color in light mode (hex). Example: `"#2B2B2B"`                                |
| Primary Text Dark (`primaryTextDark`)       | string | Main text color in dark mode (hex). Example: `"#FFFFFF"`                                 |
| Secondary Text Light (`secondaryTextLight`) | string | Secondary text color in light mode (hex) for timestamps, subtitles. Example: `"#727272"` |
| Secondary Text Dark (`secondaryTextDark`)   | string | Secondary text color in dark mode (hex) for timestamps, subtitles. Example: `"#989898"`  |

<Tip>
  Match `brandColor` to your website's primary accent color. Use your site's
  existing text colors for `primaryTextLight` and `primaryTextDark` to maintain
  brand consistency.
</Tip>

### 4.3 Typography

| Setting       | Type   | What It Does                                                          |
| ------------- | ------ | --------------------------------------------------------------------- |
| Font (`font`) | string | Font family: `'roboto'`, `'arial'`, `'inter'`, or `'times new roman'` |
| Size (`size`) | string | Text size and spacing: `'default'`, `'compact'`, or `'comfortable'`   |

***

## Settings Overview

Below is the complete settings structure with default values. Update these in `CometChatSettings.ts` to customize your chat experience.

```json lines theme={null}
{
  "chatFeatures": {
    "coreMessagingExperience": {
      "typingIndicator": true,
      "threadConversationAndReplies": true,
      "photosSharing": true,
      "videoSharing": true,
      "audioSharing": true,
      "fileSharing": true,
      "editMessage": true,
      "deleteMessage": true,
      "messageDeliveryAndReadReceipts": true,
      "userAndFriendsPresence": true,
      "conversationAndAdvancedSearch": true,
      "moderation": true,
      "quotedReplies": false,
      "markAsUnread": false
    },
    "deeperUserEngagement": {
      "mentions": true,
      "mentionAll": true,
      "reactions": true,
      "messageTranslation": true,
      "polls": true,
      "collaborativeWhiteboard": true,
      "collaborativeDocument": true,
      "voiceNotes": true,
      "emojis": true,
      "stickers": true,
      "userInfo": true,
      "groupInfo": true
    },
    "aiUserCopilot": {
      "conversationStarter": false,
      "conversationSummary": false,
      "smartReply": false
    },
    "userManagement": {
      "friendsOnly": false
    },
    "groupManagement": {
      "createGroup": true,
      "addMembersToGroups": true,
      "joinLeaveGroup": true,
      "deleteGroup": true,
      "viewGroupMembers": true
    },
    "moderatorControls": {
      "kickUsers": true,
      "banUsers": true,
      "promoteDemoteMembers": true,
      "reportMessage": true
    },
    "privateMessagingWithinGroups": {
      "sendPrivateMessageToGroupMembers": true
    },
    "inAppSounds": {
      "incomingMessageSound": true,
      "outgoingMessageSound": true
    }
  },
  "callFeatures": {
    "voiceAndVideoCalling": {
      "oneOnOneVoiceCalling": true,
      "oneOnOneVideoCalling": true,
      "groupVideoConference": true,
      "groupVoiceConference": true
    }
  },
  "layout": {
    "withSideBar": true,
    "tabs": ["chats", "calls", "users", "groups"],
    "chatType": "user"
  },
  "style": {
    "theme": "system",
    "color": {
      "brandColor": "#6852D6",
      "primaryTextLight": "#141414",
      "primaryTextDark": "#FFFFFF",
      "secondaryTextLight": "#727272",
      "secondaryTextDark": "#989898"
    },
    "typography": {
      "font": "roboto",
      "size": "default"
    }
  }
}
```

***

## Next Steps

<CardGroup>
  <Card title="Directory Structure" href="/chat-builder/react/builder-dir-structure">
    Understand the organization of the builder components and generated code.
  </Card>

  <Card title="Customizations" href="/chat-builder/react/builder-customisations">
    Modify component props, styling, and behavior for deeper customization.
  </Card>
</CardGroup>


# UI Kit Builder Integration
Source: https://www.cometchat.com/docs/chat-builder/react/integration

Step-by-step guide to integrating CometChat UI Kit Builder into your React app with user login.

The **UI Kit Builder** simplifies integrating CometChat's UI Kit into your React application — quickly set up chat, customize UI elements, and add features without extensive coding.

<Frame>
  <img />
</Frame>

## **Complete Integration Workflow**

1. **Design Your Chat Experience** - Use the **UI Kit Builder** to customize layouts, features, and styling.
2. **Review and Export** - Review which features will be enabled in your Dashboard, toggle them on/off, and download the generated code package.
3. **Preview Customizations** - Optionally, preview the chat experience before integrating it into your project.
4. **Integration** - Integrate into your existing application.
5. **Customize Further** - Explore advanced customization options to tailor the chat experience.

<Frame>
  <iframe title="YouTube video" />
</Frame>

***

## **Launch the UI Kit Builder**

1. Log in to your [**CometChat Dashboard**](https://app.cometchat.com).
2. Select your application from the list.
3. Navigate to **Chat & Messaging** → **Get Started**.
4. Choose your platform and click **Launch UI Kit Builder**.

***

## **Review Your Export**

When you click **Export**, a "Review Your Export" modal appears (Step 1 of 3). This lets you:

* **Review features** — See which features will be enabled in your CometChat Dashboard based on your UI Kit configuration
* **Toggle features** — Turn individual features on/off before export
* **AI User Copilot** — Requires an OpenAI API key (you'll configure this in the next step)

<Frame>
  <img />
</Frame>

<Note>
  Only checked features will be enabled in your Dashboard. You can always modify
  these settings later in the [CometChat Dashboard](https://app.cometchat.com).
</Note>

***

## **Preview Customizations (Optional)**

Before integrating the **UI Kit Builder** into your project, you can preview the chat experience by following these steps. This step is completely optional and can be skipped if you want to directly integrate the **UI Kit Builder** into your project.

> You can preview the experience:
>
> 1. Open the `cometchat-app-react` folder.
> 2. Install dependencies:
>
> ```
> npm i
> ```
>
> 3. Run the app:
>
> ```powershell theme={null}
> npm start
> ```
>
> Your app credentials are already prepopulated in the exported code.

***

## **Integrate into Your Project**

Follow these steps to integrate CometChat UI Kit Builder into your existing React project:

### **Step 1: Install Dependencies**

Run the following command to install the required dependencies:

```ruby theme={null}
npm install @cometchat/chat-uikit-react@6.3.11 @cometchat/calls-sdk-javascript
```

### **Step 2: Copy CometChat Folder**

Copy the `cometchat-app-react/src/CometChat` folder into your project's `src` directory.

### **Step 3: Initialize CometChat UI Kit**

Initialize CometChat in your app's entry file. Select your setup:

<Tabs>
  <Tab title="Vite">
    ```tsx lines highlight={12-14} src/main.tsx theme={null}
    import { createRoot } from "react-dom/client";
    import "./index.css";
    import App from "./App.tsx";
    import {
      UIKitSettingsBuilder,
      CometChatUIKit,
    } from "@cometchat/chat-uikit-react";
    import { setupLocalization } from "./CometChat/utils/utils.ts";
    import { CometChatProvider } from "./CometChat/context/CometChatContext";

    export const COMETCHAT_CONSTANTS = {
      APP_ID: "YOUR_APP_ID", // Replace with your App ID
      REGION: "YOUR_REGION", // Replace with your App Region
      AUTH_KEY: "YOUR_AUTH_KEY", // Replace with your Auth Key or leave blank if you are authenticating using Auth Token
    };

    const uiKitSettings = new UIKitSettingsBuilder()
      .setAppId(COMETCHAT_CONSTANTS.APP_ID)
      .setRegion(COMETCHAT_CONSTANTS.REGION)
      .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(uiKitSettings)?.then(() => {
      setupLocalization();
      createRoot(document.getElementById("root")!).render(
        <CometChatProvider>
          <App />
        </CometChatProvider>,
      );
    });
    ```
  </Tab>

  <Tab title="CRA">
    ```tsx lines highlight={12-14} src/index.tsx theme={null}
    import { createRoot } from "react-dom/client";
    import "./index.css";
    import App from "./App.tsx";
    import {
      UIKitSettingsBuilder,
      CometChatUIKit,
    } from "@cometchat/chat-uikit-react";
    import { setupLocalization } from "./CometChat/utils/utils.ts";
    import { CometChatProvider } from "./CometChat/context/CometChatContext";

    export const COMETCHAT_CONSTANTS = {
      APP_ID: "YOUR_APP_ID", // Replace with your App ID
      REGION: "YOUR_REGION", // Replace with your App Region
      AUTH_KEY: "YOUR_AUTH_KEY", // Replace with your Auth Key or leave blank if you are authenticating using Auth Token
    };

    const uiKitSettings = new UIKitSettingsBuilder()
      .setAppId(COMETCHAT_CONSTANTS.APP_ID)
      .setRegion(COMETCHAT_CONSTANTS.REGION)
      .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(uiKitSettings)?.then(() => {
      setupLocalization();
      createRoot(document.getElementById("root")!).render(
        <CometChatProvider>
          <App />
        </CometChatProvider>,
      );
    });
    ```
  </Tab>
</Tabs>

<Info>
  Your app credentials (`APP_ID`, `AUTH_KEY`, `REGION`) are prepopulated in the exported code. If you need to use different credentials, you can find them in the Credentials block of your app's [Overview section](https://app.cometchat.com) on the CometChat Dashboard.
</Info>

### **Step 4: User Authentication**

CometChat uses a UID (User ID) to identify each user. After initialization, authenticate users to enable chat functionality.

You can either:

1. **Create new users** on the **[CometChat Dashboard](https://app.cometchat.com)**, **[CometChat SDK Method](/docs/ui-kit/react/methods#create-user)** or **[via the API](https://www.cometchat.com/docs/rest-api/users/create)**.

2. **Use pre-generated test users**: `cometchat-uid-1` through `cometchat-uid-5`

The **Login** method returns a **User object** containing all relevant details of the logged-in user.

**Login After Initialization**

Log in the user after initialization — useful when login happens later in your app flow (e.g., after a login form).

<Tabs>
  <Tab title="TypeScript">
    ```ts lines highlight={3} theme={null}
    import { CometChatUIKit } from "@cometchat/chat-uikit-react";

    const UID = "YOUR_UID"; // Replace with your actual UID

    CometChatUIKit.getLoggedinUser().then((user: CometChat.User | null) => {
      if (!user) {
        // If no user is logged in, proceed with login
        CometChatUIKit.login(UID)
          .then((user: CometChat.User) => {
            console.log("Login Successful:", { user });
            // Mount your app
          })
          .catch(console.log);
      } else {
        // If user is already logged in, mount your app
      }
    });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js lines highlight={3} theme={null}
    import { CometChatUIKit } from "@cometchat/chat-uikit-react";

    const UID = "YOUR_UID"; // Replace with your actual UID

    CometChatUIKit.getLoggedinUser().then((user) => {
      if (!user) {
        // If no user is logged in, proceed with login
        CometChatUIKit.login(UID)
          .then((user) => {
            console.log("Login Successful:", { user });
            // Mount your app
          })
          .catch(console.log);
      } else {
        // If user is already logged in, mount your app
      }
    });
    ```
  </Tab>
</Tabs>

**Login During Initialization**

Alternatively, log in the user immediately inside `CometChatUIKit.init()` — ideal for apps that authenticate on startup.

<Tabs>
  <Tab title="TypeScript">
    ```ts lines highlight={12-14} theme={null}
    import React from "react";
    import ReactDOM from "react-dom/client";
    import App from "./App";
    import {
      UIKitSettingsBuilder,
      CometChatUIKit,
    } from "@cometchat/chat-uikit-react";
    import { setupLocalization } from "./CometChat/utils/utils";
    import { CometChatProvider } from "./CometChat/context/CometChatContext";

    export const COMETCHAT_CONSTANTS = {
      APP_ID: "YOUR_APP_ID", // Replace with your App ID
      REGION: "YOUR_REGION", // Replace with your App Region
      AUTH_KEY: "YOUR_AUTH_KEY", // Replace with your Auth Key or leave blank if you are authenticating using Auth Token
    };

    const uiKitSettings = new UIKitSettingsBuilder()
      .setAppId(COMETCHAT_CONSTANTS.APP_ID)
      .setRegion(COMETCHAT_CONSTANTS.REGION)
      .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(uiKitSettings)?.then(() => {
      setupLocalization();

      const UID = "YOUR_UID"; // Replace with your actual UID

      CometChatUIKit.getLoggedinUser().then((user: CometChat.User | null) => {
        if (!user) {
          CometChatUIKit.login(UID)
            .then((loggedUser: CometChat.User) => {
              console.log("Login Successful:", loggedUser);
              // Mount your app
              ReactDOM.createRoot(
                document.getElementById("root") as HTMLElement,
              ).render(
                <CometChatProvider>
                  <App />
                </CometChatProvider>,
              );
            })
            .catch((error) => console.error("Login Failed:", error));
        } else {
          // User already logged in, mount app directly
          console.log("User already logged in:", user);
          ReactDOM.createRoot(
            document.getElementById("root") as HTMLElement,
          ).render(
            <CometChatProvider>
              <App />
            </CometChatProvider>,
          );
        }
      });
    });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js lines highlight={12-14} theme={null}
    import React from "react";
    import ReactDOM from "react-dom/client";
    import App from "./App";
    import {
      UIKitSettingsBuilder,
      CometChatUIKit,
    } from "@cometchat/chat-uikit-react";
    import { setupLocalization } from "./CometChat/utils/utils";
    import { CometChatProvider } from "./CometChat/context/CometChatContext";

    export const COMETCHAT_CONSTANTS = {
      APP_ID: "YOUR_APP_ID", // Replace with your App ID
      REGION: "YOUR_REGION", // Replace with your App Region
      AUTH_KEY: "YOUR_AUTH_KEY", // Replace with your Auth Key or leave blank if you are authenticating using Auth Token
    };

    const uiKitSettings = new UIKitSettingsBuilder()
      .setAppId(COMETCHAT_CONSTANTS.APP_ID)
      .setRegion(COMETCHAT_CONSTANTS.REGION)
      .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(uiKitSettings)?.then(() => {
      setupLocalization();

      const UID = "YOUR_UID"; // Replace with your actual UID

      CometChatUIKit.getLoggedinUser().then((user) => {
        if (!user) {
          CometChatUIKit.login(UID)
            .then((loggedUser) => {
              console.log("Login Successful:", loggedUser);
              // Mount your app
              ReactDOM.createRoot(document.getElementById("root")).render(
                <CometChatProvider>
                  <App />
                </CometChatProvider>,
              );
            })
            .catch((error) => console.error("Login Failed:", error));
        } else {
          // User already logged in, mount app directly
          console.log("User already logged in:", user);
          ReactDOM.createRoot(document.getElementById("root")).render(
            <CometChatProvider>
              <App />
            </CometChatProvider>,
          );
        }
      });
    });
    ```
  </Tab>
</Tabs>

<Note>
  **Auth Key vs Auth Token**

  Auth Key is perfect for prototyping. For production apps, switch to Auth Token for secure authentication. See [Authentication and User Management](/docs/fundamentals/user-auth) for details.
</Note>

***

### **Step 5: Render the CometChatApp Component**

Render the chat UI by adding `CometChatApp` to your component:

```javascript lines theme={null}
import CometChatApp from "./CometChat/CometChatApp";

const App = () => {
  return (
    /* CometChatApp requires a parent with explicit height & width to render correctly.
     Adjust the height and width as needed.
     */
    <div style={{ width: "100vw", height: "100vh" }}>
      <CometChatApp />
    </div>
  );
};

export default App;
```

#### **Render with Default User and Group**

You can also render the component with default user and group selection:

<Tabs>
  <Tab title="TypeScript">
    ```tsx lines highlight={12} theme={null}
    import { useEffect, useState } from "react";
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import CometChatApp from "./CometChat/CometChatApp";
    const App = () => {
      const [selectedUser, setSelectedUser] = useState<CometChat.User | undefined>(
        undefined,
      );
      const [selectedGroup, setSelectedGroup] = useState<
        CometChat.Group | undefined
      >(undefined);
      useEffect(() => {
        const UID = "cometchat-uid-2"; // Replace with your User ID
        CometChat.getUser(UID).then(setSelectedUser).catch(console.error);
        // const GUID = "cometchat-guid-1"; // Replace with your Group ID
        // CometChat.getGroup(GUID).then(setSelectedGroup).catch(console.error);
      }, []);
      return (
        /* CometChatApp requires a parent with explicit height & width to render correctly.
          Adjust the height and width as needed.
         */
        <div style={{ width: "100vw", height: "100vh" }}>
          <CometChatApp user={selectedUser} group={selectedGroup} />
        </div>
      );
    };
    export default App;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx lines highlight={8} theme={null}
    import { useEffect, useState } from "react";
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import CometChatApp from "./CometChat/CometChatApp";
    const App = () => {
      const [selectedUser, setSelectedUser] = useState(undefined);
      const [selectedGroup, setSelectedGroup] = useState(undefined);
      useEffect(() => {
        const UID = "cometchat-uid-2"; // Replace with your User ID
        CometChat.getUser(UID).then(setSelectedUser).catch(console.error);
        // const GUID = "cometchat-guid-1"; // Replace with your Group ID
        // CometChat.getGroup(GUID).then(setSelectedGroup).catch(console.error);
      }, []);
      return (
        /* CometChatApp requires a parent with explicit height & width to render correctly.
          Adjust the height and width as needed.
         */
        <div style={{ width: "100vw", height: "100vh" }}>
          <CometChatApp user={selectedUser} group={selectedGroup} />
        </div>
      );
    };
    export default App;
    ```
  </Tab>
</Tabs>

#### Without Sidebar Mode

When the sidebar is hidden via the **Without Sidebar** option in UI Kit Builder, the component renders a single chat type based on the `chatType` prop:

| `chatType` | Behavior                                                            |
| ---------- | ------------------------------------------------------------------- |
| `"user"`   | Displays one-on-one conversations with the selected or default user |
| `"group"`  | Displays group conversations with the selected or default group     |

Pass the `user` or `group` prop to specify which conversation opens by default.

### **Step 6: Run the App**

Start your application with the appropriate command based on your setup:

<Tabs>
  <Tab title="Vite / Next.js">
    ```bash theme={null}
    npm run dev
    ```
  </Tab>

  <Tab title="Create React App (CRA)">
    ```bash theme={null}
    npm start
    ```
  </Tab>
</Tabs>

***

## **Troubleshooting**

If you face any issues while integrating the builder in your app project, please check if you have the following configurations added to your `tsConfig.json`:

```json theme={null}
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "resolveJsonModule": true
  }
}
```

If your development server is running, restart it to ensure the new TypeScript configuration is picked up.

***

## **Next Steps**

You can continue customizing by editing the exported code directly — or return to the UI Kit Builder to adjust your configuration and re-export a fresh code package.

### **Customize in Code**

Modify the exported components, props, and styling directly in your project.

<CardGroup>
  <Card title="Customizations" href="/chat-builder/react/builder-customisations">
    Adjust component props, behavior, and UI elements.
  </Card>

  <Card title="UI Kit Builder Settings" href="/chat-builder/react/builder-settings">
    Understand the settings file and feature toggles.
  </Card>

  <Card title="Directory Structure" href="/chat-builder/react/builder-dir-structure">
    See how the exported code is organized.
  </Card>

  <Card title="Advanced Theming" href="/ui-kit/react/theme">
    Customize colors, typography, and styling to match your brand.
  </Card>
</CardGroup>

### **Customize via UI Kit Builder**

Return to the Builder to update your configuration, then re-export and replace the code package. Any changes made in the UI Kit Builder will require you to re-export the code and follow the same integration steps above to integrate into your project.

<CardGroup>
  <Card title="Launch UI Kit Builder" icon="arrow-up-right-from-square" href="https://app.cometchat.com">
    Open the CometChat Dashboard to reconfigure and re-export.
  </Card>
</CardGroup>

***


# CometChat UI Kit Builder For React
Source: https://www.cometchat.com/docs/chat-builder/react/overview

CometChat UI Kit Builder for React is a low-code development tool to design and configure fully-featured chat experiences.

It provides a set of prebuilt, production-ready messaging components backed by CometChat's real-time infrastructure.

With CometChat UI Kit Builder, you can:

* **Configure chat and calling features**
* **Apply theming and layout options**
* **Export React-ready code**

The exported UI connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling.

## What You Can Configure

Toggle these features on or off directly in the UI Kit Builder. For a full reference of each setting, see [UI Kit Builder Settings](/docs/chat-builder/react/builder-settings).

### Chat Features

| Category                            | Includes                                                                                                                                               |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Core Messaging Experience**       | Typing indicators, threads, media sharing (photos, video, audio, files), edit & delete messages, read receipts, search, quoted replies, mark as unread |
| **Deeper User Engagement**          | Mentions, @all mentions, reactions, message translation, polls, collaborative whiteboard & document, voice notes, emojis, stickers, user & group info  |
| **AI User Copilot**                 | Conversation starters, conversation summaries, smart replies                                                                                           |
| **User Management**                 | Friends-only mode                                                                                                                                      |
| **Group Management**                | Create groups, add members, join/leave, delete groups, view members                                                                                    |
| **Moderation**                      | Content moderation, report messages, kick/ban users, promote/demote members                                                                            |
| **Private Messaging Within Groups** | Direct messages between group members                                                                                                                  |
| **In-App Sounds**                   | Incoming & outgoing message sounds                                                                                                                     |

### Call Features

| Category                  | Includes                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------ |
| **Voice & Video Calling** | 1:1 voice calling, 1:1 video calling, group voice conference, group video conference |

### Layout

| Category    | Includes                                |
| ----------- | --------------------------------------- |
| **Sidebar** | With Sidebar or Without Sidebar mode    |
| **Tabs**    | Conversations, Call Logs, Users, Groups |

### Theming

| Category       | Includes                                                    |
| -------------- | ----------------------------------------------------------- |
| **Theme**      | System, Light, or Dark mode                                 |
| **Colors**     | Brand color, primary & secondary text colors (light & dark) |
| **Typography** | Font family, text sizing (default, compact, comfortable)    |

***

## How to Use UI Kit Builder

### 1. Design

Configure your chat layout, toggle features, and pick a theme using the UI Kit Builder.

<Frame>
  <img />
</Frame>

### 2. Export

Click **Export Code** to generate a production-ready React codebase based on your configuration.

### 3. Integrate

Drop the exported code into your React project, add your CometChat credentials, and run the app. See the [Integration Guide](/docs/chat-builder/react/integration) for full steps.

***

## Try Live Demo

Experience the CometChat UI Kit Builder in action:

<CardGroup>
  <Card title="Launch Live Demo" icon="play" href="https://preview.cometchat.com/" />
</CardGroup>

or follow the video walkthrough below:

<Frame>
  <iframe title="YouTube video" />
</Frame>


# Chat & Messaging
Source: https://www.cometchat.com/docs/chat-call

Add real-time chat, voice & video calling to your apps in minutes. Choose your path: UI Kits, SDKs, or Widgets.

<div>
  <div />

  <div>
    <Columns>
      <div>
        <h1>Chat & Messaging</h1>

        <p>
          Production-ready messaging for web and mobile, ready to drop into your stack.
        </p>

        <p><strong>Building with an AI agent?</strong> Install this skill and start building instantly.</p>

        <div>
          ```bash theme={null}
          npx @cometchat/skills add
          ```
        </div>
      </div>

      <div>
        <img alt="Chat & Messaging UI Preview" />
      </div>
    </Columns>
  </div>
</div>

<div>
  <h3>
    <span>Step 1</span>
  </h3>

  <div>
    <h2>Add CometChat to Your Frontend</h2>
    <p>Use our pre-built UI kits or SDKs to add chat to your website or mobile app instantly.</p>
  </div>

  <div>
    <div>
      <h3>
        UI Kit Builder
      </h3>

      <span>  </span>
      <span>RECOMMENDED</span>
    </div>

    <p>
      Get a fully functional chat interface in minutes. Configure via our ui kit builder — no complex setup required.
    </p>

    <AccordionGroup>
      <Accordion title="How It Works">
        <Steps>
          <Step title="Configure visually">
            Toggle mentions, reactions, media sharing, and more through our visual interface.
          </Step>

          <Step title="Export React code">
            Get production-ready React code that plugs directly into your existing app.
          </Step>

          <Step title="Customize anytime">
            It's based on our UI Kits—edit layouts, styles, or workflows as needed.
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="Why It's Great">
        <Steps>
          <Step title="Fastest setup">No manual component wiring required.</Step>
          <Step title="Extra features">User/group info, moderation, and more included by default.</Step>
          <Step title="No compromise on customization">Same powerful UI Kits under the hood.</Step>
        </Steps>
      </Accordion>
    </AccordionGroup>

    <CardGroup>
      <Card title="React" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/react.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=360d1421dea2eb2e44dfb12c496dda8a" alt="React" />} href="/chat-builder/react/overview" />

      <Card title="Next.js" icon={<img src="https://mintcdn.com/cometchat-22654f5b/mbY_CYvdVJAywUE8/images/icons/nextjs.svg?fit=max&auto=format&n=mbY_CYvdVJAywUE8&q=85&s=868b34a7d669610304235ba92f18ada7" alt="Next.js" />} href="/chat-builder/nextjs/overview" />

      <Card title="React Router" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/react-router.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=95ac6ea84dee657a8e7353085ceb3770" alt="React Router" />} href="/chat-builder/react-router/overview" />

      <Card title="iOS Swift" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/swift.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=17596c5f282d15f0e5b602d35aa89411" alt="iOS Swift" />} href="/chat-builder/ios/overview" />

      <Card title="Android Java" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/android.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=3f4bd348d54becef6552a9f4103eb110" alt="Android Java" />} href="/chat-builder/android/overview" />

      <Card title="React Native" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/react.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=360d1421dea2eb2e44dfb12c496dda8a" alt="React Native" />} href="/ui-kit/react-native/overview" />

      <Card title="Flutter" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/flutter.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=9bb597bdc52edda692bc0b0db73e4395" alt="Flutter" />} href="/chat-builder/flutter/overview" />
    </CardGroup>
  </div>

  <div>
    <h3>
      UI Kits - Components
    </h3>

    <p>
      Build your own chat interface using individual components. Each component includes built-in chat logic.
    </p>

    <AccordionGroup>
      <Accordion title="How It Works">
        <Steps>
          <Step title="Select components">
            Choose only what you need from the comprehensive UI Kit.
          </Step>

          <Step title="Arrange & theme">
            Compose your desired layout; apply custom styling or theming.
          </Step>

          <Step title="Ship without plumbing">
            Each component includes its own chat logic—no SDK wiring per part.
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="Why It's Great">
        <Steps>
          <Step title="Fastest setup">No manual component wiring required.</Step>
          <Step title="Extra features">User/group info, moderation, and more included by default.</Step>
          <Step title="No compromise on customization">Same powerful UI Kits under the hood.</Step>
        </Steps>
      </Accordion>
    </AccordionGroup>

    <CardGroup>
      <Card title="React" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/react.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=360d1421dea2eb2e44dfb12c496dda8a" alt="React" />} href="/ui-kit/react/react-js-integration" />

      <Card title="Next.js" icon={<img src="https://mintcdn.com/cometchat-22654f5b/mbY_CYvdVJAywUE8/images/icons/nextjs.svg?fit=max&auto=format&n=mbY_CYvdVJAywUE8&q=85&s=868b34a7d669610304235ba92f18ada7" alt="Next.js" />} href="/ui-kit/react/next-js-integration" />

      <Card title="React Router" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/react-router.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=95ac6ea84dee657a8e7353085ceb3770" alt="React Router" />} href="/ui-kit/react/react-router-integration" />

      <Card title="Astro" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/astro.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=255358eccb0e3a4f498f99067a5eeb1a" alt="Astro" />} href="/ui-kit/react/astro-integration" />

      <Card title="Angular" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/angular.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=28a581cfaf1315f867014bb28eeebb8f" alt="Angular" />} href="/ui-kit/angular/overview" />

      <Card title="Vue" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/vuejs.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=6b3bfa79526c9d51dd561572f30764a4" alt="Vue" />} href="/ui-kit/vue/overview" />

      <Card title="iOS Swift" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/swift.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=17596c5f282d15f0e5b602d35aa89411" alt="iOS Swift" />} href="/ui-kit/ios/overview" />

      <Card title="Android Kotlin" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/kotlin.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=3d29877d493068d640ed542f3aaf044d" alt="Android Kotlin" />} href="/ui-kit/android/overview" />

      <Card title="Android Java" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/android.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=3f4bd348d54becef6552a9f4103eb110" alt="Android Java" />} href="/ui-kit/android/overview" />

      <Card title="React Native" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/react.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=360d1421dea2eb2e44dfb12c496dda8a" alt="React Native" />} href="/ui-kit/react-native/overview" />

      <Card title="Flutter" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/flutter.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=9bb597bdc52edda692bc0b0db73e4395" alt="Flutter" />} href="/ui-kit/flutter/overview" />
    </CardGroup>
  </div>

  <div>
    <h3>
      SDKs
    </h3>

    <p>
      Build your own UI from scratch with our complete SDK feature set.
    </p>

    <AccordionGroup>
      <Accordion title="How It Works">
        <Steps>
          <Step title="Integrate the SDK">
            Initialize and connect to CometChat in your frontend application.
          </Step>

          <Step title="Build every screen">
            Create UI and flows from the ground up—exactly how you want them.
          </Step>

          <Step title="Customize everything">
            Full control over every aspect of the chat experience.
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="Why It's Great">
        <Steps>
          <Step title="Fastest time‑to‑value">Live in minutes, not days.</Step>
          <Step title="Works anywhere">No framework lock‑in or build steps.</Step>
          <Step title="Easy to customize">Configure without code; theme when needed.</Step>
        </Steps>
      </Accordion>
    </AccordionGroup>

    <CardGroup>
      <Card title="JavaScript" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/js.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=c298fae713e52492e9d2a1f1259fee91" alt="JavaScript" />} href="/sdk/javascript/overview" />

      <Card title="React Native" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/react.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=360d1421dea2eb2e44dfb12c496dda8a" alt="React Native" />} href="/sdk/react-native/overview" />

      <Card title="iOS" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/swift.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=17596c5f282d15f0e5b602d35aa89411" alt="iOS" />} href="/sdk/ios/overview" />

      <Card title="Android" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/android.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=3f4bd348d54becef6552a9f4103eb110" alt="Android" />} href="/sdk/android/overview" />

      <Card title="Flutter" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/flutter.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=9bb597bdc52edda692bc0b0db73e4395" alt="Flutter" />} href="/sdk/flutter/overview" />

      <Card title="Ionic" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/ionic.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=84edc5bea90c10aee543f16befaa5206" alt="Ionic" />} href="/sdk/ionic-legacy/overview" />

      <Card title="Unreal Engine" icon={<img src="https://mintcdn.com/cometchat-22654f5b/p6zcVY7c9yo1u2SD/images/icons/unreal.svg?fit=max&auto=format&n=p6zcVY7c9yo1u2SD&q=85&s=d1772fb74745efc1f2abe631904ecfb7" alt="Unreal Engine" />} href="/sdk/unreal/overview" />
    </CardGroup>
  </div>

  <div>
    <h3>
      Chat Widgets
    </h3>

    <p>
      Add chat to any website with a simple script tag. Perfect for customer support and community chat.
    </p>

    <AccordionGroup>
      <Accordion title="How It Works">
        <Steps>
          <Step title="Add a script tag">
            Paste a single script into your site or CMS.
          </Step>

          <Step title="Configure in dashboard">
            Toggle features, colors, and behavior from CometChat.
          </Step>

          <Step title="Launch">
            The widget appears instantly across your pages.
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="Why It's Great">
        <Steps>
          <Step title="Fastest time‑to‑value">Live in minutes, not days.</Step>
          <Step title="Works anywhere">No framework lock‑in or build steps.</Step>
          <Step title="Easy to customize">Configure without code; theme when needed.</Step>
        </Steps>
      </Accordion>
    </AccordionGroup>

    <CardGroup>
      <Card title="HTML / Bootstrap / jQuery" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/html5.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=618e8722dfdbe43bdbcd49c28aea89a1" alt="HTML / Bootstrap / jQuery" />} href="/widget/html/integration" />

      <Card title="WordPress" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/wordpress.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=b8627526d8f9b07e6438831e5b687c3e" alt="WordPress" />} href="/widget/wordpress/integration" />

      <Card title="Shopify" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/shopify.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=ecc307682aeac00c7eded813026771d8" alt="Shopify" />} href="/widget/shopify/integration" />

      <Card title="Squarespace" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/squarespace.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=ab68d081fcc789979e91559d22c0b6c8" alt="Squarespace" />} href="/widget/squarespace/integration" />

      <Card title="Wix" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/wix.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=c09108b12ce4d44f779a38f2d3e43c33" alt="Wix" />} href="/widget/wix/integration" />

      <Card title="Webflow" icon={<img src="https://mintcdn.com/cometchat-22654f5b/8jUDJ4u0JryEVoUC/images/icons/webflow.svg?fit=max&auto=format&n=8jUDJ4u0JryEVoUC&q=85&s=032ff7a6cfb3e40d4c9bcdd7d8d01cac" alt="Webflow" />} href="/widget/webflow/integration" />
    </CardGroup>
  </div>

  <h3>
    <span>Step 2</span>
  </h3>

  <div>
    <h2>
      Sync Your Users
    </h2>

    <p>
      Sync your user database with CometChat for a seamless experience.
    </p>

    <Columns>
      <Card title="CometChat Dashboard" href="https://app.cometchat.com/">
        <ul>
          * Add users directly from the CometChat Dashboard.
          * Ideal for quick testing or small teams.
        </ul>
      </Card>

      <Card title="SDK (In-App Provisioning)" href="/sdk/javascript/user-management">
        <ul>
          * Create users via the SDK methods.
          * Perfect for auto-provisioning during sign-up or login.
        </ul>
      </Card>

      <Card title="REST API (Backend)" href="/rest-api/users/create">
        <ul>
          * Create users using the REST API.
          * Best for batch imports or admin workflows.
        </ul>
      </Card>
    </Columns>
  </div>

  <div>
    <h2>
      Sample Apps & Demos
    </h2>

    <p>
      See CometChat in action. Clone these sample apps to get started quickly.
    </p>

    <CardGroup>
      <Card title="React Chat App" href="https://github.com/cometchat/cometchat-uikit-react/tree/v6/sample-app" />

      <Card title="React Native Chat App" href="https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples" />

      <Card title="iOS Chat App (Swift)" href="https://github.com/cometchat/cometchat-sample-app-ios" />

      <Card title="Android Chat App (Java)" href="https://github.com/cometchat/cometchat-sample-app-android-java" />

      <Card title="Android Chat App (Kotlin)" href="https://github.com/cometchat/cometchat-uikit-android/tree/v5/sample-app-kotlin" />

      <Card title="Flutter Chat App" href="https://github.com/cometchat/cometchat-uikit-flutter/tree/v5/sample_app" />

      <Card title="Angular Chat App" href="https://github.com/cometchat/cometchat-sample-app-angular" />

      <Card title="Vue Chat App" href="https://github.com/cometchat/cometchat-sample-app-vue" />
    </CardGroup>
  </div>
</div>

<div>
  <div>
    <div>
      2026 © CometChat
    </div>

    <div>
      <a href="https://www.linkedin.com/company/cometchat">
        <svg>
          <path />
        </svg>

        <span>LinkedIn</span>
      </a>

      <a href="https://x.com/cometchat">
        <svg>
          <path />
        </svg>

        <span>Twitter</span>
      </a>

      <a href="https://github.com/cometchat">
        <svg>
          <path />
        </svg>

        <span>GitHub</span>
      </a>
    </div>
  </div>
</div>


# Conversation Starter
Source: https://www.cometchat.com/docs/fundamentals/ai-user-copilot/conversation-starter

Generate CometChat AI conversation starters from recent messages to help users begin new chat conversations.

**Conversation Starter** enables you to retrieve an initial message in a new conversation, often used to set the context for the conversation that is about to begin. This can be particularly useful for guiding users on how to interact within the chat or for delivering automated messages that engage users when they initiate a chat.

## Before you begin

1. Set up the AI settings through the CometChat dashboard as detailed in the [Overview section](/docs/fundamentals/ai-user-copilot/overview).
2. Navigate to Chat > Features, under **AI User Copilot**, enable **Conversation Starter**.

   <Frame>
     <img />
   </Frame>
3. Implement the chat functionality in your applications using [CometChat's **v4** Chat SDKs](/docs/sdk/javascript/overview).

## How does it work?

CometChat AI analyzes the user's tone and writing style by reviewing recent messages sent by that user within the application.

The SDK includes a method for retrieving conversation starters in a chat. This method returns an array containing three potential starters for the conversation.

The number of messages to be fetched to generate relevant conversation starter is configurable. By default the CometChat AI takes the latest `1000` messages. This can be configured to specific timestamps as well.

| Configuration | Value                                                  |
| ------------- | ------------------------------------------------------ |
| lastNMessages | This will fetch specific number of messages.           |
| fromTimestamp | This will fetch messages from a particular timestamp.  |
| toTimestamp   | This will fetch messages until a particular timestamp. |

<Note>
  While using any configuration mentioned above a maximum of **only** `1000` messages will be fetched.
</Note>

## Implementation

### SDKs

To implement Conversation Starter in the platform of your choice, you may utilize the following code samples:

<Tabs>
  <Tab title="JS/React Native/Ionic SDK">
    ```js theme={null}
    const receiverId = 'UID/GUID';
    const receiverType = 'user/group';
    const configuration = {lastNMessages: 100};

    CometChat.getConversationStarter(receiverId, receiverType, configuration).then(
    	(conversation-starter) => {
      	console.log("Conversation Starter", conversation-starter);
      },
      (error) => {
      	console.log("An error occurred while fetching conversation starter", error);
      }
    );
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String receiveId = "";
    String receiverType = CometChatConstants.RECEIVER_TYPE_USER;

    JSONObject configuration = new JSONObject();
    try {
        configuration.put("lastNMessages", 100);
    } catch (JSONException e) {
        throw new RuntimeException(e);
    }

    CometChat.getConversationStarter(receiveId, receiverType, configuration, new CometChat.CallbackListener<List<String>>() {
        @Override
        public void onSuccess(List<String> strings) {
            Log.e(TAG, strings.toString());
        }
        @Override
        public void onError(CometChatException e) {
            Log.e(TAG, e.getMessage());
        }
    });
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val receiveId = ""
    val receiverType: String = CometChatConstants.RECEIVER_TYPE_USER
    val configuration = JSONObject()
    try {
        configuration.put("lastNMessages", 100)
    } catch (e: JSONException) {
        throw RuntimeException(e)
    }

    CometChat.getConversationStarter(
        receiveId,
        receiverType,
        configuration,
        object : CallbackListener<List<String?>?>() {
            fun onSuccess(strings: List<String?>) {
                Log.e(SplashActivity.TAG, strings.toString())
            }

            override fun onError(e: CometChatException) {
                Log.e(SplashActivity.TAG, e.getMessage())
            }
        }
    )
    ```
  </Tab>

  <Tab title="Dart">
    ```dart theme={null}
    String receiveId = "";
    String receiverType = CometChatConversationType.user;
    Map configuration = { "lastNMessages": 100 };

    CometChat.getConversationStarter("cometchat-uid-2", "user", configuration: configuration, onSuccess: (List<String> starters) {
        debugPrint("getConversationStarter Sucess: $starters");
    }, onError: (CometChatException e) {
        debugPrint("getConversationStarter Error: $e");
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    let receiverId = ""
    let receiverType = CometChat.ReceiverType.group
    let configuration = [ "lastNMessages": 100 ]


    CometChat.getConversationStarter(receiverId: "cometchat-uid-1", receiverType: .user, configuration: configuration) { startersReplies in
        print("getConversationStarter success: \(startersReplies)")
    } onError: { error in
        print("getConversationStarter error: \(error?.errorDescription)")
    }
    ```
  </Tab>
</Tabs>

### UI Kits

Assuming the necessary prerequisites are met, Conversation Starter functions seamlessly starting from v4 of the Chat UI Kits. Similarly, Conversation Starter is triggered automatically when there are no messages in a conversation.


# Conversation Summary
Source: https://www.cometchat.com/docs/fundamentals/ai-user-copilot/conversation-summary

Generate CometChat AI conversation summaries from recent or unread messages with configurable message ranges.

**Conversation Summary** enables the summarization of conversations using AI.

## Before you begin

1. Set up the AI settings through the CometChat dashboard as detailed in the [Overview section](/docs/fundamentals/ai-user-copilot/overview).
2. Navigate to Chat > Features, under **AI User Copilot**, enable **Conversation Summary**.

   <Frame>
     <img />
   </Frame>
3. Implement the chat functionality in your applications using [CometChat's **v4** Chat SDKs](/docs/sdk/javascript/overview).

## How does it work?

CometChat AI goes through the messages of a conversation to understand the context of a conversation & provide a short summary of the conversation.

The CometChat SDK has a method to fetch the conversation summary. It returns the conversation summary as a string.

The number of messages to be fetched to generate relevant summaries is configurable. By default the CometChat AI takes the latest `1000` messages. This can be configured to specific timestamps as well.

| Configuration | Value                                                  |
| ------------- | ------------------------------------------------------ |
| lastNMessages | This will fetch specific number of messages.           |
| fromTimestamp | This will fetch messages from a particular timestamp.  |
| toTimestamp   | This will fetch messages until a particular timestamp. |
| unreadOnly    | This will fetch only the unread messages.              |

<Note>
  While using any configuration mentioned above a maximum of **only** `1000` messages will be fetched.
</Note>

## Implementation

### SDKs

To implement Conversation Summary in the platform of your choice, you may utilize the following code samples:

<Tabs>
  <Tab title="JS/React Native/Ionic SDK">
    ```js theme={null}
    const receiverId = "UID/GUID";
    const receiverType = "user/group";
    const configuration = { lastNMessages: 100 };

    CometChat.getConversationSummary(receiverId, receiverType, configuration).then(
      (conversationSummary) => {
        console.log("Conversation Summary:", conversationSummary);
      },
      (error) => {
        console.log(
          "An error occurred while fetching conversation summary.",
          error
        );
      }
    );
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String receiverId = 'UID/GUID';
    String receiverType = CometChatConstants.RECEIVER_TYPE_USER; //'user/group'
    JSONObject configuration =  new JSONObject();
    try {
        configuration.put("lastNMessages", 100);
    } catch (JSONException e) {
        throw new RuntimeException(e);
    }

    CometChat.getConversationSummary(receiverId, receiverType,c onfiguration, new CometChat.CallbackListener<String>() {
        @Override
        public void onSuccess(String s) {
            Logger.error(TAG, s);
        }

        @Override
        public void onError(CometChatException e) {
            Logger.error(TAG, e.getMessage());
        }
    });
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val receiverId = "UID/GUID"
    val receiverType = CometChatConstants.RECEIVER_TYPE_USER // 'user/group'
    val configuration = JSONObject()

    try {
        configuration.put("lastNMessages", 100)
    } catch (e: JSONException) {
        throw RuntimeException(e)
    }

    CometChat.getConversationSummary(receiverId, receiverType, configuration,
        object : CometChat.CallbackListener<String>() {
            override fun onSuccess(s: String) {
                Log.e(TAG, s)
            }

            override fun onError(e: CometChatException) {
                Log.e(TAG, e.localizedMessage)
            }
    })
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    let receiverId = ""
    let receiverType = CometChat.ReceiverType.group
    let configuration = [ "lastNMessages": 100 ]

    CometChat.getConversationSummary(receiverId: receiverId, receiverType: receiverType, configuration: configuration) { summary in
        print("getConversationSummary success: \(summary)")
    } onError: { error in
        print("getConversationSummary error: \(error?.errorDescription)")
    }
    ```
  </Tab>

  <Tab title="Dart">
    ```dart theme={null}
    String receiveId = "";
    String receiverType = CometChatConversationType.user;
    Map configuration = { "lastNMessages": 100 };

    CometChat.getConversationSummary(receiveId, receiverType, configuration: configuration, onSuccess:(String summary) {
       debugPrint("getConversationSummary Success: $summary");
    }, onError: (CometChatException e) {
       debugPrint("getConversationSummary error: $e");
    });
    ```
  </Tab>
</Tabs>

### UI Kits

Assuming the necessary prerequisites are met, Conversation Summary functions seamlessly starting from v4 of the Chat UI Kits. The placement of the AI icon may vary based on the version. Clicking on the icon will display the Conversation Summary.


# AI User Copilot
Source: https://www.cometchat.com/docs/fundamentals/ai-user-copilot/overview

Overview of AI User Copilot in CometChat.

## AI-Enabled Messaging Experience

Picture a chat that effortlessly starts and flows, like catching up with your best buddy over a cup of coffee. With CometChat AI, we're making that a reality! Introducing **Conversation Starter** and **Smart Replies** that ignite natural and organic conversations. Say goodbye to awkward silences and hello to chat-filled adventures!

For those who require a concise overview of their discussions, the **Conversation Summary** feature is available to provide a succinct recap.

## Pre-requisite

* Login to your [CometChat dashboard](https://app.cometchat.com/login) and choose your app.
* Navigate to **AI Chatbot** > **Settings** in the left-hand menu.

<Frame>
  <img />
</Frame>

### Set the GPT Model

Enter the name of the Open AI ChatGPT model that you intend to use.

### Save the Open AI Key

You can get the Open AI Key from your [Open AI Account](https://platform.openai.com/account/api-keys). This will be used by CometChat to interact with the Open AI APIs.

### Set a Custom Instruction

Custom Instruction is an information which gets added in each and every ChatGPT prompt made by the CometChat AI. Custom Instruction is app-level information you can add to describe your use-case & inform what kind of responses you need from the CometChat AI.

### Set the Temperature

The API is non-deterministic by default. This means that you might get a slightly different completion every time you call it, even if your prompt stays the same. Setting temperature to 0 will make the outputs mostly deterministic, but a small amount of variability will remain.

Lower values for temperature result in more consistent outputs, while higher values generate more diverse and creative results. Select a temperature value based on the desired trade-off between coherence and creativity for your specific application.

### Enable AI

Toggle on AI.


# Smart Replies
Source: https://www.cometchat.com/docs/fundamentals/ai-user-copilot/smart-replies

Generate CometChat AI smart replies for conversations with positive, negative, and neutral response suggestions.

**Smart Replies** enable the retrieval of an AI-generated response message within a conversation.

## Before you begin

1. Configure the AI settings through the CometChat dashboard as detailed in the [Overview section](/docs/fundamentals/ai-user-copilot/overview).
2. Navigate to Chat > Features, under **AI User Copilot**, enable **Smart Replies**.

   <Frame>
     <img />
   </Frame>
3. Implement the chat functionality in your applications using [CometChat's **v4** Chat SDKs](/docs/sdk/javascript/overview).

## How does it work?

CometChat AI goes through the messages of a conversation to understand the context of a conversation & provide relevant replies. It returns three replies: `positive, negative & neutral`.

The CometChat SDK has a method to fetch the smart replies in a conversation. It returns an object of three replies with keys: `positive, negative & neutral`.

The number of messages to be fetched to generate relevant Smart Replies is configurable. By default the CometChat AI takes the latest `1000` messages. This can be configured to specific timestamps as well.

| Configuration | Value                                                  |
| ------------- | ------------------------------------------------------ |
| lastNMessages | This will fetch specific number of messages.           |
| fromTimestamp | This will fetch messages from a particular timestamp.  |
| toTimestamp   | This will fetch messages until a particular timestamp. |
| unreadOnly    | This will fetch only the unread messages.              |

<Note>
  While using any configuration mentioned above a maximum of **only** `1000` messages will be fetched.
</Note>

## Implementation

### SDKs

To implement Smart Replies in the platform of your choice, you may utilize the following code samples:

<Tabs>
  <Tab title="JS/React Native/Ionic SDK">
    ```js theme={null}
    const receiverId = "UID/GUID";
    const receiverType = "user/group";
    const configuration = { lastNMessages: 100 };

    CometChat.getSmartReplies(receiverId, receiverType, configuration).then(
      (smartReplies) => {
        const { positive, negative, neutral } = smartReplies;
        console.log("Positive Reply", positive);
        console.log("Negative Reply", negative);
        console.log("Neutral Reply", neutral);
      },
      (error) => {
        console.log("An error occurred while fetching smart replies", error);
      }
    );
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String receiverId = 'UID/GUID';
    String receiverType = 'user/group';
    JSONObject configuration =  new JSONObject();
    try {
        configuration.put("lastNMessages", 100);
    } catch (JSONException e) {
        throw new RuntimeException(e);
    }

    CometChat.getSmartReplies(receiverId, CometChatConstants.RECEIVER_TYPE_USER, configuration, new CometChat.CallbackListener<HashMap<String, String>>() {
        @Override
        public void onSuccess(HashMap<String, String> smartReplies) {
            Iterator<String> iterator = smartReplies.keySet().iterator();
            for (String s : smartReplies.keySet()) {
                Log.e(TAG, "Smart Reply : " + iterator.next() + " " + smartReplies.get(s));
            }
        }

        @Override
        public void onError(CometChatException e) {
            Logger.error(TAG, e.getMessage());
        }
    });
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val receiverId: String = 'UID/GUID'
    val receiverType: String = 'user/group'
    val configuration = JSONObject()
    try {
        configuration.put("lastNMessages", 100)
    } catch (e: JSONException) {
        throw RuntimeException(e)
    }

    CometChat.getSmartReplies(
        receiverId,
        CometChatConstants.RECEIVER_TYPE_USER,
        configuration,
        object : CallbackListener<HashMap<String, String>>() {
            override fun onSuccess(smartReplies: HashMap<String, String>) {
                val iterator: Iterator<String> = smartReplies.keys.iterator()
                for (s in smartReplies.keys) {
                    Log.e(TAG, "Smart Reply : " + iterator.next() + " " + smartReplies[s])
                }
            }

            override fun onError(e: CometChatException) {
                Logger.error(TAG, e.message)
            }
        }
    )
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    let receiverId = ""
    let receiverType = CometChat.ReceiverType.user
    let configuration = [ "lastNMessages": 100 ]

    CometChat.getSmartReplies(receiverId: receiverId, receiverType: receiverType, configuration: configuration) { smartRepliesMap in
        print("GetSmartReplies success: \(smartRepliesMap)")
    } onError: { error in
        print("GetSmartReplies error: \(error?.errorDescription)")
    }
    ```
  </Tab>

  <Tab title="Dart">
    ```dart theme={null}
    String receiveId = "";
    String receiverType = CometChatConversationType.user;
    Map configuration = { "lastNMessages": 100 };


    CometChat.getSmartReplies(receiveId, receiverType, configuration: configuration, onSuccess: (HashMap<String, String> map) {
        debugPrint("getSmartReplies Success: $map");
    }, onError: (CometChatException e) {
        debugPrint("getSmartReplies Error: $e");
    });
    ```
  </Tab>
</Tabs>

### UI Kits

Assuming the necessary prerequisites are met, Smart Replies function seamlessly starting from v4 of the Chat UI Kits. In v4, Smart Replies are accessible manually, whereas in v5, they work automatically.


# Avatars (Deprecated)
Source: https://www.cometchat.com/docs/fundamentals/avatars

Upload and update CometChat user avatar images with base64 files, hosted avatar URLs, and profile metadata.

<Warning>
  Deprecated: This extension is no longer maintained and will not receive further updates.
</Warning>

This extension allows the end-users to upload an avatar image for their profile.

With the Avatars Extension, your users can upload your end-users' avatar directly in CometChat. This extension is useful when you do not have a user profile management feature in your website or mobile app.

<Frame>
  <img />
</Frame>

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Avatars extension.

## How does it work?

This extension allows the users to select an image for their avatar on CometChat.

Once the image file is selected for the avatar, it needs to be uploaded in the `base64` format. The extension hosts the image and updates its URL in the avatar section of the user's profile. Also, the avatar URL is sent back in the success response for being updated in your backend.

Image formats allowed by the extension are: `jpg`, `jpeg`, `png`, svg.

Make use of the `callExtension` method provided by the CometChat SDK as shown below.

<Note>
  Max size limit

  The size of the Avatar image file is limited to 2 MB. Please validate the size of the image before uploading it to CometChat via this extension.
</Note>

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension(
      'avatar',
      'POST',
      'v1/upload',
      {
        avatar:
          'data:image/jpeg;base64,abcd',
      }
    ).then(response => {
       // { avatarURL: "https://data-eu.cometchat.io/avatars/photo123.jpg" }
      }).catch(error => {
       // Error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;
    JSONObject body=new JSONObject();

    // bytes refer to the selected image bytes
    String imageString = Base64.encodeToString(bytes, Base64.NO_WRAP);

    // The image type can image/jpg, image/png, etc.
    // based on the image file under consideration.
    body.put("avatar", "data:image/png;base64,abcd"+imageString);

    CometChat.callExtension("avatar", "POST", "/v1/upload", body,
    new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // {avatarURL: "https://data-us.cometchat.io/avatars/1a2b3c.jpg"}
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "avatar", type: .post, endPoint: "/v1/upload", 
      body: ["avatar": "data:image/png;base64,abcd", onSuccess: { (response) in
        // { avatarURL: "https://data-eu.cometchat.io/avatars/1a2b3c.jpg" }
      }) { (error) in
        // Some error occured
      }
    }
    ```
  </Tab>
</Tabs>


# Bitly
Source: https://www.cometchat.com/docs/fundamentals/bitly

Shorten long links in CometChat text messages with Bitly by configuring an access token, group GUID, and extension call.

*Learn how to minify the long website links in your text messages using Bitly.*

## Before you begin

1. Sign up with [Bitly](https://bitly.com/).
2. Once you have logged in, click on the Account name displayed in the top right corner.
3. Click on Settings and in the left navigation pane, select API.
4. Click on Generate Token to create a new Access Token.
5. Using the above Access Token, fetch the GUID for your group using their [Get Groups API](https://dev.bitly.com/api-reference#getGroups).
6. The Access Token and Bitly Group's GUID are required in extension settings.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Bitly extension.
3. Open the settings for this extension.
4. Enter your Bitly Access Token and Group's GUID.
5. Save your settings.

## How does it work?

This extension uses the `callExtension` method provided by the CometChat SDK. You can call the extension as follows:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension("url-shortener-bitly", "POST", "v1/shorten", {
      text: "Your message with URL https://yourdomain.com/very/very/long/url",
    })
      .then((response) => {
        // minifiedText in response
      })
      .catch((error) => {
        // Error occured
      });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String URL = "/v1/shorten";
    JSONObject body=new JSONObject();

    body.put("text", "Your message with URL https://yourdomain.com/very/very/long/url");

    CometChat.callExtension("url-shortener-bitly", "POST", URL, body,
    new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // minifiedText from the extension
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "url-shortener-bitly", type: .post, endPoint: "v1/shorten", body: ["text": "Your message with URL https://yourdomain.com/very/very/long/url"], onSuccess: { (response) in
            // minifiedText from the extension
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>


# Chatwoot
Source: https://www.cometchat.com/docs/fundamentals/chatwoot

Connect Chatwoot with CometChat to route customer support conversations through your chat experience using access tokens and inbox IDs.

The Chatwoot extension makes customer support seamless for your users. Instead of having two interfaces- one for chat between users and one for chat with your support team, you can use CometChat as a front-end for your customer support use case as well!

<Frame>
  <img />
</Frame>

## Before you begin

1. You may have an existing account created with Chatwoot. If not, sign up with [Chatwoot](https://app.chatwoot.com/app/auth/signup).

2. Do the following mandatory setup on Chatwoot:

   1. To add Agent(s): [Click here](https://www.chatwoot.com/docs/user-guide/add-agent-settings)
   2. To create a Channel and Inbox: [Click here](https://www.chatwoot.com/docs/product/channels/api/create-channel)
   3. Only mention the name of the channel for now. The webhook URL can be skipped.

3. Get your Chatwoot Access token:

   1. Once you have logged in, click on your avatar in the bottom left corner.
   2. Scroll to the bottom of the Account settings section that opens up.
   3. You should find the Access token.

4. Get the inbox id:

   1. Once you have logged in, click on the Settings icon in the left bar.
   2. Click on the "Inboxes" in the navigation.
   3. Click on the Inbox that you want to set up for the CometChat support.
   4. Copy the Inbox ID from the URL. For eg, if the URL is: `https://app.chatwoot.com/app/accounts/123/settings/inboxes/12128` then the Inbox ID is `12128.`

5. Get the Account ID:

   1. While you have the settings open, click on the Account Settings in the navigation bar
   2. Copy the Account ID from there.

6. The above details will be required during the Extension's settings.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Extension settings

#### **On CometChat Dashboard**

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.

2. Go to the Extensions section and enable the Chatwoot extension.

3. Open the Settings for this extension.

4. Enter the following details about your Chatwoot account (copied earlier):

   1. Chatwoot Access token
   2. Chatwoot Account ID
   3. Chatwoot Inbox ID

5. Enter the user's UID on CometChat who's going to be the Customer Support contact.

6. Once you save the settings, a webhook URL will be generated for you.

<Frame>
  <img />
</Frame>

#### On Chatwoot Dashboard

1. Go to the Settings and the Inboxes section.
2. Click on the settings icon for the inbox in use.
3. Paste the above copied URL in the Webhook URL section.

<Frame>
  <img />
</Frame>

## How does it work?

* The end users of your app can send queries to the Customer Support user that you have set in the extension's settings.
* These queries will be forwarded to the configured Chatwoot inbox.
* When an agent replies to the queries, those will be sent over to CometChat and received by your end user.
* With this, your end users can communicate with each other as well as your Customer support team using the same Chat interface.


# Collaborative Document
Source: https://www.cometchat.com/docs/fundamentals/collaborative-document

Start CometChat collaborative document sessions from one-on-one or group chats and share document links with participants.

Learn how to collaborate using a document.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Collaborative Document extension.

## How does it work?

### Initiating the session

Using the Collaborative Document extension is pretty straight-forward. As an initiator, you only have to create a session. The extension will handle the following for you:

1. Provide you with a link for collaboration.
2. Forward the link as an invitation to the receivers.

You can initiate the session in either one-on-one chat or a group chat. The session can be shared by simply submitting the `receiver` (uid/guid) and `receiverType` (user/group).

This extension uses the `callExtension` method provided by our SDKs.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension("document", "POST", "v1/create", { 
    	"receiver": "UID/GUID",
    	"receiverType": "user/group"
    }).then(response => {
    	// Response with document url
    }).catch(error => {
    	// Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("receiverType", "user/group");
    body.put("receiver", "uid/guid");

    CometChat.callExtension("document", "POST", "/v1/create", body,
    	new CometChat.CallbackListener<JSONObject>() {
        @Override
        public void onSuccess(JSONObject responseObject) {
            // The document link to join as an initiator.
        }

        @Override
        public void onError(CometChatException e) {
          	// Some error occured.
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "document", type: .post, endPoint: "v1/create",
    body: ["receiverType":"user/group", "receiver":"uid/guid"], onSuccess: { (response) in
            // Success response
          }) { (error) in
            // Some error occured
          }
    ```
  </Tab>
</Tabs>

### Receiving the details

#### As an initiator

You will be receiving the `document_url` of the session in the success callback of the `callExtension` method as shown in the above code sample.

#### As a collaborator

The receiver (can be a user or group) will get a message with the following properties:

1. category: `custom`
2. type: `extension_document`

You have to implement the Custom message listener to get the message. Please check out our [Receive Messages](/docs/sdk/javascript/receive-message) documentation under the SDK of your choice.

By default, the unread count is not incremented for Custom Messages.

Hence, the `metadata`contains `incrementUnreadCount` with value as `true`. Use this for incrementing the unread count every time a Collaborative Document's custom message is received.

### Document metadata

The metadata section will have the details about the `document_url`.

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    "metadata": {
      	"incrementUnreadCount": true,
      	"@injected": {
          "extensions": {
            "document": {
              "document_url": "https://document.cometchat.io/p/uniqdocid"
            }
          }
        }
    }
    ```
  </Tab>
</Tabs>

You can make use of the getMetadata() method for extracting the details. Refer the code samples below:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    if (metadata != null) {
      var injectedObject = metadata["@injected"];
      if (injectedObject != null && injectedObject.hasOwnProperty("extensions")) {
        var extensionsObject = injectedObject["extensions"];
        if (
          extensionsObject != null &&
          extensionsObject.hasOwnProperty("document")
        ) {
          var documentExtension = extensionsObject["document"];
          var document_url = documentExtension["document_url"];
        }
      }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    JSONObject metadata = message.getMetadata();
    if (metadata != null) {
      JSONObject injectedObject = metadata.getJSONObject("@injected");
      if (injectedObject != null && injectedObject.has("extensions")) {
        JSONObject extensionsObject = injectedObject.getJSONObject("extensions");
        if (extensionsObject != null && extensionsObject.has("document"))
            {
              JSONObject documentObj = extensionsObject.getJSONObject("document");
              String board_url = documentObj.getString("document_url");
            }
        }
    }
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    if (metadata != null) {
      if (metadata.has("@injected")) {
       val injectedJSONObject = metadata.getJSONObject("@injected")
       if (injectedJSONObject != null && injectedJSONObject.has("extensions")) {
       val extensionsObject = injectedJSONObject.getJSONObject("extensions")

       if (extensionsObject != null && extensionsObject.has("document")) {
       val documentObj = extensionsObject.getJSONObject("document")
       val document_url = documentObj.getString("document_url")
             }     
           }
         }
       }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    let textMessage = message as? TextMessage
    var metadata : [String : Any]? = textMessage.metaData
    if metadata != nil {

        var injectedObject : [String : Any]? = (metadata?["@injected"] as? [String : Any])!
                
        if injectedObject != nil && (injectedObject!["extensions"] != nil){

          var extensionsObject : [String : Any]? = injectedObject?["extensions"] as? [String : Any]

          if extensionsObject != nil && extensionsObject?["document"] != nil             {
            var documentObj = extensionsObject?["document"] as! [String :  Any]

            let document_url = documentObj["document_url"] as! String
          }
       }
    }
    ```
  </Tab>
</Tabs>

### Start collaborating

<Frame>
  <img />
</Frame>

The Collaborative document has the following editing features:

1. Bold
2. Italic
3. Underline
4. Strikethrough
5. Numbered list
6. Bulleted list
7. Indent and Outdent

You can export your document as:

1. Etherpad
2. HTML
3. Plain text


# Collaborative Whiteboard
Source: https://www.cometchat.com/docs/fundamentals/collaborative-whiteboard

Start CometChat collaborative whiteboard sessions from one-on-one or group chats and share invitation links with participants.

Connect with other users of the app and collaborate using a Whiteboard.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Collaborative Whiteboard extension.

## How does it work?

### Initiating the session

Using the Collaborative Whiteboard extension is pretty straight-forward. As an initiator, you only have to create a session. The extension will handle the following for you:

1. Provide you with a link for collaboration.
2. Forward the link as an invitation to the receivers.

You can initiate a whiteboard in either one-on-one chat or a group chat. The session can be shared by simply submitting the `receiver` (uid/guid) and `receiverType` (user/group).

This extension uses the `callExtension` method provided by our SDKs.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension("whiteboard", "POST", "v1/create", {
      receiver: "UID/GUID",
      receiverType: "user/group",
    })
      .then((response) => {
        // Response with board_url
      })
      .catch((error) => {
        // Some error occured
      });
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    CometChat.callExtension("whiteboard", "POST", "v1/create", {
      receiver: "UID/GUID",
      receiverType: "user/group",
    })
      .then((response: any) => {
        // Response with board_url
      })
      .catch((error: any) => {
        // Some error occurred
      });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("receiverType", "user/group");
    body.put("receiver", "uid/guid");

    CometChat.callExtension("whiteboard", "POST", "/v1/create", body,
    	new CometChat.CallbackListener<JSONObject>() {
        @Override
        public void onSuccess(JSONObject responseObject) {
            // The whiteboard link to join as an initiator.
        }

        @Override
        public void onError(CometChatException e) {
          	// Some error occured.
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "whiteboard", type: .post, endPoint: "v1/create", body: ["receiverType":"user/group", "receiver":"uidguid"], onSuccess: { (response) in
            // Success response
          }) { (error) in
            // Some error occured
          }
    ```
  </Tab>

  <Tab title="Dart">
    ```dart theme={null}
      Map<String, String> body = {
          'receiverType': 'user/group',
          'receiver': 'uid/guid',
        };
        CometChat.callExtension("whiteboard", "POST", "/v1/create", body, onSuccess: (map) {

        }, onError: (e) {

      });
    ```
  </Tab>
</Tabs>

### Receiving the details

#### As an initiator

You will be receiving the `board_url` of the whiteboard session in the success callback of the `callExtension` method as shown in the above code sample.

#### As a collaborator

The receiver (a user or group) will get a message with the following properties:

1. category: `custom`
2. type: `extension_whiteboard`

You have to implement the Custom message listener to get the message. Please check out our [Receive Messages](/docs/sdk/javascript/receive-message) documentation under the SDK of your choice.

By default, the unread count is not incremented for Custom Messages.

Hence, the `metadata`contains `incrementUnreadCount` with value as `true`. Use this for incrementing the unread count every time a Collaborative whiteboard's custom message is received.

### Append username to the Whiteboard URL

On the whiteboard screen, the mouse pointers of the collaborating users can be identified with the help of usernames. This username can be appended to the whiteboard URL before opening it.

You can use `CometChat.getLoggedinUser()` method to get the details about the logged-in user. Refer to our [Retrieve Users](/docs/sdk/javascript/retrieve-users) documentation for retrieving the details about the logged-in user. The following is for your reference:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.getLoggedinUser().then(
      (user) => {
        // Replace spaces with underscore
        let username = user.name.split(" ").join("_");

        // Append the username to the board_url
        board_url = board_url + "&username=" + username;
      },
      (error) => {
        console.log("error getting details:", { error });
      }
    );
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    CometChat.getLoggedinUser().then(
      (user: CometChat.User | null) => {
        // Replace spaces with underscore
        let username = user!.getName().split(" ").join("_");

        // Append the username to the board_url
        board_url += "&username=" + username;
      },
      (error: any) => {
        console.log("error getting details:", { error });
      }
    );
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    User user = CometChat.getLoggedInUser();
    if (user != null) {
        String username = user.getName().replace(" ", "_");
        String boardUrl = "your_board_url_here"; // replace with your actual URL
        boardUrl = boardUrl + "&username=" + username;
        Log.i(TAG, "boardUrl" + boardUrl); // or use the URL as needed
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    if let loggedInUser = CometChat.getLoggedInUser() {
        let userName = loggedInUser.name
        let boardUrl = "your_board_url_here"; // replace with your actual URL
        boardUrl = "\(boardUrl)&username=\(username)"
        print(boardUrl)
    }
    ```
  </Tab>

  <Tab title="Dart">
    ```dart theme={null}
    CometChat.getLoggedInUser().then((user) {
      if(user != null) {
        String username = user.name.replaceAll(' ', '_');
        String boardUrl = 'your_board_url_here'; // replace with your actual URL
        boardUrl = '$boardUrl&username=$username';
        debugPrint(boardUrl); // or use the URL as needed
      }
    }).catchError((error) {
      debugPrint('Error getting details: $error');
    });
    ```
  </Tab>
</Tabs>

### Whiteboard metadata

The metadata section will have the details about the `board_url`.

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    "metadata": {
      	"@injected": {
          "extensions": {
            "whiteboard": {
              "board_url": "https://whiteboard-.cometchat.io?whiteboardid=abc"
            }
          }
        }
    }
    ```
  </Tab>
</Tabs>

You can make use of the getMetadata() method for extracting the details. Refer the code samples below:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    if (metadata != null) {
      var injectedObject = metadata["@injected"];
      if (injectedObject != null && injectedObject.hasOwnProperty("extensions")) {
        var extensionsObject = injectedObject["extensions"];
        if (
          extensionsObject != null &&
          extensionsObject.hasOwnProperty("whiteboard")
        ) {
          var whiteboardObject = extensionsObject["whiteboard"];
          var board_url = whiteboardObject["board_url"];
        }
      }
    }
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    if (metadata != null) {
      const injectedObject = metadata["@injected"];
      if (injectedObject != null && injectedObject.hasOwnProperty("extensions")) {
        const extensionsObject = injectedObject["extensions"];
        if (
          extensionsObject != null &&
          extensionsObject.hasOwnProperty("whiteboard")
        ) {
          const whiteboardObject = extensionsObject["whiteboard"];
          const board_url = whiteboardObject["board_url"];
        }
      }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    JSONObject metadata = message.getMetadata();
    if (metadata != null) {
      JSONObject injectedObject = metadata.getJSONObject("@injected");
      if (injectedObject != null && injectedObject.has("extensions")) {
        JSONObject extensionsObject = injectedObject.getJSONObject("extensions");
        if (extensionsObject != null && extensionsObject.has("whiteboard"))
            {
              JSONObject whiteboardObject = extensionsObject.getJSONObject("whiteboard");
              String board_url = whiteboardObject.getString("board_url");
            }
        }
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    let textMessage = message as? TextMessage
    var metadata : [String : Any]? = textMessage.metaData
    if metadata != nil {

        var injectedObject : [String : Any]? = (metadata?["@injected"] as? [String : Any])!

        if injectedObject != nil && (injectedObject!["extensions"] != nil){

          var extensionsObject : [String : Any]? = injectedObject?["extensions"] as? [String : Any]

          if extensionsObject != nil && extensionsObject?["whiteboard"] != nil             {
            var whiteboardObject = extensionsObject?["whiteboard"] as! [String :  Any]

            let board_url = whiteboardObject["board_url"] as! String
          }
       }
    }
    ```
  </Tab>

  <Tab title="Dart">
    ```dart theme={null}
    if (metadata != null) {
      if (metadata.containsKey('@injected')) {
        Map<String, dynamic>? injectedJSONObject = metadata['@injected'];
        if (injectedJSONObject.containsKey('extensions')) {
          Map<String, dynamic>? extensionsObject = injectedJSONObject['extensions'];
          if (extensionsObject != null && extensionsObject.containsKey('whiteboard')) {
            Map<String, dynamic>? whiteboardObject = extensionsObject['whiteboard'];
            if (whiteboardObject != null && whiteboardObject.containsKey('board_url')) {
              String boardUrl = whiteboardObject['board_url'];
              debugPrint(boardUrl); // or use the boardUrl as needed
            }
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Start collaborating

<Frame>
  <img />
</Frame>

Our whiteboard implementation provides the following features:

1. **Edit** a. Clear board b. Undo c. Redo
2. **Tools** a. Mouse pointer b. Select an area c. Pen d. Line e. Rectangle f. Circle g. Text h. Eraser
3. **Tool properties** a. Thickness b. Color
4. **Upload image to whiteboard**
5. **Export whiteboard as image**


# Data Import and Migration
Source: https://www.cometchat.com/docs/fundamentals/data-import-and-migration

Migrate users, messages, groups, and conversations into CometChat with historical import or live migration workflows.

Data import and migration enables you to transfer existing chat data from your own servers or another chat provider to CometChat. This ensures continuity of service and preserves your users' conversation history during the transition.

## What Can Be Migrated?

CometChat's migration capabilities cover:

* **Users**: User profiles, metadata, and account information
* **Messages**: Complete message history including text, media, and metadata
* **Groups**: Group configurations and membership information
* **Conversations**: Conversation threads and their associated data

## Migration Approaches

CometChat offers two approaches to data migration, depending on your needs:

### Historical Data Import

Import all your existing data at rest—stored messages, users, and groups—into CometChat before going live. This approach is ideal when:

* You're doing a complete platform switch
* You want all historical data available from day one
* Your migration can happen during a maintenance window

The Data Import APIs handle bulk ingestion of historical chat data, allowing you to transfer large volumes of users, messages, and group information efficiently.

### Live Data Migration

Maintain communication between users on your old system and users who have already migrated to CometChat. This approach is ideal when:

* You need zero downtime during migration
* Users will upgrade to the new app version gradually
* Seamless communication must continue throughout the transition period

Live migration bridges both systems during the upgrade cycle, ensuring no messages are lost regardless of which system a user is currently on.

## Getting Started

**For Historical Data Import**: Use the [Data Import REST APIs](/docs/rest-api/data-import) to programmatically import your users, messages, and groups.

**For Live Data Migration**: [Contact our Sales team](https://www.cometchat.com/contact-sales) to discuss your migration requirements and set up the live migration process.


# Disappearing Messages
Source: https://www.cometchat.com/docs/fundamentals/disappearing-messages

Enable CometChat disappearing messages so one-on-one and group messages can be scheduled for automatic deletion.

The Disappearing Messages extension allows end-users to send messages that disappear after a certain interval of time. This extension works for both private (one-on-one) and group messages.

This extension is also known as exploding messages on some platforms.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Disappearing messages extension.

## How does it work?

Once the messages are sent, you can immediately schedule them for deletion using the disappearing messages extension. The message with the mentioned `msgId` gets deleted at `timeInMS`.

<Warning>
  The value of timeInMS should strictly be less than 1 year
</Warning>

This extension uses the `callExtension` method provided by the CometChat SDK.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.sendMessage(textMessage) // Can be any type of message
      .then(message => {
      	CometChat.callExtension('disappearing-messages','DELETE','v1/disappear',{
        	msgId: message.id, // The id of the message that was just sent
        	timeInMS: 1633521809051 // Time in milliseconds. Should be a time from the future.
      	}).then(response => {
          // Successfully scheduled for deletion
        })
      
      	// Logic to display the sent message on the screen.
      	// ...
    	}).catch(error => {
      	// Error occured
    	});
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("msgId", ID_OF_THE_SENT_MESSAGE);
    body.put("timeInMS", 1633521809051); // Change to a future timestamp

    // Once the message is sent successfully, call this.
    CometChat.callExtension("disappearing-messages", "DELETE", "/v1/disappear", body,
    	new CometChat.CallbackListener<JSONObject>() {
        @Override
        public void onSuccess(JSONObject responseObject) {
            // Will disappear successfully.
        }

        @Override
        public void onError(CometChatException e) {
          	// Some error occured.
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    // Once a message is sent successfully, call this.
    // Change the timeInMS to a future timestamp.
    CometChat.callExtension(slug: "disappearing-messages", type: .delete, endPoint: "v1/disappear", body: ["msgId":SENT_MESSAGE_ID, "timeInMS": 1633521809051], onSuccess: { (response) in
    	// Will disappear successfully
    }) { (error) in
      // Some error occured
    }
    ```
  </Tab>
</Tabs>


# Email Replies (Legacy)
Source: https://www.cometchat.com/docs/fundamentals/email-replies

Let users reply to CometChat email notifications through SendGrid inbound parse webhooks and conversation routing.

<Warning>
  **Legacy Notice**: This extension is considered legacy and is scheduled for deprecation in the near future. It is no longer recommended for new integrations.

  Please note: Legacy extensions are no longer actively maintained and will not receive feature updates or enhancements.
</Warning>

## About the extension

The Email Replies adds extra functionality to the Email Notifications extension by enabling the receiver of the Email Notification to respond to the conversation by directly replying to the email.

## Pre-requisite

To start using Email Notifications with Replies, you need to first enable and save the settings for Email Notifications extension. [Learn more](/docs/notifications/email-overview).

Once it is set up, you can come back and proceed from here.

## SendGrid Setup

### SendGrid Inbound parse webhook

Once your Domain Authentication is successful, you need to set up the Inbound parse. You need to add the MX record to your Domain name provider. More details about Inbound parsing can be found [here](https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/).

The Webhook URL will be as follows:

For apps in the US region:

<Tabs>
  <Tab title="HTTP">
    ```
    https://email-notification-us.cometchat.io/v1/reply
    ```
  </Tab>
</Tabs>

For apps in the EU region:

<Tabs>
  <Tab title="HTTP">
    ```
    https://email-notification-eu.cometchat.io/v1/reply
    ```
  </Tab>
</Tabs>

For apps in the IN region:

<Tabs>
  <Tab title="HTTP">
    ```
    https://email-notification-in.cometchat.io/v1/reply
    ```
  </Tab>
</Tabs>

Before saving the Inbound Host and URL:

1. Uncheck **Spam Check** checkbox.
2. Uncheck **Send Raw** checkbox.

## Extension Settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Email replies extension.
3. Open up the settings page for this extension.
4. Select *Email replies* option and enter the sender Email ID.
5. Save your settings.

<Note>
  When adding Sender's Email in the settings, please make sure that it does not have "+" in it.
</Note>

<Frame>
  <img />
</Frame>

## Save users' Email IDs

You can use our to set private metadata for a user. We recommend adding this code where you call our .

Alternatively, just for the sake of testing purposes, you can add this from the CometChat Dashboard as well.

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the "Users" section.
3. Select any user of your choice and select the "Profile" tab.
4. Paste the below JSON in the Metadata input box and hit Save.

The Metadata is a JSON that should have the `@private` key present and should have the value `email` specified for the user. The format for the private metadata must be as follows:

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "@private":
      {
        "email":"abc@xyz.com"
      }
    }
    ```
  </Tab>
</Tabs>

## Respond via Email

Send a message to an offline user and watch them receive an email automagically. Reply to the Email and receive a response in your chat.

## Send Reply via Email

Click on **Reply** button in your mailbox and the composer will open up. Type your message and hit send. Your message will be sent to the CometChat user as a response in the chat.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Warning>
  Do not add any other Email ID in To, Cc, or Bcc fields while replying.
</Warning>


# Emojis (Deprecated)
Source: https://www.cometchat.com/docs/fundamentals/emojis

Emojis (Deprecated) — CometChat documentation.

<Warning>
  Deprecated: This extension is outdated as all the major browsers natively support emojis.
</Warning>


# End To End Encryption (Deprecated)
Source: https://www.cometchat.com/docs/fundamentals/end-to-end-encryption

Configure CometChat end-to-end encryption with Virgil Security keys, local message encryption, and sample app setup.

<Warning>
  Deprecated: This extension is no longer maintained and will not receive further updates.
</Warning>

Ensure only your users can read what is sent and nobody in between.

End-to-end encryption is intended to prevent data being read or modified by anyone but the sender and recipient(s). The messages are encrypted by the sender and decrypted by the recipient locally on their device. [Virgil Security](https://virgilsecurity.com/) is an industry leader in end-to-end encryption.

<Card>
  I want to checkout the sample app

  End-to-end Encryption Sample app for Web (React)

  Follow the steps mentioned in the `README.md` file.

  Kindly, click on below button to download.

  [Sample app](https://github.com/cometchat/javascript-react-chat-end-to-end-encryption-app/archive/refs/tags/3.0.5-1.zip)

  [View on Github](https://github.com/cometchat/javascript-react-chat-end-to-end-encryption-app)
</Card>

## Before you begin

1. Sign up or Log in to [https://dashboard.virgilsecurity.com/apps](https://dashboard.virgilsecurity.com/apps)

2. Create a New application.

3. Go to E3Kit section and create the .env file. Copy the following details:

   1. `APP_ID`
   2. `APP_KEY_ID`
   3. `APP_KEY`

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.

2. Go to the Extensions section and enable the End-to-end encryption extension.

3. Open the Settings for this extension and save the following:

   1. `APP_ID`
   2. `APP_KEY_ID`
   3. `APP_KEY`

4. Save your settings.

## How does it work?

Virgil E3Kit uses the concept of Asymmetric key cryptography for achieving End-to-end encryption of messages. The process and code for encryption and decryption for your platform can be found at Virgil's documentation [here](https://developer.virgilsecurity.com/docs/e3kit/end-to-end-encryption/default/#sign-and-encrypt-data).

CometChat users and groups are considered as `identities` on Virgil.

### Handled by the extension

#### 1. Creation of Virgil token and identity

`VIRGIL TOKEN` is required for initialization of E3Kit on the client-side.

CometChat users and groups have `IDENTITIES` on Virgil.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('e2ee', 'GET', '/v1/virgil-jwt', null)
      .then(response => {
      const { virgilToken, identity } = response;
     })
     .catch(error => {
      // Error occured
     });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    CometChat.callExtension("e2ee", "GET", "/v1/virgil-jwt", null,
    new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // virgilToken, identity
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "e2ee", type: .get, endPoint: "/v1/virgil-jwt", body: nil, onSuccess: { (response) in
            // virgilToken, identity
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>

#### 2. Fetching the identities for users and groups

In order to encrypt and decrypt messages, the E3Kit requires the `IDENTITIES`. These can be cached in your app for reuse.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const uids = ['cometchat-uid-1'];
    const guids = ['cometchat-guid-1', 'anothergroup'];
    CometChat.callExtension('e2ee', 'POST', '/v1/get-identities', { uids, guids })
      .then(response => {
       // userIdentities and groupIdentities are array of objects.
       // Each object has (g)uid as the key and the identity as its value.
      const { userIdentities, groupIdentities } = response;
     })
     .catch(error => {
      // Error occured
     });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    JSONArray uids = new JSONArray();
    JSONArray guids = new JSONArray();

    uids.add("cometchat-uid-1");
    guids.add("cometchat-guid-1", "anothergroup");

    body.put(uids);
    body.put(guids);

    CometChat.callExtension("e2ee", "POST", "/v1/get-identities", body,
     new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // userIdentities, groupIdentities
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "e2ee", type: .post, endPoint: "v1/get-identities", body: ["uids":["cometchat-uid-1"], "guids":["cometchat-guid-1", "anothergroup"]] as [String : Any], onSuccess: { (response) in
             // userIdentities, groupIdentities
          }) { (error) in
             // Error occured
          }
    ```
  </Tab>
</Tabs>

#### 3. Group actions

Group Management on Virgil is different from the Group Management on CometChat.

Virgil groups have the following restrictions:

1. The creator of the group is called as the `GROUP OWNER.`
2. Only the `GROUP OWNER` can add members to or remove members from a Virgil group.
3. Group can be deleted only by the `GROUP OWNER`.

Hence, to reduce the development efforts on the front-end, the following group actions are handled by the extension:

1. Create group
2. Delete group
3. Add member(s) to group
4. Kick a member from a group
5. Ban a member from a group
6. Member joins a group
7. Change in group owner/moderator/admin

You will need the `GROUP OWNER` identity to list the groups followed by encrypting or decrypting messages from those groups. The `IDENTITY` for the `GROUP OWNER` is `2137f9ef75295ea`.

Learn more about Virgil Group Encryption [here](https://developer.virgilsecurity.com/docs/e3kit/end-to-end-encryption/group-chat/).

### To be handled on app

#### Login

1. The user logs in to CometChat.

2. Your app makes a call to the extension to get the `VIRGIL TOKEN` and `VIRGIL IDENTITY` for the logged in user.

3. Logged in user is then registered on Virgil cloud using the client-side E3Kit. This step requires the `VIRGIL TOKEN` that was generated before. Learn more about setting up E3Kit client [here](https://developer.virgilsecurity.com/docs/e3kit/get-started/setup-client/). The `EThree.initialize` method takes a second parameter that is object with the following two keys:

   1. `groupStorageName`: Pass the value as `.g_${current_timestamp}`
   2. `storageName`: Pass the value as`.l_${current_timestamp}`

4. In this process of registration, a `CARD` is generated for the logged in user. It contains the `PUBLIC KEY` that is available for everyone else.

5. Also, a `PRIVATE KEY` is generated and stored locally for the logged in user.

6. This `PRIVATE KEY` is very important and must be backed up using E3Kit. This step requires the `VIRGIL IDENTITY` that was generated for the logged in user.

#### Message encryption (Send a message)

1. The logged in user fetches the `VIRGIL IDENTITY` of the receiver by making a call to the extension.
2. This `VIRGIL IDENTITY` is then used for fetching the receiver's `CARD`.
3. This `CARD` is then used to encrypt the text message.
4. The encrypted message is then sent to the receiver using the CometChat SDK.

#### Message decryption (Receive a message)

1. The encrypted message is received by the logged in user in the appropriate listener provided by CometChat SDK.
2. The logged in user decrypts the message using the `PRIVATE KEY` at his end to view the original text.

<Note>
  Learn more about encryption and decryption of one-on-one messages [here](https://developer.virgilsecurity.com/docs/e3kit/end-to-end-encryption/default/).\
  Learn more about encryption and decryption of group messages [here](https://developer.virgilsecurity.com/docs/e3kit/end-to-end-encryption/group-chat/#encrypt-and-decrypt-messages).
</Note>

#### Logout

1. Call the `cleanup()` method provided by the E3Kit to remove the Private key from the user's device.
2. Make sure that the back up was created during the Login process in **Step 1**.

For implementation details on the platform of your choice, please refer to Virgil E3Kit [documentation](https://developer.virgilsecurity.com/docs/e3kit/).

<Warning>
  Private key backup

  It is very important that you take a backup of the Private key for the logged in users. If that is lost, a new CARD has to be generated on Virgil that leads to creation of new Private and Public key pair.\
  Older messages cannot be decrypted using the new Private key. More details can be found [here](https://developer.virgilsecurity.com/docs/e3kit/key-backup/).
</Warning>

#### Recommended Login flow

The following flow is recommended to make sure that:

1. The `PRIVATE KEY` is backed up during the first time a user registers using Virgil's E3Kit.
2. Your users are able to restore the `PRIVATE KEY`, thus ensuring multi-device support and continued access to older messages.
3. Virgil Group actions can be performed on behalf of the user by the extension.

<Frame>
  <img />
</Frame>

<Warning>
  CAVEATS

  1. Other extensions will not work once the End-to-end encryption extension is enabled. As the messages will only be visible to your end users.
  2. The extension needs to be enabled and correctly configured immediately after an app is created on the CometChat Dashboard.
  3. Extension does not work for existing groups.
  4. If the user loses the Private Key, they will not be able to decrypt older messages encrypted using the lost key pair. Hence, backup of Private key is very important.
</Warning>


# Extensions
Source: https://www.cometchat.com/docs/fundamentals/extensions-overview

Overview of Extensions in CometChat.

We believe that building a great chat product does not consist of just voice, video and text chat. It's much more than that. And Extensions are our answer to this.

Extensions pickup where our core leaves. They help extend the functionality of CometChat.

### User Experience

Extensions that help improve the user messaging experience. *Recommended for most apps.*

[Bitly](/docs/fundamentals/bitly)\
[Link Preview](/docs/fundamentals/link-preview)\
[Message shortcuts](/docs/fundamentals/message-shortcuts)\
[Pin message](/docs/fundamentals/pin-message)\
[Rich Media Preview](/docs/fundamentals/rich-media-preview)\
[Save message](/docs/fundamentals/save-message)\
[Thumbnail Generation](/docs/fundamentals/thumbnail-generation)\
[TinyURL](/docs/fundamentals/tinyurl)\
[Voice Transcription](/docs/fundamentals/voice-transcription)\
[Avatars](/docs/fundamentals/avatars)

### User Engagement

Extensions that help increase user engagement. *Recommended for advanced apps.*

[Giphy](/docs/fundamentals/giphy)\
[Message Translation](/docs/fundamentals/message-translation)\
[Polls](/docs/fundamentals/polls)\
[Reminders](/docs/fundamentals/reminders)\
[Stickers](/docs/fundamentals/stickers)\
[Stipop](/docs/fundamentals/stickers-stipop)\
[Tenor](/docs/fundamentals/tenor)\
[Email replies](/docs/fundamentals/email-replies)\
[Mentions](/docs/fundamentals/mentions)\
[Reactions](/docs/fundamentals/reactions)\
[Smart Reply](/docs/fundamentals/smart-replies)\
[Live Streaming by api.video](/docs/fundamentals/video-broadcasting)

### Collaboration

Extensions that help with collaboration. *Recommended for advanced apps.*

[Collaborative Whiteboard](/docs/fundamentals/collaborative-whiteboard)\
[Collaborative Document](/docs/fundamentals/collaborative-document)

### Security

*Extensions that help you to build adding extra security to your apps.* *Recommended for live streaming and event apps.*

[Disappearing messages](/docs/fundamentals/disappearing-messages)\
[End to End Encryption](/docs/fundamentals/end-to-end-encryption)

### Customer Support

Extensions that help you add support to your app. *Recommended for advanced apps.*

[Chatwoot](/docs/fundamentals/chatwoot)\
[Intercom](/docs/fundamentals/intercom)

### Notifications

Extensions that help alert users of new messages. *Recommended for all apps.*

[Push Notification](/docs/notifications/web-push-notifications)\
[Email Notification](https://assets.cometchat.io/legacy-docs/notifications/email-notifications-extension-legacy.html)\
[SMS Notification](https://assets.cometchat.io/legacy-docs/notifications/sms-notifications-extension-legacy.html)

### Moderation

*Extensions that help you to build a safe messaging environment.* *Recommended for live streaming and event apps.*

[Legacy Moderation Extensions](https://assets.cometchat.io/legacy-docs/moderation/legacy-extensions.html)


# Core In App Messaging Features
Source: https://www.cometchat.com/docs/fundamentals/features-core

Explore CometChat core messaging features such as user and group chat, media sharing, receipts, typing indicators, mentions, and reactions.

CometChat provides a powerful suite of messaging features. A subset of these features called 'Messaging Core' provide features which are bare minimum to build a good chat user experience.

The following are some of the most used Core features:

* User to User and Group chat:

  * This is the most basic form of messaging which can exists between two individual users or users that are a part of a group. For a developer's perspective, the actual chat works using the following delivery methods:
  * On the message sender's side, the messages are sent using CometChat UI Kits which use SDKs which act as an API wrapper.
  * On the message receiver's side, the messages are delivered using a Websocket connection to the CometChat plaform which is managed by the SDKs.
  * For more details on Websockets and its connectivity details, please visit [Managing Web Sockets](/docs/sdk/javascript/managing-web-sockets-connections-manually) in the CometChat SDK.
  * By default, user and group messaging along with Web Socket implementation is available in the UI Kits.

* Media sharing:

  * Sharing files, videos and other media types are the key in today's messaging world. You can implement media messages using SDKs or UI Kits as well as use [Extensions](/docs/fundamentals/extensions-overview) for Gifs and Stickers.
  * By default, support for Media messages is available in the UI Kits.

* Message Delivery and Read receipts:

  * Message delivery receipts indicate that a message has reached the message receiver. Message read receipt indicates that the message has been read by the message receiver. CometChat supports the following features from a message delivery and read indicator perspective:
  * Mark up to a message as delivered.
  * Mark up to a message as read.
  * Mark all messages after a particular message as unread.
  * To view these features, please visit [Delivery and Read receipts](/docs/sdk/javascript/delivery-read-receipts#mark-messages-as-unread) in the SDK docs.
  * By default, support delivery and read receipts is available in the UI Kits.

* Typing indicators:

  * Typing indicators in a conversation provide an indication to other users that a given user is typing a message. To implement typing indicators, visit the [Typing indicators](/docs/sdk/javascript/typing-indicators) section of the SDK docs.
  * By default, support Typing indicators is available in the UI Kits.

* Mentions (@username):

  * Mentions allow users to refer to a specific user in a conversation. This is done by sending a '@username' in the message to address that user.
  * To implement Mentions, please visit [Mentions](/docs/sdk/javascript/mentions) section in the SDK docs.
  * By default, support for Mentions is available in the UI Kits.

* Reactions:

  * Reactions on a message allow users to express their emotions using emojis. To implement Reactions, please visit the [Reactions](/docs/sdk/javascript/reactions) section in the SDK docs.
  * By default, support for Reactions is available in the UI Kits.

* Threaded Conversations:

  * Message threads allow users to branch off a conversation specific to a topic within a conversation in a sub-conversation. Such a conversation is called a Threaded conversation. To implement Threads in a conversation, please visit [Threaded Messages](/docs/sdk/javascript/threaded-messages) section in the docs.
  * By default, support for Threaded conversations is available in the UI Kits.

* User presence:

  * User presence helps users to understand if a particular user is online and hence available for chat. To implement User presence, please visit the [User Presence](/docs/sdk/javascript/user-presence) section in the docs.
  * By default, support for User Presence is available in the UI Kits.


# Gfycat (Deprecated)
Source: https://www.cometchat.com/docs/fundamentals/gfycat

Gfycat (Deprecated) — CometChat documentation.

<Warning>
  Deprecated: This extension is no longer maintained and will not receive further updates.
</Warning>

Gfycat ceased their operations recently. This extension is no longer available.

Please check out our [Giphy](/docs/fundamentals/giphy) extension that is similar to Gfycat.


# Giphy
Source: https://www.cometchat.com/docs/fundamentals/giphy

Add Giphy GIFs to CometChat conversations with trending GIFs, search results, API keys, and extension calls.

GIFs are a great way to change the tone or convey emotions in your conversations. Here's a guide which helps to implement Gifphy in an easy and quick way. Let's get started!

## Before you begin

1. Sign up at [Giphy](https://developers.giphy.com/dashboard/) and create a new app.
2. Select API and click on Next.
3. Enter your App name, description and click create.
4. Make note of the API key that has been created.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Giphy extension.
3. Click on the settings button and enter your Giphy API key and hit save.

## How does it work?

This extension uses the `callExtension` method provided by the CometChat SDK. You can perform the following actions using this method:

1. Get trending GIFs
2. Search for GIFs

### Get Trending GIFs

To list and show the most trending GIFs on Giphy, all you have to do is include the following parameters in your request.

| key    | Value  | Description                                                                                                    |
| ------ | ------ | -------------------------------------------------------------------------------------------------------------- |
| offset | number | Since you can get paginated results for trending GIFs, you can provide an offset and fetch results accordingly |
| limit  | number | The number of trending GIFs that you want to fetch                                                             |

Once you have set the above parameters, you can make a call to the extension as follows:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const URL = "v1/trending?offset=1&limit=15";
    CometChat.callExtension("gifs-giphy", "GET", URL, null)
      .then((response) => {
        // GIFs data from Giphy
      })
      .catch((error) => {
        // Error occured
      });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String URL = "/v1/trending?offset=1&limit=15";

    CometChat.callExtension("gifs-giphy", "GET", URL, null,
    new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // GIFs data from Giphy
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "gifs-giphy", type: .get, endPoint: "v1/trending?offset=10&limit=15", body: nil, onSuccess: { (response) in
            // GIFs data from Giphy
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>

### Search for GIFs

Apart from listing the trending ones, the extension also allows searching for a particular GIF using the following parameters:

| key    | value                                  | Description                                                                                                |
| ------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| offset | number                                 | Since you can get paginated results for searches, you can provide an offset and fetch results accordingly. |
| limit  | number                                 | The number of GIFs that you want to fetch as part of the search.                                           |
| lang   | 2-letter ISO 639-1 language identifier | (Optional) Defaults to en. (Example values: es, fr, it.)                                                   |
| query  | string                                 | Search term                                                                                                |

Once you have all the above parameters, you can make a call to the extension as follows:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const URL = "v1/search?offset=1&limit=15&query=awesome";
    CometChat.callExtension("gifs-giphy", "GET", URL, null)
      .then((response) => {
        // GIFs data from Giphy
      })
      .catch((error) => {
        // Error occured
      });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String URL = "/v1/search?offset=1&limit=15&query=awesome";

    CometChat.callExtension("gifs-giphy", "GET", URL, null,
    new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // GIFs data from Giphy
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "gifs-giphy", type: .get, endPoint: "v1/search?offset=10&limit=15&query=awesome", body: nil, onSuccess: { (response) in
            // GIFs data from Giphy
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>


# Implementation Checklist
Source: https://www.cometchat.com/docs/fundamentals/implementation-checklist

Follow the CometChat implementation checklist for signup, SDK or UI Kit integration, user sync, extensions, testing, and launch.

### 1. Complete the Signup Process

<Frame>
  <img />
</Frame>

* [Create a free account](https://app.cometchat.com/signup) with CometChat.
* Familiarize yourself with the [key concepts](/docs/fundamentals/key-concepts).
* Send invitations to other developers, product owners for collaboration.

### 2. Integrate the chosen UI Kit or SDK into your application

<Frame>
  <img />
</Frame>

* Choose to integration CometChat in your app either by using UI Kits or SDKs.
* Have a look at our Sample apps for quickly checking out features and functionalities.
* UI Kits: [React](/docs/ui-kit/react/overview), [React Native](/docs/ui-kit/react-native/overview), [iOS](/docs/ui-kit/ios/overview), [Android](/docs/ui-kit/android/overview), [Flutter](/docs/ui-kit/flutter/overview), [Angular](/docs/ui-kit/angular/overview), [Vue](/docs/ui-kit/vue/overview)\
  SDKs: [JavaScript](/docs/sdk/javascript/overview), [React Native](/docs/sdk/react-native/overview), [iOS](/docs/sdk/ios/overview), [Android](/docs/sdk/android/overview), [Flutter](/docs/sdk/flutter/overview), [Ionic/Capacitor](/docs/sdk/ionic-legacy/overview) & [Sample apps](https://github.com/cometchat)

### 3. Synchronize users and groups utilizing the APIs

* This step involves the backend side of implementation.
* When a new user signs up in your system, create the corresponding user's entry with CometChat using APIs.
* Whenever a user's details are updated in your system, synchronize them with CometChat.
* [Create users API](/docs/rest-api/users/create)
* [Update users API](/docs/rest-api/users/update)

### 4. Enable necessary extensions

<Frame>
  <img />
</Frame>

* Enable extensions like [Thumbnail generator](/docs/fundamentals/thumbnail-generation), [Message translation](/docs/fundamentals/message-translation), etc.
* Implement the frontend for these [extensions](/docs/fundamentals/extensions-overview) in case the implementation does not exist.

### 5. Implement Push notifications

* Drive user engagement in your applications through the integration of [Push Notifications](/docs/notifications/push-overview).

### 6. Integrate CometChat AI

<Frame>
  <img />
</Frame>

* Ignite natural and organic converstaions between your users.
* [CometChat AI](/docs/fundamentals/ai-user-copilot/overview)

### 7. Set up bots

<Frame>
  <img />
</Frame>

* [Bots](/docs/ai-chatbots/custom-bots) are unique users capable of autonomously sending and receiving messages. You can define a bot's behaviour by implementing and exposing your business logic using Callback URLs.

### 7. Set up webhooks

<Frame>
  <img />
</Frame>

* [Webhooks](/docs/fundamentals/webhooks) faciliate real-time event-driven communication with your system, enabling you to receive HTTP POST requests from CometChat that carry details about different events.

### 9. Secure user logins with authentication tokens

* Ensuring safe and secure authentication of users in CometChat is crucial. Achieve this by utilizing [auth tokens](/docs/rest-api/chat-apis).
* Generate and retrieve the [auth token](/docs/rest-api/chat-apis) through your backend system, then supply it to the frontend.

### 10. Set up data import and migration

* To seamlessly transition from your existing chat solution to CometChat's comprehensive solution, you will need to [import your existing data](/docs/fundamentals/data-import-and-migration) as well as migrate the [live data](/docs/fundamentals/data-import-and-migration) to CometChat.

### 11. Launch your applications with the new messaging capabilities

* Delete default/test users and groups.
* Select a correct billing plan.
* Go live with your apps powered by CometChat.
* [CometChat Dashboard](https://app.cometchat.com).


# Intercom
Source: https://www.cometchat.com/docs/fundamentals/intercom

Connect Intercom with CometChat to route customer support conversations through chat using access tokens and support user IDs.

The Intercom extension makes customer support seamless for your users. Instead of having two interfaces- one for chat between users and one for chat with your support team, you can use CometChat as a front-end for your customer support use case as well!

<Frame>
  <img />
</Frame>

## Before you begin

1. You may have an existing account created with Intercom. If not, sign up with [Intercom](https://intercom.com).
2. Create a test workspace by following these [steps](https://www.intercom.com/help/en/articles/188-create-a-test-workspace-in-intercom) from Intercom's documentation.
3. Once that is done, go back to the settings and expand the Developers section.
4. Click on DeveloperHub and create an app.
5. Select the newly created app and go to the Authentication section.
6. Copy the Access token as this will be required later.

<Frame>
  <img />
</Frame>

<Note>
  The integration works with Intercom API Verion `2.3 (2020-11-12)`. If there's a version mismatch, the extension won't work.
</Note>

## Extension settings

#### On CometChat Dashboard

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.

2. Go to the Extensions section and enable the Intercom extension.

3. Open the Settings for this extension.

4. Enter the following and save your settings:

   1. **Intercom Access token**: Copied earlier from the Intercom Developer Hub.
   2. **Customer Support UID**: A user on CometChat that is your Customer Support user.

5. Once you save your settings, a Webhook URL will be auto generated for your app.

<Frame>
  <img />
</Frame>

#### On Intercom Developer Hub

1. Copy the above auto-generated Webhook URL and paste it in the Webhooks section on the Intercom Developer Hub.
2. From the Webhook Topics, select `conversation.admin.replied`

<Frame>
  <img />
</Frame>

## How does it work?

The end users of your app can send queries to the Custom Support user that you have set in the extension's settings.

These queries will be forwarded to the Intercom dashboard.

Similarly, messages sent from Intercom dashboard by the support team or admin will be sent over to CometChat and received by your end user.

With this, your end users can communicate with each other as well as your Custom support team using the same Chat interface.


# Key Concepts
Source: https://www.cometchat.com/docs/fundamentals/key-concepts

Understand CometChat key concepts including apps, users, UIDs, roles, authentication, groups, messages, calls, and webhooks.

## Dashboard

* The CometChat Dashboard enables you to create new apps (projects) and manage your existing apps.
* Ideally, you should create two apps - one for development and one for production.
* Do not create separate apps for every platform; if you do, your users on different platforms will not be able to communicate with each other!
* For every app, a unique App ID (`appId`) is generated. This `appId` will be required when integrating CometChat within your app.

## Users

* In CometChat, a "user" refers to anyone who utilizes the service for communication.
* Each user is uniquely identified using `uid`.
* The `uid` is typically the primary ID of the user from your database.
* A `uid` can be alphanumeric with underscore (`_`) and hyphen (`-`). Spaces, punctuation and other special characters are not allowed.

### User Roles

* A role is a category for a group of similar users.
* For example, you may want to group your premium users using the role "Premium".
* You then use this to filter users or enable/disable features by writing conditional code.

### User List

* The User List can be used to build the **Contacts** or **Who's Online** view in your app.
* The list of users can be different based on the logged-in user.

## Authentication

* For a user to engage with other users using CometChat, they must be authenticated and logged into CometChat's system, typically after they have logged into your application or website.

* **CometChat does not take care of user management** tasks such as registration and login processes. These aspects must be managed within your own application or website. Once a user is logged into your service, you can then programmatically log them into CometChat, ensuring that users never have to log into CometChat directly.

* Similarly, **CometChat does not manage friendships or contacts** within its platform. If your application requires a feature where users can add each other as friends, this must be handled on your end. After two users have established a mutual friend connection in your application, you can then reflect this relationship within CometChat, linking them as friends in the messaging system.

### Auth workflow

| Your App                      | Your Server                                                                                                   | CometChat                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| User registers in your app    | You store the user information in your database (e.g. ID, name, email, phone, location etc. in `users` table) | You add the user to CometChat (only ID & name) using the Rest API        |
| User logs in to your app      | You verify the credentials, login the user and retrieve the user ID                                           | You log in the user to CometChat using the same user ID programmatically |
| User sends a friend request   | You display the request to the potential friend                                                               | No action required                                                       |
| User accepts a friend request | You display the users as friends                                                                              | You add both the users as friends using the Rest API                     |

### Auth & Rest API Keys

* From the CometChat dashboard, you can generate two types of keys.
* Each key serves a distinct purpose and provides different levels of access to the CometChat platform, ensuring that your application's interaction with CometChat is secure and appropriate permissions are maintained.

| Type         | Privileges                                                       | Recommended Use                               |
| ------------ | ---------------------------------------------------------------- | --------------------------------------------- |
| Auth Key     | The Auth Key can be used to create & login users.                | In your client-side code (during development) |
| Rest API Key | The Rest API Key can be used to perform any CometChat operation. | In your server-side code                      |

### Auth token

* Auth tokens are associated with users in CometChat. A single user can have multiple auth tokens. The auth tokens should be **per user per device**.
* It should be generated by API call ideally, via server to server call. The auth token should then be given to CometChat for login.
* An Auth Token can only be deleted via dashboard or using REST API.

## Groups

* A group in CometChat is a feature that allows multiple users to engage in conversations about specific topics or shared interests. It facilitates collective communication and collaboration among its members.
* Each group is uniquely identified using `guid`.
* The `guid` is typically the primary ID of the group from your database.
* If you do not store group information in your database, you can generate a random string for use as `guid`.
* A `guid` can be alphanumeric with underscore (`_`) and hyphen (`-`). Spaces, punctuation and other special characters are not allowed.

### Group types

CometChat supports three different types of groups.

| Type     | Visibility                   | Participation                                     |
| -------- | ---------------------------- | ------------------------------------------------- |
| Public   | All users                    | Any user can choose to join                       |
| Password | All users                    | Any user with a valid password can choose to join |
| Private  | Only users part of the group | Invited users will be auto-joined                 |

### Group members

* After joining a group on CometChat, a participant is considered a member of that group.
* This membership is ongoing, meaning they will continue to receive messages, calls, and notifications from the group indefinitely.
* If a member no longer wishes to receive these communications, they must actively leave the group or be removed by being kicked out or banned by a group administrator.

CometChat supports three different types of member scopes in a group:

| Member      | Default                                      | Privileges                                                                                                                                                                                                    |
| ----------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Admin       | Group creator is assigned Admin scope        | - Change scope of Group Members to admin, moderator or participant. - Can add members to a group. - Kick & Ban Participants/Moderators/Admins - Send & Receive Messages & Calls - Update group - Delete group |
| Moderator   | A participant can be made a moderator        | - Change scope of moderator or participant. - Update group - Kick & Ban Participants - Send & Receive Messages & Calls                                                                                        |
| Participant | Any other user is assigned Participant scope | - Send & Receive Messages & Calls                                                                                                                                                                             |

## Messaging

<Frame>
  <img />
</Frame>

Every message in CometChat belongs to either one of the five categories:

1. Message
2. Custom
3. Action
4. Call
5. Interactive

Each category can be further be classified into types.

### Message

The category `message` can be used to send messages of the following types:

1. `text` - A plain text message
2. `image`- An image message
3. `video`- A video message
4. `audio`- An audio message
5. `file`- A file message

### Custom

* In the case of messages that belong to the `custom` category, there are no predefined types.
* Custom messages can be used by developers to send messages that do not fit in the default category and types provided by CometChat.
* For messages with the category `custom`, the developers can set their own type to uniquely identify the custom message.
* A very good example of a custom message would be the sharing of location co-ordinates. In this case, the developer can decide to use the custom message with type set to `location`.

### Action

Action messages are system-generated messages. Messages belonging to the `action` category can further be classified into one of the below types:

1. `groupMember` - action performed on a group member.
2. `message` - action performed on a message.

Action messages hold another property called `action` which actually determine the action that has been performed For the type `groupMember` the action can be either one of the below:

1. `joined` - when a group member joins a group
2. `left` - when a group member leaves a group
3. `kicked` - when a group member is kicked from the group
4. `banned` - when a group member is banned from the group
5. `unbanned` - when a group member is unbanned from the group
6. `added` - when a user is added to the group
7. `scopeChanged` - When the scope of a group member is changed.

For the type `message`, the action can be either one of the below:

1. `edited` - when a message is edited.
2. `deleted` - when a message is deleted.

### Call

Messages with the category `call` are Calling related messages. These can belong to either one of the 2 types

1. `audio`
2. `video`

The call messages have a property called status that helps you figure out the status of the call. The status can be either one of the below values:

1. `initiated` - when a is initiated to a user/group
2. `ongoing` - when the receiver of the call has accepted the call
3. `canceled` - when the call has been canceled by the initiator of the call
4. `rejected` - when the call has been rejected by the receiver of the call
5. `unanswered` - when the call was not answered by the receiver.
6. `busy` - when the receiver of the call was busy on another call.
7. `ended` - when the call was successfully completed and ended by either the initiator or receiver.

### Interactive

Messages with the category `interactive` are useful where users can perform some action without leaving the conversation. Interactive messages can be of the following types:

1. `form`
2. `card`
3. `scheduler`
4. `customInteractive`


# Link Preview
Source: https://www.cometchat.com/docs/fundamentals/link-preview

Show link previews in CometChat messages with URL metadata such as title, description, favicon, image, and source URL.

The Link Preview extension will help you show a preview of the web page for every link in your message.

While this extension gives you all the details required for generating a preview, our [Rich Media Preview](/docs/fundamentals/rich-media-preview) gives you a decorated iframe with the styling.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Link Preview extension.

## How does it work?

We provide you a few details about the URL that is in your message. The details are as follows:

1. Description
2. Favicon
3. Image
4. Title
5. URL.

Say, for example, a user shares a Facebook link in their message, then our extension will query the link for the details that you need to build a preview.

These details are provided as part of metadata as shown in the example below:

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    "@injected": {
      "extensions": {
        "link-preview": {
          "links": [
            {
              "description": "Create an account or log into Facebook. Connect with friends, family and other people you know. Share photos and videos, send messages and get updates.",
              "favicon": "https://static.xx.fbcdn.net/rsrc.php/yz/r/KFyVIAWzntM.ico",
              "image": "https://www.facebook.com/images/fb/icon/325x325.png",
              "title": "Facebook - Log In or Sign Up",
              "url": "https://www.facebook.com"
            }
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

If the link-preview key is missing, it means that the extension is either not enabled or has timed out.

Also, it may happen that certain details are missing or the details are not available altogether. Consider switching to Rich Media Preview for better experience.

## Implementation

Using the Link Preview extension, you can build a preview box similar to the one you've seen in Slack.

<Frame>
  <img />
</Frame>

You can fetch the details for the Link Preview using `getMetadata()` method.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    var metadata = message.getMetadata();
    if (metadata != null) {
      var injectedObject = metadata["@injected"];
      if (injectedObject != null && injectedObject.hasOwnProperty("extensions")) {
        var extensionsObject = injectedObject["extensions"];
        if (
          extensionsObject != null &&
          extensionsObject.hasOwnProperty("link-preview")
        ) {
          var linkPreviewObject = extensionsObject["link-preview"];
          var links = linkPreviewObject["links"];
          var description = links[0]["description"];
          var favicon = links[0]["favicon"];
          var image = links[0]["image"];
          var title = links[0]["title"];
          var url = links[0]["url"];
        }
      }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    JSONObject metadata = message.getMetadata();
            if (metadata != null) {
            JSONObject injectedObject = metadata.getJSONObject("@injected");
            if (injectedObject != null && injectedObject.has("extensions")) {
            JSONObject extensionsObject = injectedObject.getJSONObject("extensions");
            if (extensionsObject != null && extensionsObject.has("link-preview")){
              
             JSONObject linkObject = extensionsObject.getJSONObject("link-preview");
             JSONArray linkArray= linkObject.getJSONArray("links");
             JSONObject linkPreviewObject=linkArray.getJSONObject(0);
              if (linkPreviewObject.has("description"))
             String description = linkPreviewObject.getString("description");
              if (linkPreviewObject.has("favicon"))
             String favicon = linkPreviewObject.getString("favicon");
              if (linkPreviewObject.has("image"))
             String image = linkPreviewObject.getString("image");
              if (linkPreviewObject.has("title"))
             String title = linkPreviewObject.getString("title");
              if (linkPreviewObject.has("url"))
             String url = linkPreviewObject.getString("url");

         }
       }
     }
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    if (metadata != null) {
       if (metadata.has("@injected")) {
       val injectedJSONObject = metadata.getJSONObject("@injected")
       if (injectedJSONObject != null && injectedJSONObject.has("extensions")) {
       val extensionsObject = injectedJSONObject.getJSONObject("extensions")
       if (extensionsObject.has("link-preview")) {

           val linkObject = extensionsObject.getJSONObject("link-preview")
           val linksArray = linkObject.getJSONArray("links")
           val linkPreviewObject = linksArray.getJSONObject(0)

           if (linkPreviewObject.has("description")) 
              val description = linkPreviewObject.getString("description")
           if (linkPreviewObject.has("favicon")) 
               val favicon = linkPreviewObject.getString("favicon")
           if (linkPreviewObject.has("image")) 
               val image= linkPreviewObject.getString("image")
           if (linkPreviewObject.has("title")) 
               val title= linkPreviewObject.getString("title")
           if (linkPreviewObject.has("url"))
               val url=  linkPreviewObject.getString("url")                      
            }
          }
       }
     }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    let textMessage = message as? TextMessage

    if let metaData = textMessage.metaData , let injected = metaData["@injected"] as? [String : Any], let cometChatExtension =  injected["extensions"] as? [String : Any], let linkPreviewDictionary = cometChatExtension["link-preview"] as? [String : Any], let linkArray = linkPreviewDictionary["links"] as? [[String: Any]] {

          guard let linkPreview = linkArray[safe: 0] else {
            return
          }

          if let linkTitle = linkPreview["title"] as? String {
              print(linkTitle)
          }

          if let description = linkPreview["description"] as? String {
              print(description)
          }

          if let thumbnail = linkPreview["image"] as? String {
              print(thumbnail)
          }

          if let linkURL = linkPreview["url"] as? String {
              print(linkURL)
          }

          if let favIcon = linkPreview["favicon"] as? String {
              print(favIcon)
          }
    	}
    ```
  </Tab>
</Tabs>

<Warning>
  Links that take more than a second to resolve will be automatically skipped to keep in-flight transit time to a minimum.
</Warning>


# Mentions (Legacy)
Source: https://www.cometchat.com/docs/fundamentals/mentions

Add CometChat mentions with @ user formatting, group member lookup, message rendering, and mention fetch calls.

<Warning>
  **Legacy Notice**: This extension is already included as part of the core messaging experience and is scheduled for deprecation in the near future.

  Please note: Legacy extensions are no longer actively maintained and will not receive feature updates or enhancements.
</Warning>

Mentions are a great way to get someone's attention in a conversation. Mentions start with the @ symbol followed by a name.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Mentions extension.

## How does it work?

### Implement UI logic in your app

Simply enabling the extension will not add the functionality to your apps. The Mentions extension heavily depends on the UI. It should have the following logic already implemented.

1. When `@` symbol is typed in the message composer, show a list of all the users of that group.
2. Insert the selected name from the list in the message composer as `@{Name|UID}`.
3. The message bubbles and the message composer render the `@{Name|UID}` as just `@Name`.

For showing a list of users in a group, you can refer to our [Retrieve Group Members](/docs/sdk/javascript/retrieve-group-members) documentation under the SDK of your choice.

***For example:***

To mention Andrew Joseph with UID `cometchat-uid-1`, the text message should be **Hello @\{Andrew Joseph|cometchat-uid-1}**. However, it should be rendered or formatted as **Hello @Andrew Joseph** in the message composer as well as the message bubbles in the chat.

You have to use third party libraries that make the above mentioned implementation simpler and a rich text editor like [Quill](https://quilljs.com/) or [TinyMCE](https://www.tiny.cloud/tinymce/features/).

### Listing messages with mentions

To get all the messages with mentions for a user, make use of the `callExtension` method provided by CometChat SDK as shown below:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const URL = "v1/fetch";
    CometChat.callExtension('mentions', 'GET', URL, null).then(response => {
        // {messages: []}
    })
    .catch(error => {
        // Error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String URL = "/v1/fetch";

    CometChat.callExtension("mentions", "GET", URL, null,
    new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // {messages: []}
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "mentions", type: .get, endPoint: "v1/fetch", body: nil, onSuccess: { (response) in
            // { messages: [] }
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>


# Message Shortcuts
Source: https://www.cometchat.com/docs/fundamentals/message-shortcuts

Enable CometChat message shortcuts so users can create, fetch, edit, delete, and send predefined messages from shortcuts.

The Message Shortcuts extension enables your users to send each other predefined messages.

For example, **!hb** can be automatically expanded to **Happy birthday!**

<Frame>
  <img />
</Frame>

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Message shortcuts extension.
3. Open the settings for this extension.
4. You should a list of Global Message shortcuts.
5. Edit the existing shortcuts or add new ones.
6. Save your settings.

## How does it work?

The shortcuts saved in the Extension's settings are Global message shortcuts that can be accessed by all the users of your app. The shortcuts saved by users are accessible only to them along with the Global message shortcuts.

With the Message Shortcuts extension, you can:

1. Fetch all shortcuts on your user's device.
2. Allow users to edit, define or delete shortcuts.
3. Send predefined message by typing shortcuts.

## Implementation

### 1. Fetch all shortcuts

Once the user has successfully logged in, you can request the shortcuts from the extension. Additionally, you can provide a button to refresh the shortcuts.

Make use of the `callExtension` method exposed by the CometChat SDK to fetch the shortcuts.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('message-shortcuts', 'GET', 'v1/fetch', null)
    .then(shortcuts => {
     	 // Save these shortcuts locally.
    })
    .catch(error => {
    	// Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    CometChat.callExtension("message-shortcuts", "GET", "/v1/fetch", null,
        new CometChat.CallbackListener<JSONObject>() {
        @Override
        public void onSuccess(JSONObject responseObject) {
            // Shortcuts received here.
        }

        @Override
        public void onError(CometChatException e) {
            // Some error occured.
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "message-shortcuts", type: .get, endPoint: "v1/fetch", body: nil, onSuccess: { (response) in
    	print("Stickers",response)
    }) { (error) in
      print("Error",error?.errorCode, error?.errorDescription)
    }
    ```
  </Tab>
</Tabs>

The response will have the following JSON structure:

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "shortcuts": {
        "!hbd": "Happy Birthday! 🥳",
        "!cu": "See you later.",
        "!ty": "Hey! Thanks a lot! 😊",
        "!wc": "You're welcome!"
      }
    }
    ```
  </Tab>
</Tabs>

### 2. Modify shortcuts

Shortcuts can be added, edited or deleted by your users. You need to have a section in your front-end application that allows the users to do so. The extension accepts a final list of shortcuts after all the modifications have been done by the user.

Make use of the `callExtension` method exposed by the CometChat SDK to submit the final customized list.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const finalList = {
      shortcuts: {
        "!hbd":"Happy birthday! Have fun!"
      }
    };

    CometChat.callExtension('message-shortcuts', 'POST', 'v1/update', finalList)
    .then(response => {
     	 // Updated successfully.
    })
    .catch(error => {
    	// Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject finalList = new JSONObject();
    JSONObject shortcuts = new JSONObject();

    shortcuts.put("!hbd", "Happy birthday! Have fun!");
    shortcuts.put("!ttyl", "Talk to you later");

    finalList.put("shortcuts", shortcuts);

    CometChat.callExtension("message-shortcuts", "POST", "/v1/update", finalList,
     new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            //On Success
        }
        @Override
        public void onError(CometChatException e) {
            //On Failure
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    let finalList = ["shortcuts": ["!hbd": "Happy Birthday!" ,
                "!cu" : "See you later.",
                "!ty", "Hey! Thanks a lot! :blush:",
                "!wc", "You're welcome!"]]
    CometChat.callExtension(slug: "message-shortcuts", type: .post, endPoint: "v1/update", body: finalList, onSuccess: { (response) in
    	// Updated successfully.
    }) { (error) in
    	// Error occured
    }
    ```
  </Tab>
</Tabs>

### 3. Use shortcuts

The UI implementation can be as follows:

1. When `!` is typed in the message composer, a list pops up above the message composer with all the available shortcuts and their predefined values.
2. On typing the next letter after the`!` typed earlier, the list gets filtered with the shortcuts that start with that letter.
3. Clicking on any shortcut from the list, expands the corresponding predefined message in the message composer.


# Message Translation
Source: https://www.cometchat.com/docs/fundamentals/message-translation

Translate CometChat messages into multiple languages so users in multilingual conversations can read messages in their language.

The Message Translation extension helps you translate messages into multiple languages.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Message Translation extension.

## How does it work?

The messages translation extension allows the receivers of the message to translate it in the language of their choice.

In a group of multi-lingual people, a message sent by one of the participants can be in English. However, it can be translated by other members of the group to their languages.

We support translations in the following languages:

| Language              | Language code |
| --------------------- | ------------- |
| Afrikaans             | af            |
| Albanian              | sq            |
| Amharic               | am            |
| Arabic                | ar            |
| Armenian              | hy            |
| Azerbaijani           | az            |
| Bengali               | bn            |
| Bosnian               | bs            |
| Bulgarian             | bg            |
| Catalan               | ca            |
| Chinese (Simplified)  | zh            |
| Chinese (Traditional) | zh-TW         |
| Croatian              | hr            |
| Czech                 | cs            |
| Danish                | da            |
| Dari                  | fa-AF         |
| Dutch                 | nl            |
| English               | en            |
| Estonian              | et            |
| Farsi (Persian)       | fa            |
| Filipino, Tagalog     | tl            |
| Finnish               | fi            |
| French                | fr            |
| French (Canada)       | fr-CA         |
| Georgian              | ka            |
| German                | de            |
| Greek                 | el            |
| Gujarati              | gu            |
| Haitian Creole        | ht            |
| Hausa                 | ha            |
| Hebrew                | he            |
| Hindi                 | hi            |
| Hungarian             | hu            |
| Icelandic             | is            |
| Indonesian            | id            |
| Irish                 | ga            |
| Italian               | it            |
| Japanese              | ja            |
| Kannada               | kn            |
| Kazakh                | kk            |
| Korean                | ko            |
| Latvian               | lv            |
| Lithuanian            | lt            |
| Macedonian            | mk            |
| Malay                 | ms            |
| Malayalam             | ml            |
| Maltese               | mt            |
| Marathi               | mr            |
| Mongolian             | mn            |
| Norwegian (Bokmål)    | no            |
| Pashto                | ps            |
| Polish                | pl            |
| Portuguese (Brazil)   | pt            |
| Portuguese (Portugal) | pt-PT         |
| Punjabi               | pa            |
| Romanian              | ro            |
| Russian               | ru            |
| Serbian               | sr            |
| Sinhala               | si            |
| Slovak                | sk            |
| Slovenian             | sl            |
| Somali                | so            |
| Spanish               | es            |
| Spanish (Mexico)      | es-MX         |
| Swahili               | sw            |
| Swedish               | sv            |
| Tamil                 | ta            |
| Telugu                | te            |
| Thai                  | th            |
| Turkish               | tr            |
| Ukrainian             | uk            |
| Urdu                  | ur            |
| Uzbek                 | uz            |
| Vietnamese            | vi            |
| Welsh                 | cy            |

The language is identified using identifiers from [RFC 5646](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) — if there is a 2-letter ISO 639-1 identifier, with a regional subtag if necessary, it uses that. Otherwise, it uses the ISO 639-2 3-letter code.

## Implementation

The extension uses the `callExtension()` method provided by CometChat SDKs.

The messages will be translated according to the languages specified by the receiver. You can specify the languages for translation as an array. If you pass in an empty array, the language will default to English.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('message-translation', 'POST', 'v2/translate', {
      "msgId": 12,
      "text": "Hey there! How are you?",
      "languages": [ "ru", "hi", "mr" ]
    }).then( result => {
    	// Result of translations
    })
    .catch(error => {
      // Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    JSONArray languages = new JSONArray();

    languages.add("ru");
    languages.add("hi");

    body.put("msgId", 12);
    body.put("languages", languages);
    body.put("text", "Hey there! How are you?");

    CometChat.callExtension("message-translation", "POST", "/v2/translate", body,
     new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // Result of translations
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "message-translation", type: .post, endPoint: "v2/translate", body: ["msgId": 12 ,"languages": ["hi", "ru"], "text": "Hey there! How are you?"] as [String : Any], onSuccess: { (response) in
             // Result of translations
          }) { (error) in
             // Some error occured
          }
    ```
  </Tab>
</Tabs>

The result will be received in the success callback of the `callExtension()` method. It will have the following JSON structure:

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "msgId": 12,
      "translations": [
        {
          "message_translated": "Эй там! Как ты?",
          "language_translated": "ru",
          "error": null,
          "error_description": null
        },
        {
          "message_translated": "अरे वहाँ! आप कैसे हैं?",
          "language_translated": "hi",
          "error": null,
          "error_description": null
        },
        {
          "message_translated": "",
          "language_translated": "mr",
          "error": "UnsupportedLanguagePairException",
          "error_description": "Unsupported language pair: en to mr. Target language 'mr' is not supported"
        }
      ],
        "language_original": "en"
    }
    ```
  </Tab>
</Tabs>

If the source language is not supported for translation, then you will get the following error:

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "code": "ERR_NOT_SUPPORTED",
      "message": "Autodetected source language '<language_code>' is not supported"
    }
    ```
  </Tab>
</Tabs>

### Translating at the sender's end

If the languages of the end-users/receivers are known before hand, this method of implementation can be used.

That is, before your trigger `CometChat.sendMessage` method, make a call to the message translation extension as mentioned above. Since the message has not been sent yet, the `msgId` won't be available and can be skipped in that call.

Once you get the response, make an entry in your message's metadata as shown below:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const messageText = "Hey there! How are you?";

    const metadata = {
      "message-translation": {
        "ru": "Эй там! Как ты?",
        "hi": "अरे वहाँ! आप कैसे हैं?"
      },
    };

    const textMessage = new CometChat.TextMessage(receiverID, messageText, receiverType);
    textMessage.setMetadata(metadata);

    CometChat.sendMessage(textMessage).then(
      message => {
        console.log("Message sent successfully:", message);
      }, error => {
        console.log("Message sending failed with error:", error);
      }
    );
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    private String messageText = "Hey there! How are you?";

    JSONObject metadata = new JSONObject();
    JSONObject translations = new JSONObject();

    try {
    	translations.put("ru", "Эй там! Как ты?");
    	translations.put("hi", "अरे वहाँ! आप कैसे हैं?");
    	metadata.put("message-translation", translations);
    } catch (JSONException je) {
      je.printStackTrace();
    }

    TextMessage textMessage = new TextMessage(receiverID, messageText, receiverType);
    textMessage.setMetadata(metadata);

    CometChat.sendMessage(textMessage, new CometChat.CallbackListener <TextMessage> () {
     @Override
     public void onSuccess(TextMessage textMessage) {
      Log.d(TAG, "Message sent successfully: " + textMessage.toString());
     }
     @Override
     public void onError(CometChatException e) {
      Log.d(TAG, "Message sending failed with exception: " + e.getMessage());
     }
    });
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val messageText:String="Hey there! How are you?"

    val metadataObject:JSONObject=JSONObject("{
      "message-translation": {
        "ru": "Эй там! Как ты?",
        "hi": "अरे वहाँ! आप कैसे हैं?"
      },
    }")

    val textMessage = TextMessage(receiverID, messageText, receiverType)
    textMessage.metadata=metadataObject

    CometChat.sendMessage(textMessage, object : CometChat.CallbackListener<TextMessage>() {
       override fun onSuccess(p0: TextMessage?) {
          Log.d(TAG, "Message sent successfully: " + p0?.toString())               
       }

       override fun onError(p0: CometChatException?) {
          Log.d(TAG, "Message sending failed with exception: " + p0?.message)          }

    })
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    let text = "Hey there! How are you?";

    let translations = ["ru": "Эй там! Как ты?", "hi": "अरे वहाँ! आप कैसे हैं?"];
    let metadata = ["message-translation": translations]

    let textMessage = TextMessage(receiverUid: receiverID, text: text, receiverType: .user)
    textMessage.metaData = metadata;

    CometChat.sendTextMessage(message: textMessage, onSuccess: { (message) in

      print("TextMessage sent successfully. " + message.stringValue())

    }) { (error) in

      print("TextMessage sending failed with error: " + error!.errorDescription);
    }
    ```
  </Tab>
</Tabs>

Then, at the receiver's end, based on the device/browser language, you can show the translated text message in their chats from the metadata.

### Translating at the receiver's end

If the languages of the end-users/receivers are not known before hand, this method of implementation can be used.

Simply show a translate button above every message bubble in the UI. Make a call to the extension as mentioned above. The translation can then be shown in the same message bubble.

However, unlike the translations that are saved in the metadata when translating at the sender's end, these translations are ephemeral and will be lost once the page is reloaded, the user fetches older messages and scrolls back to the latest translated messages or the user switces conversations and comes back to the conversation with translated messages.


# Moderation
Source: https://www.cometchat.com/docs/fundamentals/moderation-extensions

Learn about CometChat moderation options for reviewing messages, managing rules, and handling moderation extensions.

CometChat Moderation features come in two variants:

1. The modern rule based [Moderation](/docs/moderation/overview) platform.

2. The [Legacy Moderation Extensions](https://assets.cometchat.io/legacy-docs/moderation/legacy-extensions.html) based on CometChat Extensions.

For the best experience, we recommend using the rule based [Moderation](/docs/moderation/overview) platform.


# Multi-Tenancy
Source: https://www.cometchat.com/docs/fundamentals/multi-tenancy

Manage multiple isolated CometChat apps under one plan for SaaS, education, white-label, and multi-customer deployments.

Multi-tenancy in CometChat enables you to manage multiple isolated chat environments under a single billing plan, providing economies of scale and streamlined management for applications serving multiple organizations or customer segments.

## Understanding Apps and Multi-Tenancy

### What is a CometChat App?

A CometChat app represents a self-contained chat environment with its own users, groups, messages, roles, and configurations. Each app operates independently with isolated data.

### Multi-App vs Multi-Tenant Setup

**Multi-App Setup**: Create separate CometChat apps with independent billing plans and configurations. Best suited for:

* Different products within an organization
* Separate departments with distinct P\&Ls
* Applications requiring completely independent billing and metrics

**Multi-Tenant Setup**: Create multiple CometChat apps that share quotas and billing from a single base plan. Best suited for:

* SaaS platforms serving multiple customers
* Aggregator applications
* Vertical-specific software (education, healthcare, etc.)

## Authentication

All Management API requests must be authenticated using the key and secret provided when multi-tenancy is enabled for your account. Include these credentials in the request headers:

```
key: YOUR_KEY
secret: YOUR_SECRET
```

## Common Use Cases

Multi-tenancy works well for scenarios like:

* **Education platforms**: Each school operates as a separate app, with teachers, students, and parents communicating within their school's isolated environment
* **Business communication tools**: Each business or franchise gets its own app, keeping employee and customer conversations separate
* **White-label solutions**: Provide branded chat experiences to multiple clients while managing everything from a single account

## How Multi-Tenancy Works

When multi-tenancy is enabled for your account:

1. A **base app** is created and associated with your billing plan
2. All additional apps created in the account consume from the base app's quotas (MAU, PCC, Voice/Video minutes)
3. Usage across all apps is pooled and billed together through the base app
4. All apps inherit features and configurations from the base plan

## App Management APIs

Once multi-tenancy is enabled, you receive App Management credentials (key and secret) that allow you to programmatically:

* Create and configure new apps
* Enable/disable extensions
* Manage app team members
* Configure webhooks
* Manage widgets

This enables automation and "configuration as code" patterns for managing large numbers of apps consistently.

## Getting Started

To enable multi-tenancy for your account, [contact our support team](https://www.cometchat.com/contact-sales). Once approved, you'll receive your App Management key and secret, and can begin creating tenant apps.

For detailed API documentation on managing apps programmatically, refer to the [Management REST APIs](/docs/rest-api/management-apis).


# Notifications
Source: https://www.cometchat.com/docs/fundamentals/notification-extensions

Explore CometChat notification options for push, email, and SMS, including platform notifications and notification extensions.

CometChat Notifications come in two variants:

1. The mordern [Notifications](/docs/notifications/overview) platform.

   * [Push Notifications](/docs/notifications/push-overview)
   * [Email Notifications](/docs/notifications/email-overview)
   * [SMS Notification](/docs/notifications/sms-overview)

2. The Legacy Notification Extensions based on CometChat Extensions.

   * [Legacy Push Notifications Extension](https://assets.cometchat.io/legacy-docs/notifications/push-notifications-extension-legacy.html)
   * [Legacy Email Notifications Extension](https://assets.cometchat.io/legacy-docs/notifications/email-notifications-extension-legacy.html)
   * [Legacy SMS Notifications Extension](https://assets.cometchat.io/legacy-docs/notifications/sms-notifications-extension-legacy.html)

For the best experience, we recommend to use the mordern [Notifications](/docs/notifications/overview) platform. Please visit the above mentioned links for more details.


# What Is CometChat?
Source: https://www.cometchat.com/docs/fundamentals/overview

Overview of What Is CometChat? in CometChat.

CometChat is a comprehensive communications platform that empowers businesses to seamlessly integrate real-time chat, voice and video calling functionalities. These integrations can be done picking up the implementation methods that align best with your goals.

Our **Messaging & chat** features offer flexible, secure, feature-rich and easy-to-manage integrations for your web and mobile apps. With **Voice & video calling** features, you get enterprise-grade security, robust infrastructure and a familiar UI from the same vendor as your chat solution.

## Solutions for every industry

CometChat's solutions cater to every industry with a global and scalable infrastructure, multi-region capabilities, multi-tenancy, and round-the-clock support. Our comprehensive documentation, competitive pricing, and flexible implementation options ensure that our platform is equipped for enterprise-grade requirements while remaining accessible for startups.

This dual readiness positions CometChat as both **Enterprise-ready** and **Startup-friendly**.

Our customer base spans a diverse range of industries, including:

* Online marketplaces
* Healthcare
* Dating
* Events & streaming
* Online education
* Community & Social
* Sports & Gaming
* Team Comms & Workflows
* SaaS Businesses

## Integrate in minutes

With a few lines of code, you can have CometChat integrated into any app written in React, iOS, Android, Flutter and 12+ other languages.

**Future proof your chat roadmap** by implementing chat quickly and efficiently with minimal risk. Our UI kits, APIs empower you to focus on growing your business while we handle the technical aspects.

**Partner with subject matter experts** and master the art of real-time engagement with CometChat. Our expertise in messaging, chat, and calling empowers you to offer the best in-app chat experience.

**Complete customizability & extensions** empowers you to personalize user experience, leverage data from other systems, connect chat to your core business logic with webhooks, extensions & integrations.

## Build with tools of your choice

### No-code widget

Simply copy and paste a few lines of code to add text, voice, and video to your web app in minutes.

### Low-code UI Kits

Reduce your time to market and give your users the modern chat experience they expect with UI kits.

### SDKs & APIs

Fully customizable and easy to use? Yes, it's possible, with our SDKs and APIs for in-app messaging and voice & video calling.

## Compliances

Choosing CometChat is your assurance of a meticulously vetted and highly secure solution. We deeply appreciate and obsess over the significance of both security and compliance.

CometChat is fully compliant with the following security standards:

* **HIPAA + BAA**: CometChat is compliant with HIPAA rules and standards and can enter into a BAA.
* **PIPEDA**: CometChat is compliant with PIPEDA and follows the Fair Information Principles.
* **GDPR**: CometChat meets all requirements of GDPR and provides special APIs to enable customers to maintain compliance.
* **ISO 27001**: CometChat is certified compliant with the ISO 27001 standards.
* **SOC 2 Type 2**: CometChat is certified compliant with SOC 2’s five Trust Service Principles of security, availability, privacy, confidentiality, and processing integrity.

## Features

### Messaging & chat

| Core messaging           | Advanced messaging     | Engagement                    |
| ------------------------ | ---------------------- | ----------------------------- |
| One-on-one private chat  | Threaded conversations | Mentions                      |
| Group text messaging     | Message replies        | Stickers & GIFs               |
| Share files & multimedia | Message translation    | Collaborative whiteboard      |
| Typing indicators        | Smart Replies          | Collaborative document        |
| Users & friends list     | Chat history           | Polls                         |
| Users & friends presence | Custom messages        | Mentions count                |
| Read receipts            | Pin message            | User profile avatars          |
| Delivery receipts        | Save message           | Reminders                     |
| Audio messages           | Rich media preview     | Reactions                     |
| Unread message count     | URL shorteners         | Push notifications            |
| Users search             | Thumbnail generation   | Email notifications & replies |
| Messages search          | Message shortcuts      | SMS notifications             |
|                          | Voice transcription    | Email replies                 |
|                          | Broadcast message      |                               |

| Moderation                   | Administration & Security         | Integrations & webhooks |
| ---------------------------- | --------------------------------- | ----------------------- |
| In-flight message moderation | Analytics                         | Analytics & usage API   |
| Image moderation             | Dashboard team management         | Rest APIs               |
| Profanity filter             | Custom metadata                   | Before message webhook  |
| Data masking                 | Cross-platform sync               | After message webhook   |
| XSS Filter                   | User & group management           | Intercom                |
| User-to-user blocking        | Encryption                        | SendGrid                |
| Moderation dashboard         | Multi-device support              | Chatwoot                |
| Human moderators             | Historical data import API        | Virgil security         |
| Report user                  | Live data migration               | App management API      |
| Kick/ban users               | Data export                       | App creation API        |
| Report message               | ISO 27001                         | Presence webhook        |
| Virus & malware scanner      | SOC 2                             | Read receipt            |
| Sentiment analysis           | GDPR API                          | Delivery receipt        |
|                              | HIPPA w/ BAA                      |                         |
|                              | Encryption in transit (TLS/SSL)   |                         |
|                              | Encryption at rest (AES 256)      |                         |
|                              | Role-based access control         |                         |
|                              | Disappearing messages             |                         |
|                              | End-to-end encryption             |                         |
|                              | End-user API endpoint restriction |                         |

### Voice & video calling

| Calling essentials            | Advanced calling features | Administration            |
| ----------------------------- | ------------------------- | ------------------------- |
| 1-to-1 calling                | Video broadcasting        | Analytics & usage API     |
| Group calling                 | Call recording            | Rest APIs                 |
| Multi-device support          | Interactive whiteboard    | Dashboard analytics       |
| Conference calls              | Interactive document      | Call logs                 |
| Personal meeting rooms        | Picture-in-picture        | Customizable call screens |
| Mobile calling                | Screen sharing            | SRTP encryption           |
| Push notifications            | In-call messaging         | Pushkit & callkit support |
| Grid tile & spotlight layouts |                           | App management API        |

### CometChat AI

| Insights AI        | Conversational AI                    | Moderation AI       |
| ------------------ | ------------------------------------ | ------------------- |
| AI Funnel Insights | Conversation Starter & Smart Replies | Content Moderation  |
| AI User Insights   | Conversation Summaries               | AI Image Moderation |
| AI Entity Insights | AI Bots                              | Mute Suggestions    |

## Moving forward

Next, have a look at the Implementation checklist to quickly integrate chat functionality into your app and prepare for a successful launch.


# Pin Message
Source: https://www.cometchat.com/docs/fundamentals/pin-message

Pin, unpin, and fetch pinned CometChat messages in one-on-one or group conversations using the Pin Message extension.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Pin message extension.

## How does it work?

Pin message extension provides you the ability to:

1. Pin messages
2. Unpin messages
3. Fetch all the pinned messages for a conversation.

Messages pinned in a conversation (be it one-on-one or group) are visible to the receiver(s) as well.

### 1. Pin a message

To pin a message, use the `callExtension` method provided by the SDK to make an HTTP POST request with the parameters as shown below. You need to pass the `msgId` that has to be pinned.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('pin-message', 'POST', 'v1/pin', {
        "msgId": 280 // The ID of the message to be pinned. Here 280.
    }).then(response => {
        // { success: true }
    })
    .catch(error => {
        // Error occurred
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("msgId", 280);

    CometChat.callExtension("pin-message", "POST", "/v1/pin", body,
     new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            //On Success
        }
        @Override
        public void onError(CometChatException e) {
            //On Failure
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "pin-message", type: .post, endPoint: "v1/pin", body: ["msgId": 280] as [String : Any], onSuccess: { (response) in
             // Success
          }) { (error) in
             // Error occured
          }
    ```
  </Tab>
</Tabs>

### 2. Unpin a message

To unpin a message, use the `callExtension` method provided by the SDK to make an HTTP DELETE request with the parameters as shown below. You need to pass the `msgId`, `receiverType` and the `receiver` (can be either UID or GUID based on `receiverType`).

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('pin-message', 'DELETE', 'v1/unpin', {
        "msgId": 111,
        "receiverType": "group",
        "receiver": "cometchat-guid-1"
    }).then(response => {
        // { success: true }
    })
    .catch(error => {
        // Error occurred
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("msgId", 111);
    body.put("receiverType", "group");
    body.put("receiver", "cometchat-guid-1");

    CometChat.callExtension("pin-message", "DELETE", "/v1/unpin", body,
     new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            //On Success
        }
        @Override
        public void onError(CometChatException e) {
            //On Failure
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "pin-message", type: .delete, endPoint: "v1/unpin", body: ["msgId": 111, "receiverType": "group", "receiver": "cometchat-guid-1"] as [String : Any], onSuccess: { (response) in
             // Success
          }) { (error) in
             // Error occured
          }
    ```
  </Tab>
</Tabs>

### 3. Fetch pinned messages

To fetch the pinned messages for a conversation, use the `callExtension` method provided by the SDK to make an HTTP GET request with the query parameters as shown below. You need to pass the `receiverType` and the `receiver` (can be either UID or GUID based on `receiverType`).

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const URL = `v1/fetch?receiverType=${RECEIVER_TYPE}&receiver=${RECEIVER}`;
    CometChat.callExtension('pin-message', 'GET', URL, null).then(response => {
        // {pinnedMessages: []}
    })
    .catch(error => {
        // Error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String URL = "/v1/fetch?receiverType=" + RECEIVER_TYPE + "&receiver=" + RECEIVER;

    CometChat.callExtension("pin-message", "GET", URL, null,
    new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // {pinnedMessages: []}
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "pin-message", type: .get, endPoint: "v1/fetch?receiverType=\(RECEIVER_TYPE)&receiver=\(RECEIVER)", body: nil, onSuccess: { (response) in
            // {pinnedMessages: []}
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>


# Polls
Source: https://www.cometchat.com/docs/fundamentals/polls

Create CometChat polls in conversations, collect votes from users, fetch poll results, and manage poll options.

Polls let you quickly record the opinions directly in the Conversations and also view the results.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Polls extension.

## How do polls work?

Polls extension has the following 3 parts:

1. Creating a poll by submitting a question along with the possible options.
2. Voting in a poll.
3. Fetching the results for a particular poll.

## 1. Creating a Poll

In order to create a poll, you need to submit the following details:

1. Question
2. Array of options
3. Receiver (UID/GUID)
4. Receiver type (user/group)

The options in the array are assigned an index appropriately (starting from 1). You can create a poll by using `callExtension` method provided by our SDKs:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('polls', 'POST', 'v2/create', {
        "question": "Which OS do you use?",
        "options": ["Windows", "Ubuntu", "MacOS", "Other"],
        "receiver": "cometchat-uid-1",
        "receiverType": "user"
    }).then(response => {
        // Details about the created poll
    })
    .catch(error => {
        // Error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    JSONArray options = new JSONArray();

    options.add("Milk");
    options.add("Cereal");

    body.put("question", "Milk goes first or the cereal?");
    body.put("options", options);
    body.put("receiver", "cometchat-guid-1");
    body.put("receiverType", "group");

    CometChat.callExtension("polls", "POST", "/v2/create", body,
     new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            //On Success
        }
        @Override
        public void onError(CometChatException e) {
            //On Failure
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "polls", type: .post, endPoint: "v2/create", body: ["question": "Which OS do you use?" ,"options":["Windows", "Ubuntu", "MacOS", "Other"],"receiver":"cometchat-uid-1","receiverType":"user"] as [String : Any], onSuccess: { (response) in
             // Details about the created poll
          }) { (error) in
             // Error occured
          }
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

## 2. Receiving a poll

Polls are custom messages. So, you have to implement our `onCustomMessageReceived` listener in order to receive the Poll-related message. Please refer to our [Receive Messages](/docs/sdk/javascript/receive-message) documentation under the SDK of your choice.

The `metadata` stores all the information about the poll. You will find the following details in `metadata` -> `@injected` -> `extensions` -> `polls`.

| Key      | Value                                                                                |
| -------- | ------------------------------------------------------------------------------------ |
| id       | A String representing a unique ID for the poll.                                      |
| options  | An Object with the option number as the key and the option description as the value. |
| question | A string representing the question asked in the poll.                                |
| results  | An object that stores voting results.                                                |

Apart from the above Poll-related details, the `metadata` will also contain `incrementUnreadCount` with value as `true`. This will be useful for incrementing the unread count every time a poll is received.

## 3. Voting in a poll

Voting in a poll simply requires you to provide the `id` of the poll and the option you intend to vote for. The `vote` parameter is basically the option number.

You can allow users to vote for a poll by using the `callExtension` method provided by our SDKs:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('polls', 'POST', 'v2/vote', {
        vote: "3",
        id: "d5441d53-c191-4696-9e92-e4d79da7463",
    }).then(response => {
        // Successfully voted
    })
    .catch(error => {
        // Error Occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("vote", OPTION_NUMBER);
    body.put("id", POLL_ID);

    CometChat.callExtension("polls", "POST", "/v2/vote", body,
     new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // Voted successfully
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "polls", type: .post, endPoint: "v2/vote", body: ["vote": "3","id": "d5441d53-c191-4696-9e92-e4d79da7463"], onSuccess: { (response) in
            // Successfully voted
          }) { (error) in
            // Error Occured
          }
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## 4. Getting Results

There are 2 ways to fetch the results of the poll:

1. Real-time updates from the `metadata`
2. Fetch the results by using the `callExtension` method.

### Real-time updates

As mentioned earlier, a Poll is a message of the category: `custom`. When the votes are cast by the users, the metadata for the message will be updated accordingly. To get real-time voting information, you need to implement the `onMessageEdited` listener. Please check our [Edit message](/docs/sdk/javascript/edit-message) documentation under the SDK of your choice.

The updated details will be available in the metadata of the message. Here is a sample response:

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    "@injected": {
        "extensions": {
            "polls": {
                "id": "d5441d53-c191-4696-9e92-e4d79da7463",
                "options": {
                    "1": "Chicken",
                    "2": "The Egg"
                },
                "results": {
                    "total": 2,
                    "options": {
                        "1": {
                            "text": "Chicken",
                            "count": 1,
                            "voters": {
                                "cometchat-uid-1": {
                                    "name": "Andrew Joseph",
                                    "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"
                                }
                            }
                        },
                        "2": {
                            "text": "The Egg",
                            "count": 1,
                            "voters": {
                                "cometchat-uid-2": {
                                    "name": "George Alan",
                                    "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"
                                }
                            }
                        }
                    }
                },
                "question": "Which came first? The chicken or the egg?"
            }
        }
    }
    ```
  </Tab>
</Tabs>

### Using callExtension() method

For fetching results, the only parameter required is the id of the poll. You can use this method only when you are the creator of the poll. Others cannot call this method to get the poll results. Result for a poll can be fetched using a `callExtension` method provided by our SDKs:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('polls', 'GET', 'v2/results?id='+POLL_ID, null)
    .then(results => {
    	// Poll results
    })
    .catch(error => {
    	// Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String URL = "/v2/results?id=" + POLL_ID;

    CometChat.callExtension("polls", "GET", URL, null,
    new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // Poll results
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "polls", type: .get, endPoint: "v2/results?id=\(POLL_ID)", body: nil, onSuccess: { (response) in
            // Poll results
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>

A sample response for the results is as follows:

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    "polls": {
        "id": "d5441d53-c191-4696-9e92-e4d79da7463",
        "options": {
            "1": "Chicken",
            "2": "The Egg"
        },
        "results": {
            "total": 2,
            "options": {
                "1": {
                    "text": "Chicken",
                    "count": 1,
                    "voters": {
                        "cometchat-uid-1": {
                            "name": "Andrew Joseph",
                            "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"
                        }
                    }
                },
                "2": {
                    "text": "The Egg",
                    "count": 1,
                    "voters": {
                        "cometchat-uid-2": {
                            "name": "George Alan",
                            "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"
                        }
                    }
                }
            }
        },
        "question": "Which came first? The chicken or the egg?"
    }
    ```
  </Tab>
</Tabs>

## Notifications

<Card title="Notification templates" href="/notifications/templates-and-sounds#6-poll-message-templates">
  Customize the push, email, and SMS notification templates for poll messages.
</Card>


# Pre-Signed URLs
Source: https://www.cometchat.com/docs/fundamentals/presigned-urls

Secure CometChat media files with pre-signed URLs, expiry settings, signed access, and configurable TTL.

CometChat generates **pre-signed URLs** for all media files, including images, audio, video, and documents shared in chat. A pre-signed URL embeds a cryptographic signature and an expiry timestamp directly in the URL, so files are accessible only within a defined time window without requiring API credentials on the client side.

This feature is enabled by default for all newly created apps. Existing apps can opt in from the CometChat dashboard.

***

## How It Works

When a media file is sent or retrieved, CometChat returns a pre-signed URL in the following format:

```
https://media-<REGION>.cometchat.io/<APP_ID>/media/<filename>?Expires=<unix_timestamp>&Signature=<signature>&Key-Pair-Id=<key_pair_id>
```

| Parameter     | Description                                              |
| ------------- | -------------------------------------------------------- |
| `Expires`     | Unix timestamp after which the URL is no longer valid    |
| `Signature`   | Cryptographic signature that validates the URL integrity |
| `Key-Pair-Id` | Identifier for the signing key pair used by CometChat    |

Pre-signed URLs are returned across all surfaces - SDK responses, REST API, and webhook payloads.

***

## Configuring the TTL

The TTL (Time-to-Live) controls how long a generated pre-signed URL remains valid.

| Setting | Value      |
| ------- | ---------- |
| Minimum | 15 minutes |
| Maximum | 1 month    |
| Default | 1 day      |

To configure the TTL:

1. Go to the [CometChat Dashboard](https://app.cometchat.com/apps).
2. Select your app and navigate to **Chat & Messaging** → **Settings**.
3. Under **Pre-Signed URLs**, set your desired TTL value.
4. Save your changes.

<Frame>
  <img alt="Pre-Signed URL TTL configuration in CometChat Dashboard" />
</Frame>

<Note>
  TTL configuration is available on all plans. Changes take effect for all new pre-signed URLs generated after saving; existing URLs retain their original expiry.
</Note>

***


# Reactions (Legacy)
Source: https://www.cometchat.com/docs/fundamentals/reactions

Add, remove, and fetch CometChat message reactions with emoji metadata and reaction extension calls.

<Warning>
  **Legacy Notice**: This extension is already included as part of the core messaging experience and is scheduled for deprecation in the near future.

  Please note: Legacy extensions are no longer actively maintained and will not receive feature updates or enhancements.
</Warning>

Reactions are the ability to react to an individual message with a specific emotion, quickly showing acknowledgment or expressing how you feel in a lightweight way.

<Frame>
  <img />
</Frame>

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Reactions extension.

## How do reactions work?

A user can react to a message using multiple emojis.

To allow a user to react to a message, show a popup with all the available emojis. Once the user clicks on a particular emoji, add that emoji as a reaction to the target message.

If a user has reacted to a message using a certain emoji and clicks on the same emoji, remove it from the target message.

Sending Reactions

To add a reaction using selected emoji, use the `callExtension` method provided by our SDKs as follows:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('reactions', 'POST', 'v1/react', {
      msgId: MESSAGE_ID,
      emoji: "😊"
    }).then(response => {
      // Reaction added successfully
    }).catch(error => {
      // Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("msgId", ID_OF_THE_MESSAGE);
    body.put("emoji", "😊");

    CometChat.callExtension("reactions", "POST", "/v1/react", body,
     new CometChat.CallbackListener<JSONObject>() {
        @Override
        public void onSuccess(JSONObject responseObject) {
            // Reaction added successfully.
        }

        @Override
        public void onError(CometChatException e) {
           // Some error occured.
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "reactions", type: .post, endPoint: "v1/react", body: ["msgId":MESSAGE_ID, "emoji":"😊"], onSuccess: { (response) in
             // Reaction added successfully
          }) { (error) in
            // Some error occured
          }
    ```
  </Tab>
</Tabs>

## Receiving Reactions

The messages will be updated later with Reactions as and when users react to them. Hence, you need to implement the `onMessageEdited` listener. Please check our [Edit message](/docs/sdk/javascript/edit-message) documentation under the SDK of your choice.

The updated details will be available in the metadata of the message. Here is a sample response:

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    "@injected": {
      "extensions": {
        "reactions": {
          "😊": {
            "cometchat-uid-2": {
              "name": "George Alan",
              "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"
            },
            "cometchat-uid-1": {
              "name": "Andrew Joseph",
              "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"
            },
          },
          "👍": {
            "cometchat-uid-3": {
              "name": "George Alan",
            }
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Implementation

At the recipients' end, from the message object, you can fetch the metadata by calling the getMetadata() method. Using this metadata, you can fetch the reaction details for that message.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    var metadata = message.getMetadata();
    if (metadata != null) {
      var injectedObject = metadata["@injected"];
      if (injectedObject != null && injectedObject.hasOwnProperty("extensions")) {
        var extensionsObject = injectedObject["extensions"];
        if (
          extensionsObject != null &&
          extensionsObject.hasOwnProperty("reactions")
        ) {
          var reactionsObject = extensionsObject["reactions"];
        }
      }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    JSONObject metadata = message.getMetadata();
    if (metadata != null) {
      JSONObject injectedObject = metadata.getJSONObject("@injected");
      if (injectedObject != null && injectedObject.has("extensions")) {
        JSONObject extensionsObject = injectedObject.getJSONObject("extensions");
        if (extensionsObject != null && extensionsObject.has("reactions")) {
              JSONObject reactionsObject = extensionsObject.getJSONObject("reactions");
            }
        }
    }
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    if (metadata != null) {
      if (metadata.has("@injected")) {
        val injectedJSONObject = metadata.getJSONObject("@injected")
          if (injectedJSONObject != null && injectedJSONObject.has("extensions")) {
          val extensionsObject = injectedJSONObject.getJSONObject("extensions")
              if (extensionsObject != null && extensionsObject.has("reactions")) {
              val reactionsObject = extensionsObject.getJSONObject("reactions")
            }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    let textMessage = message as? TextMessage
    var metadata : [String : Any]? = textMessage.metaData
    if metadata != nil {
        var injectedObject : [String : Any]? = (metadata?["@injected"] as? [String : Any])!
        if injectedObject != nil && (injectedObject!["extensions"] != nil) {
          var extensionsObject : [String : Any]? = injectedObject?["extensions"] as? [String : Any]

          if extensionsObject != nil && extensionsObject?["reactions"] != nil {
            var reactionsObject = extensionsObject?["reactions"] as! [String :  Any]
          }
       }
    }
    ```
  </Tab>
</Tabs>


# Reminders
Source: https://www.cometchat.com/docs/fundamentals/reminders

Create, list, edit, and delete CometChat reminders for messages or custom notes using the reminders bot.

Create reminders for messages or anything else.

<Frame>
  <img />
</Frame>

## Extension Settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Reminders extension.
3. Go to the Users section and create a new user with `cc_reminder_bot` as the UID. The name and Avatar can be of your choice.

<Note>
  The `cc_reminder_bot` user should be available for your app in order to use the Reminders extension. There shouldn't be an existing user using the same `UID`.
</Note>

## How do reminders work?

<Frame>
  <img />
</Frame>

Users can choose to be reminded about a message from a conversation or set some sort of custom personalized reminder.

When the reminder is due, `cc_reminder_bot` will send a message to the user.

Users can then list, edit or delete reminders.

### Set reminders

The following parameters are required for setting a reminder

| Parameter  | Value          | Description                                                                               |
| ---------- | -------------- | ----------------------------------------------------------------------------------------- |
| `about`    | Integer/String | `Integer` => For setting a message reminder. `String` => For setting a personal reminder. |
| `isCustom` | Boolean        | `false` => For setting a message reminder. `true` => For setting a personal reminder.     |
| `timeInMS` | Integer        | Unix timestamp: (e.g.: `1638351344989`)                                                   |

#### Message reminders

To set Message reminders, the `about` should be an integer corresponding to the message id. The `isCustom` value should be set to`false`.

In order to set the reminders, use the `CometChat.callExtension` method as shown below:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('reminders', 'POST', 'v1/reminder', {
      about: 1,
      isCustom: false,
      timeInMS: 1638351344989
    }).then(response => {
      // Reminder created successfully
      // Reminder details with reminderId.
    }).catch(error => {
      // Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("about", ID_OF_THE_MESSAGE);
    body.put("isCustom", false);
    body.put("timeInMS", 1638351344989);

    CometChat.callExtension("reminders", "POST", "/v1/reminder", body,
    	new CometChat.CallbackListener<JSONObject>() {
        @Override
        public void onSuccess(JSONObject responseObject) {
            // Reminder created successfully.
          	// Reminder details with reminderId.
        }

        @Override
        public void onError(CometChatException e) {
          	// Some error occured.
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "reminders", type: .post, endPoint: "v1/reminder", body: ["about":MESSAGE_ID, "isCustom":false, "timeInMS": 1638351344989], onSuccess: { (response) in
             // Reminder created successfully.
             // Reminder details with reminderId.
          }) { (error) in
            // Some error occured
          }
    ```
  </Tab>
</Tabs>

#### Personal reminders

To set Personal reminders, the about can contain the description. The `isCustom` value should be set to`true`.

In order to set the reminders, use the `CometChat.callExtension` method as shown below:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('reminders', 'POST', 'v1/reminder', {
      about: "Drinking water",
      isCustom: true,
      timeInMS: 1638351344989
    }).then(response => {
      // Reminder created successfully
      // Reminder details with reminderId.
    }).catch(error => {
      // Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("about", "Drinking water");
    body.put("isCustom", true);
    body.put("timeInMS", 1638351344989);

    CometChat.callExtension("reminders", "POST", "/v1/reminder", body,
    	new CometChat.CallbackListener<JSONObject>() {
        @Override
        public void onSuccess(JSONObject responseObject) {
            // Reminder created successfully.
          	// Reminder details with reminderId.
        }

        @Override
        public void onError(CometChatException e) {
          	// Some error occured.
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "reminders", type: .post, endPoint: "v1/reminder", body: ["about":"Drinking water", "isCustom":true, "timeInMS": 1638351344989], onSuccess: { (response) in
             // Reminder created successfully.
             // Reminder details with reminderId.
          }) { (error) in
            // Some error occured
          }
    ```
  </Tab>
</Tabs>

If the reminder has been created successfully, you will receive the reminder object with `reminderId` in the success response.

### List reminders

List the reminders set by a user using the `CometChat.callExtension` method as shown below:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('reminders', 'GET', 'v1/fetch', null).then(response => {
      // reminders array
    }).catch(error => {
      // Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    CometChat.callExtension("reminders", "GET", "/v1/fetch", null,
    	new CometChat.CallbackListener<JSONObject>() {
        @Override
        public void onSuccess(JSONObject responseObject) {
            // reminders array
        }

        @Override
        public void onError(CometChatException e) {
          	// Some error occured.
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "reminders", type: .get, endPoint: "v1/fetch", body: nil, onSuccess: { (response) in
             // reminders array
          }) { (error) in
            // Some error occured
          }
    ```
  </Tab>
</Tabs>

### Delete reminders

Reminders can be deleted using the `reminderId` as shown below:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('reminders', 'DELETE', 'v1/reminder', {
      reminderId: "e9cda52a-3839-4fd5-a010-b70db136f0f1"
    }).then(response => {
      // Reminder deleted successfully
    }).catch(error => {
      // Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;
    JSONObject body = new JSONObject();
    body.put("reminderId", "e9cda52a-3839-4fd5-a010-b70db136f0f1");

    CometChat.callExtension("reminders", "DELETE", "/v1/reminder", body,
    	new CometChat.CallbackListener<JSONObject>() {
        @Override
        public void onSuccess(JSONObject responseObject) {
            // Reminder deleted successfully
        }

        @Override
        public void onError(CometChatException e) {
          	// Some error occured.
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "reminders", type: .delete, endPoint: "v1/reminder", body: ["reminderId": "e9cda52a-3839-4fd5-a010-b70db136f0f1"], onSuccess: { (response) in
             // Reminder deleted successfully
          }) { (error) in
            // Some error occured
          }
    ```
  </Tab>
</Tabs>

### Edit reminders

In case a reminder needs to be preponed or postponed, it can be done using the Edit reminders functionality. The following updates the reminder with `reminderId: "e9cda52a-3839-4fd5-a010-b70db136f0f1"`

For editing, use the `CometChat.callExtension` method as shown below:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('reminders', 'PUT', 'v1/reminder', {
      reminderId: "e9cda52a-3839-4fd5-a010-b70db136f0f1",
      about: 1,
      isCustom: false,
      timeInMS: 1638351344999
    }).then(response => {
      // Reminder updated successfully.
    }).catch(error => {
      // Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("about", ID_OF_THE_MESSAGE);
    body.put("isCustom", false);
    body.put("timeInMS", 1638351344989);

    CometChat.callExtension("reminders", "PUT", "/v1/reminder", body,
    	new CometChat.CallbackListener<JSONObject>() {
        @Override
        public void onSuccess(JSONObject responseObject) {
            // Reminder updated successfully.
        }

        @Override
        public void onError(CometChatException e) {
          	// Some error occured.
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "reminders", type: .put, endPoint: "v1/reminder", body: ["about":MESSAGE_ID, "isCustom":false, "timeInMS": 1638351344989], onSuccess: { (response) in
             // Reminder updated successfully.
          }) { (error) in
            // Some error occured
          }
    ```
  </Tab>
</Tabs>

<Note>
  For Message reminders, `timeInMS` can be updated.\
  For Personal reminders, `timeInMS` & `about` can be updated.
</Note>

### Receive reminders

The user will receive reminders from a special user - `cc_reminder_bot` - that was configured before.

These reminders are sent as messages with `category: custom` and `type: extension_reminders`. The `customData` object will have an `about` field that the user had mentioned while setting the reminder.

Learn more about [Custom messages listener](/docs/sdk/javascript/receive-message#real-time-messages) for receiving reminders.

## Notifications

<Card title="Notification templates" href="/notifications/templates-and-sounds#7-reminder-message-templates">
  Customize the push, email, and SMS notification templates for reminder messages.
</Card>


# Rich Media Preview
Source: https://www.cometchat.com/docs/fundamentals/rich-media-preview

Generate rich previews for links in CometChat messages with Iframely metadata, thumbnails, titles, and descriptions.

The Rich Media Preview Extension allows the developer to generate rich preview panels for all the popular sites. This extension fetches the first URL from the message for the generation of a preview.

## Before you begin

1. Sign up with [Iframely](https://iframely.com/embed).
2. Get their API key to configure the extension.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Rich Media Preview extension.
3. Open the Settings for this extension.
4. Enter the iFramely API Key.
5. Save your settings.

## How does it work?

If the text message contains a URL, the extension will create a Preview using your iFramely credentials. These details can then be used to show a nice preview card for that URL.

The information about the Preview will be updated later for the message and hence you need to implement the `onMessageEdited` listener. Please check our [Edit message](/docs/sdk/javascript/edit-message) documentation under the SDK of your choice.

Here is a sample response (for [https://stackoverflow.com](https://stackoverflow.com)):

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    "@injected": {
      "extensions": {
        "rich-media": {
          "url": "https://stackoverflow.com",
            "meta": {
            "description": "Stack Overflow | The World’s Largest Online Community for Developers",
              "title": "Stack Overflow - Where Developers Learn, Share, & Build Careers",
                "canonical": "https://stackoverflow.com/",
                  "site": "Stack Overflow"
          },
          "links": {
            "thumbnail": [
              {
                "href": "https://cdn.sstatic.net/Sites/stackoverflow/Img/apple-touch-icon@2.png?v=73d79a89bded",
                "type": "image/png",
                "rel": [
                  "thumbnail",
                  "og",
                  "ssl"
                ],
                "content_length": 6562,
                "media": {
                  "width": 316,
                  "height": 316
                }
              },
              {
                "href": "https://cdn.sstatic.net/Sites/stackoverflow/Img/apple-touch-icon.png?v=c78bd457575a",
                "rel": [
                  "thumbnail",
                  "ssl",
                  "apple-touch-icon",
                  "icon"
                ],
                "type": "image/png"
              }
            ],
              "icon": [
                {
                  "href": "https://cdn.sstatic.net/Sites/stackoverflow/Img/apple-touch-icon.png?v=c78bd457575a",
                  "rel": [
                    "thumbnail",
                    "ssl",
                    "apple-touch-icon",
                    "icon"
                  ],
                  "type": "image/png"
                },
                {
                  "href": "https://cdn.sstatic.net/Sites/stackoverflow/Img/favicon.ico?v=ec617d715196",
                  "rel": [
                    "shortcut",
                    "icon",
                    "ssl"
                  ],
                  "type": "image/icon"
                }
              ]
          },
          "rel": [
            "summary",
            "ssl",
            "html5",
            "inline"
          ],
            "html": "<div class=\"iframely-embed\"><div class=\"iframely-responsive\" style=\"height: 140px; padding-bottom: 0;\"><a href=\"https://stackoverflow.com/\" data-iframely-url=\"//cdn.iframe.ly/api/iframe?url=https%3A%2F%2Fstackoverflow.com&key=eda089f6090d00a60bba3ab368d2a3e6\"></a></div></div><script async src=\"//cdn.iframe.ly//embed.js\" charset=\"utf-8\"></script>"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Implementation

At the recipients' end, from the message object, you can fetch the metadata by calling the getMetadata() method. Using this metadata, you can fetch the Rich Media Embed.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    var metadata = message.getMetadata();
    if (metadata != null) {
      var injectedObject = metadata["@injected"];
      if (injectedObject != null && injectedObject.hasOwnProperty("extensions")) {
        var extensionsObject = injectedObject["extensions"];
        if (extensionsObject != null && extensionsObject.hasOwnProperty("rich-media")) {
          var richMediaObject = extensionsObject["rich-media"];
        }
      }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    JSONObject metadata = message.getMetadata();
    if (metadata != null) {
      JSONObject injectedObject = metadata.getJSONObject("@injected");
      if (injectedObject != null && injectedObject.has("extensions")) {
        JSONObject extensionsObject = injectedObject.getJSONObject("extensions");
        if (extensionsObject != null && extensionsObject.has("rich-media")) {
              JSONObject richMediaObject = extensionsObject.getJSONObject("rich-media");
            }
        }
    }
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    if (metadata != null) {
      if (metadata.has("@injected")) {
       val injectedJSONObject = metadata.getJSONObject("@injected")
       if (injectedJSONObject != null && injectedJSONObject.has("extensions")) {
       val extensionsObject = injectedJSONObject.getJSONObject("extensions")

       if (extensionsObject != null && extensionsObject.has("rich-media")) {
         val richMediaObject = extensionsObject.getJSONObject("rich-media")
       }
      }
     }
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    let textMessage = message as? TextMessage
    var metadata : [String : Any]? = textMessage.metaData
    if metadata != nil {

        var injectedObject : [String : Any]? = (metadata?["@injected"] as? [String : Any])!
                
        if injectedObject != nil && (injectedObject!["extensions"] != nil){

          var extensionsObject : [String : Any]? = injectedObject?["extensions"] as? [String : Any]

          if extensionsObject != nil && extensionsObject?["rich-media"] != nil {
            var richMediaObject = extensionsObject?["rich-media"] as! [String :  Any]
          }
       }
    }
    ```
  </Tab>
</Tabs>


# Save Message
Source: https://www.cometchat.com/docs/fundamentals/save-message

Save, unsave, and fetch saved CometChat messages for each user with private saved-message lists.

## Extension settings

1. Login to the [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Save message extension.

## How does it work?

Save message extension provides you the ability to:

1. Save messages
2. Unsave messages
3. Fetch all the saved messages by the user.

Saved messages are private and are visible to the user who has saved them.

### 1. Save a message

To save a message, use the `callExtension` method provided by the SDK to make an HTTP POST request with the parameters as shown below. You need to pass the `msgId` of the message that has to be saved.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('save-message', 'POST', 'v1/save', {
        "msgId": 111
    }).then(response => {
        // { success: true }
    })
    .catch(error => {
        // Error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("msgId", 111);

    CometChat.callExtension("save-message", "POST", "/v1/save", body,
     new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            //On Success
        }
        @Override
        public void onError(CometChatException e) {
            //On Failure
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "save-message", type: .post, endPoint: "v1/save", body: ["msgId": 111] as [String : Any], onSuccess: { (response) in
             // Success
          }) { (error) in
             // Error occured
          }
    ```
  </Tab>
</Tabs>

### 2. Unsave a message

To unsave a message, use the `callExtension` method provided by the SDK to make an HTTP DELETE request with the parameters as shown below. You need to pass the `msgId` of the message that needs to be unsaved.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('save-message', 'DELETE', 'v1/unsave', {
        "msgId": 111
    }).then(response => {
        // { success: true }
    })
    .catch(error => {
        // Error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("msgId", 111);

    CometChat.callExtension("save-message", "DELETE", "/v1/unsave", body,
     new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            //On Success
        }
        @Override
        public void onError(CometChatException e) {
            //On Failure
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "save-message", type: .delete, endPoint: "v1/unsave", body: ["msgId": 111] as [String : Any], onSuccess: { (response) in
             // Success
          }) { (error) in
             // Error occured
          }
    ```
  </Tab>
</Tabs>

### 3. Fetch saved messages

To fetch the saved messages for a user, use the `callExtension` method provided by the SDK to make an HTTP GET request with the query parameters as shown below.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const URL = `v1/fetch`;
    CometChat.callExtension('save-message', 'GET', URL, null).then(response => {
        // {savedMessages: []}
    })
    .catch(error => {
        // Error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String URL = "/v1/fetch";

    CometChat.callExtension("save-message", "GET", URL, null,
    new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // {savedMessages: []}
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "save-message", type: .get, endPoint: "v1/fetch", body: nil, onSuccess: { (response) in
            // {savedMessages: []}
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>


# Smart Replies (Legacy)
Source: https://www.cometchat.com/docs/fundamentals/smart-replies

Show CometChat smart reply suggestions with positive, neutral, and negative responses injected into message metadata.

<Warning>
  **Legacy Notice**: This extension is already included as part of the core messaging experience (AI) and is scheduled for deprecation in the near future.

  Please note: Legacy extensions are no longer actively maintained and will not receive feature updates or enhancements.
</Warning>

The Smart Reply extension allows you to show quick reply options to a user so that they can easily respond to a message. We will always suggest 3 options; one positive, one neutral and one negative. We also add a category, in case you want to skip some suggestions.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Smart Reply extension.

## How does it work?

When a user sends a message, our Smart Reply extension will add metadata while the message is in-flight. The recipient will receive the message with metadata suggesting the responses.

At the recipients' end, from the message object, you can fetch the metadata by calling the getMetadata() method. Using this metadata, you can fetch suggested responses for the message.

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    "@injected": {
      "extensions": {
        "smart-reply": {
              "reply_positive": "<possible positive response>",
              "reply_neutral": "<possible neutral response>",
              "reply_negative": "<possible negative response>",
              "category": "<category>"
        }
      }
    }
    ```
  </Tab>
</Tabs>

If the data is missing, it means that the extension has timed out.

## Implementation

Using the Smart Reply extension, you can build a UI like this:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    var metadata = message.getMetadata();
    if (metadata != null) {
      var injectedObject = metadata["@injected"];
      if (injectedObject != null && injectedObject.hasOwnProperty("extensions")) {
        var extensionsObject = injectedObject["extensions"];
        if (
          extensionsObject != null &&
          extensionsObject.hasOwnProperty("smart-reply")
        ) {
          var smartReplyObject = extensionsObject["smart-reply"];
          var reply_positive = smartReplyObject["reply_positive"];
          var reply_neutral = smartReplyObject["reply_neutral"];
          var reply_negative = smartReplyObject["reply_negative"];
          var category = smartReplyObject["category"];
        }
      }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    JSONObject metadata = message.getMetadata();
    if (metadata != null) {
     JSONObject injectedObject = metadata.getJSONObject("@injected");
     if (injectedObject != null && injectedObject.has("extensions")) {
      JSONObject extensionsObject = injectedObject.getJSONObject("extensions");
      if (extensionsObject != null && extensionsObject.has("smart-reply")) {
       JSONObject smartReply = extensionsObject.getJSONObject("smart-reply");
       String reply_positive = smartReply.getString("reply_positive");
       String reply_neutral = smartReply.getString("reply_neutral");
       String reply_negative = smartReply.getString("reply_negative");
       String category = smartReply.getString("category");

      }
     }
    }
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    if (metadata != null) {
      if (metadata.has("@injected")) {
        val injectedJSONObject = metadata.getJSONObject("@injected")
        if (injectedJSONObject != null && injectedJSONObject.has("extensions")) {
        val extensionsObject = injectedJSONObject.getJSONObject("extensions")
        if (extensionsObject.has("smart-reply")) {
        val smartReplyObject = extensionsObject.getJSONObject("smart-reply")
        if (smartReplyObject.has("reply_positive"))
        val reply_positive = smartReplyObject.getString("reply_positive")
        if (smartReplyObject.has("reply_neutral"))
        val reply_neutral = smartReplyObject.getString("reply_neutral")
        if (smartReplyObject.has("reply_negative"))
        val reply_negative = smartReplyObject.getString("reply_negative")
        if (smartReplyObject.has("category"))
        val category = smartReplyObject.getString("category")               
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    var metadata : [String : Any]? = textMessage.metaData
    if metadata != nil {
                
      var injectedObject : [String : Any]? = (metadata?["@injected"] as? [String : Any])!
                
      if injectedObject != nil && (injectedObject!["extensions"] != nil){
                    
        var extensionsObject : [String : Any]? = injectedObject?["extensions"] as? [String : Any]
                    
        if extensionsObject != nil && extensionsObject?["smart-reply"] != nil {
                        
          var smartReply = extensionsObject?["smart-reply"] as! [String :  Any]
          let reply_positive = smartReply["reply_positive"]
          let reply_neutral = smartReply["reply_neutral"]
          let reply_negative = smartReply["reply_negative"]
          let category = smartReply["category"]
        }
      }
    }
    ```
  </Tab>
</Tabs>


# Stickers
Source: https://www.cometchat.com/docs/fundamentals/stickers

Manage CometChat sticker sets from the dashboard, load enabled stickers, and send stickers in chat conversations.

The Stickers Extension is more like an image manager which allows you to quickly add/remove stickers directly from the dashboard.

<Frame>
  <img />
</Frame>

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Stickers extension.
3. Open the Settings for this extension.
4. Click on Save to start using Stickers with in your app.

CometChat provides 14 Default Sets of stickers for your use. Apart from these 14 sets, you can also create your own sets. Moreover, you can also choose stickers from each set as per your liking and use only those in your app.

## How does it work?

### Loading stickers

Before you start Sending or Receiving stickers in your app, you first have to load the Sticker Sets. In your app, you can add a section/drawer that shows the enabled stickers. A user can click on any of these stickers to send it in a chat.

In order to load stickers, you can use the `callExtension` method provided by our SDKs.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('stickers', 'GET', 'v1/fetch', null)
    .then(stickers => {
     	// Stickers received
    })
    .catch(error => {
    	// Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    CometChat.callExtension("stickers", "GET", "/v1/fetch", null,
        new CometChat.CallbackListener<JSONObject>() {
        @Override
        public void onSuccess(JSONObject responseObject) {
            // Stickers received here.
        }

        @Override
        public void onError(CometChatException e) {
            // Some error occured.
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "stickers", type: .get, endPoint: "v1/fetch", body: nil, onSuccess: { (response) in
    	print("Success",response)
    }) { (error) in
      print("Error",error?.errorCode, error?.errorDescription)
    }
    ```
  </Tab>
</Tabs>

In response, you will get the following JSON which contains `defaultStickers` and `customStickers` arrays. Stickers with the same stickerSetId can be grouped together while displaying them in your application.

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "defaultStickers": [
        { 
          "stickerOrder": "4",
          "stickerSetId": "9bc4bf29-6913-4a95-84c5-53a385c8fa0f",
          "stickerUrl": "https://site.bear1.png",
          "stickerSetName": "Bear",
          "id": "530fe94e-e7b9-424b-8f6f-fa8454ae8d97",
          "stickerSetOrder": "1",
          "stickerName": "bear_1.png"
        },
        {
          ...
        }, ...
      ],
      "customStickers":[
        {
          "modifiedAt": "2020-06-03T14:28:17.339Z",
          "stickerOrder": "1",
          "stickerSetId": "70bcd62c-103a-4d8a-acc8-a9af3debd423",
          "stickerUrl": "https://images.com/812/hurray.png",
          "createdAt": "2020-04-25T10:41:42.697Z",
          "stickerSetName": "rejoice",
          "id": "dd8ab83a-b036-4220-9351-ad968152fd36",
          "stickerSetOrder": "1",
          "stickerName": "hurray"
        },
        {
          ...
        }, ...
      ]
    }
    ```
  </Tab>
</Tabs>

### Sending Stickers

Stickers can be sent as a media message. You can check [Send message](/docs/sdk/javascript/send-message) section (linked for JavaScript) of our SDKs for more details.

Also, you can send stickers as [Custom message](/docs/sdk/javascript/send-message#custom-message) and include the `incrementUnreadCount: true` in the metadata of that custom message. This will help you increment unread counts for Custom messages (in this case stickers).

### Receiving Stickers

Stickers are images that can be received and displayed as any regular media message. In your application, you can use the `onMediaMessageReceived` listener in order to receive stickers.

Refer to our [Receive Messages](/docs/sdk/javascript/receive-message) documentation under the SDK of your choice.


# Stipop
Source: https://www.cometchat.com/docs/fundamentals/stickers-stipop

Add Stipop stickers to CometChat conversations with trending sticker packs, search, API keys, and extension calls.

*Learn how to integrate stickers by Stipop in your app.*

Stipop is the world's trendiest sticker platform and creator community.

## Before you begin:

1. Sign up at [Stipop](https://stipop.io/).

2. On successful signup, provide the following details:

   1. Application name
   2. Website
   3. Category
   4. Sub-category
   5. Region
   6. App MAU

3. Click on Get Started once done.

4. You will be able to see the API Key on their Dashboard. Keep this handy.

5. In the left navigation pane, go to Settings and select the Application tab.

6. Copy the Application ID and keep this handy.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the extensions section and enable the Stipop extension.
3. Click on the settings button and enter your Stipop Application ID and API Key.
4. Save the settings once done.

## How does it work?

The extension provides the following functionalities:

1. Get the current Trending stickers.
2. Search for stickers using a certain phrase or keyword

This extension uses the `callExtension` method provided by the CometChat SDK.

### Get trending stickers

The API call requires the following Query Parameters:

|             |        |                                                                                                                                 |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| lang        | string | Specify default language for regional stickers. Use a 2-letter ISO 639-1 language code. **Default Value: en**                   |
| limit       | int    | The maximum number of stickers per page. Use pageNumber accordingly for optimized sticker view. **Default Value: 20 (max: 50)** |
| pageNumber  | int    | Specify pageNumber to show limit number of stickers per page.                                                                   |
| countryCode | string | Specify default country for local stickers. Use a 2-letter ISO 3166-1 country code. **Default Value: US**                       |

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const qs = `?lang=${lang}&limit=${limit}&pageNumber=${pageNumber}&countryCode=${contryCode}`;

    CometChat.callExtension('stickers-stipop', 'GET', 'v1/trending' + qs, null)
      .then(response => {
    		// Stickers in response
    	})
    	.catch(error => {
    		// Error occured
    	});
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String URL = "/v1/trending?lang="+language+"&limit="+limit+"&pageNumber="+pageNumber+"&countryCode="+countryCode;

    CometChat.callExtension("stickers-stipop", "GET", URL, null,
    	new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // Stickers
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
      });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "stickers-stipop", type: .get, endPoint: "v1/trending?lang="+language+"&limit="+limit+"&pageNumber="+pageNumber+"&countryCode="+countryCode, nil, onSuccess: { (response) in
            // Stickers
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>

### Search for stickers

The API call requires the following Query Parameters:

|            |        |                                                                                                                                 |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| lang       | string | Specify default language for regional stickers. Use a 2-letter ISO 639-1 language code. **Default Value: en**                   |
| limit      | int    | The maximum number of stickers per page. Use pageNumber accordingly for optimized sticker view. **Default Value: 20 (max: 50)** |
| pageNumber | int    | Specify pageNumber to show limit number of stickers per page.                                                                   |
| query      | string | The search term for finding stickers.                                                                                           |

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const qs = `?lang=${lang}&limit=${limit}&pageNumber=${pageNumber}&query=${query}`;

    CometChat.callExtension('stickers-stipop', 'GET', 'v1/search' + qs, null)
      .then(response => {
    		// Stickers in response
    	})
    	.catch(error => {
    		// Error occured
    	});
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String URL = "/v1/search?lang="+language+"&limit="+limit+"&pageNumber="+pageNumber+"&query="+query;

    CometChat.callExtension("stickers-stipop", "GET", URL, null,
    	new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // Stickers
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
      });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "stickers-stipop", type: .get, endPoint: "/v1/search?lang="+language+"&limit="+limit+"&pageNumber="+pageNumber+"&query="+query, nil, onSuccess: { (response) in
            // Stickers
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>


# Tenor
Source: https://www.cometchat.com/docs/fundamentals/tenor

Add Tenor GIFs to CometChat conversations with trending GIFs, search results, API keys, and extension calls.

GIFs are a great way to change the tone or convey emotions in your conversations. Here's a guide which helps to implement Tenor in an easy and quick way. Let's get started!

## Before you begin

1. Sign up at [Tenor](https://tenor.com/) and create a new app.
2. Enter your App name, description and click create.
3. Make note of the API key that has been created.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Tenor extension.
3. Click on the Settings button, enter your Tenor API key, and hit save.

## How does it work?

This extension uses the `callExtension` method provided by the CometChat SDK. You can perform the following actions using this method:

1. Get trending GIFs
2. Search for GIFs

### Get Trending GIFs

To list and show the most trending GIFs on Tenor, all you have to do is include the following parameters in your request.

| key    | Value  | Description                                                                                                    |
| ------ | ------ | -------------------------------------------------------------------------------------------------------------- |
| offset | number | Since you can get paginated results for trending GIFs, you can provide an offset and fetch results accordingly |
| limit  | number | The number of Trending GIFs that you want to fetch                                                             |

Once you have set the above parameters, you can make a call to the extension as follows:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const URL = "v1/trending?offset=1&limit=15";
    CometChat.callExtension("gifs-tenor", "GET", URL, null)
      .then((response) => {
        // GIFs data from Tenor
      })
      .catch((error) => {
        // Error occured
      });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String URL = "/v1/trending?offset=1&limit=15";

    CometChat.callExtension("gifs-tenor", "GET", URL, null,
    new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // GIFs data from Tenor
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "gifs-tenor", type: .get, endPoint: "v1/trending?offset=10&limit=15", body: nil, onSuccess: { (response) in
            // GIFs data from Tenor
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>

### Search for GIFs

Apart from listing the trending ones, the extension also allows searching for a particular GIF using the following parameters:

| key    | value                                  | Description                                                                                                |
| ------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| offset | number                                 | Since you can get paginated results for searches, you can provide an offset and fetch results accordingly. |
| limit  | number                                 | The number of GIFs that you want to fetch as part of the search.                                           |
| lang   | 2-letter ISO 639-1 language identifier | (Optional) Defaults to en. (Example values: es, fr, it.)                                                   |
| query  | string                                 | Search term                                                                                                |

Once you have all the above parameters, you can make a call to the extension as follows:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const URL = "v1/search?offset=1&limit=15&query=awesome";
    CometChat.callExtension("gifs-tenor", "GET", URL, null)
      .then((response) => {
        // GIFs data from tenor
      })
      .catch((error) => {
        // Error occured
      });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String URL = "/v1/search?offset=1&limit=15&query=awesome";

    CometChat.callExtension("gifs-tenor", "GET", URL, null,
    new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // GIFs data from tenor
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "gifs-tenor", type: .get, endPoint: "v1/search?offset=10&limit=15&query=awesome", body: nil, onSuccess: { (response) in
            // GIFs data from tenor
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>


# Thumbnail Generation
Source: https://www.cometchat.com/docs/fundamentals/thumbnail-generation

Generate small, medium, and large thumbnails for CometChat image and video messages with attachment metadata.

The Thumbnail Generation extension will help you generate a thumbnail preview of an image or a video message.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to Extensions section and enable the Thumbnail Generation extension.

## How does it work?

A small, medium and large thumbnail is generated for every attachment of a Media message of type video or image.

For eg, if a Media message of type video is sent with 2 attachments, the links to these thumbnails are then provided in the metadata of the message as shown below:

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    "@injected": {
     	"extensions": {
    		"thumbnail-generation": {
    			"url_small": "https://data.cometchat.io/a1/small.png",
    			"url_medium": "https://data.cometchat.io/a1/medium.png",
        	"url_large": "https://data.cometchat.io/a1/large.png",
    			"attachments": [
    				{
    					"data": {
              	"name": "a1.mp4",
              	"extension": "mp4",
              	"mimeType": "video/mp4",
              	"url": "http://commondatastorage.com/sample/a1.mp4",
              	"thumbnails": {
    							"url_small": "https://data.cometchat.io/a1/small.png",
              		"url_medium": "https://data.cometchat.io/a1/medium.png",
              		"url_large": "https://data.cometchat.io/a1/large.png",
            		},
          		},
    	      	"error": null,
    				},
    				{
          		"data": {
            		"name": "a2.mp4",
            		"extension": "mp4",
            		"mimeType": "video/mp4",
            		"url": "http://data.cometchat.io/media/asdfasdf.mp4",
            		"thumbnails": {
              		"url_small": "https://data.cometchat.io/a2/small.png",
              		"url_medium": "https://data.cometchat.io/a2/medium.png",
              		"url_large": "https://data.cometchat.io/a2/large.png",
            		},
          		},
          		"error": null,
        		},
        		{
          		"data": {
            		"name": "a3.mp3",
            		"extension": "mp3",
            		"mimeType": "audio/mp3",
            		"url": "http://data.cometchat.io/media/asdfasdf.mp3",
            		"thumbnails": null,
          		},
          		"error": {
            		"code": "ERR_FILETYPE_NOT_SUPPORTED",
            		"message": "Support only for jpg, jpeg, png, gif, mov, mpg, mpeg, mp4, wmv, avi",
            		"devMessage": "Support only for jpg, jpeg, png, gif, mov, mpg, mpeg, mp4, wmv, avi",
            		"httpStatusCode": 400,
          		}
        		}
      		]
    		}
      }
    }
    ```
  </Tab>
</Tabs>

If the thumbnail-generation key is missing, it means that the extension is either not enabled or has timed out.

<Note>
  The `url_small`, `url_medium` & `url_large` keys to the outside of `attachments` are the thumbnail URLs for the first attachment from the `attachments` array. These have been retained for backward compatibility only.\
  You can iterate over `attachments` array for better implementation.
</Note>

## Implementation

You can make use of the `getMetadata()` method to extract the thumbnail details for a message.

The `url` field is the link to the actual image or video.

You can make use of `url_small`, `url_medium` & `url_large` keys for showing thumbnails based on the device of your end users.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    const metadata = message.getMetadata();
    if (metadata != null) {
      const injectedObject = metadata["@injected"];
      if (injectedObject != null && injectedObject.hasOwnProperty("extensions")) {
        const extensionsObject = injectedObject["extensions"];
        if (
          extensionsObject != null &&
          extensionsObject.hasOwnProperty("thumbnail-generation")
        ) {
          const { attachments } = extensionsObject["thumbnail-generation"];
          for (const attachment of attachments) {
            if (!attachment.error) {
            	const { url_small, url_medium, url_large } = attachment.data.thumbnails;
            	// Use the urls accordingly.
            }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    JSONObject metadata = message.getMetadata();
    if (metadata != null) {
      JSONObject injectedObject = metadata.getJSONObject("@injected");
      if (injectedObject != null && injectedObject.has("extensions")) {
        JSONObject extensionsObject = injectedObject.getJSONObject("extensions");
        if (extensionsObject != null && extensionsObject.has("thumbnail-generation"))
            {
              JSONObject tg = extensionsObject.getJSONObject("thumbnail-generation");
          		JSONArray attachments = tg.getJSONArray("attachments");

          		for (int i = 0; i < attachments.length(); i++) {
                JSONObject attachment = attachments.getJSONObject(i);
                JSONObject error = attachment.getJSONObject("error");
                if (error == null) {
                  JSONObject data = attachment.getJSONObject("data");
                  JSONObject thumbnails = data.getJSONObject("thumbnails");
                	String url_small = thumbnails.getString("url_small");
                	String url_medium = thumbnails.getString("url_medium");
                	String url_large = thumbnails.getString("url_large");
    							// Use the urls are per requirement
                }
              }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    if (metadata != null) {
      if (metadata.has("@injected")) {
    		val injected = metadata.getJSONObject("@injected")
        if (injected != null && injected.has("extensions")) {
        	val extensions = injectedJSONObject.getJSONObject("extensions")
    			if (extensions != null && extensions.has("thumbnail-generation")) {
      			val tg = extensions.getJSONObject("thumbnail-generation")
      			val attachments = tg.getJSONArray("attachments")
    				for (i in 0 until attachments.length()) {
              val attachment = attachments.getJSONObject(i)
              val error = attachment.getJSONObject("error")
              if (error == null) {
                val data = attachment.getJSONObject("data")
                val thumbnails = data.getJSONObject("thumbnails")
              	val url_small = thumbnails.getString("url_small")
      					val url_medium = thumbnails.getString("url_medium")
      					val url_large = thumbnails.getString("url_large")
              }
            }
    			}
    		}
    	}
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    if let metaData = message?.metaData , let injected = metaData["@injected"] as? [String : Any], let extensions =injected["extensions"] as? [String : Any], let attachments = extensions["thumbnail-generation"] as? [[String : Any]] {

        for attachment in attachments {

          if let data = attachment["data"] as? [String:Any] , let thumbnails = data["thumbnails"] as? [String:any] {
        
           if let urlSmall = URL(string: thumbnails["url_small"] as? String) {
    // Use the url accordingly.
     }
           if let urlMedium = URL(string: thumbnails["url_medium"] as? String) {
    // Use the url accordingly.
    }
          if let urlLarge = URL(string: thumbnails["url_large"] as? String) {
    // Use the url accordingly.
    }
          // check for attachment.error if "thumbnails" is null
       }
    }
    }
    ```
  </Tab>
</Tabs>

<Note>
  Unlike image thumbnails, which are normally generated in milliseconds, video thumbnails may take a little longer. Before viewing the preview, we recommend verifying to see if the file exists. If the difference between message sentAt and the current time is less than 5 seconds, you can set a simple timer to monitor every second.
</Note>


# TinyURL
Source: https://www.cometchat.com/docs/fundamentals/tinyurl

Shorten long links in CometChat text messages with TinyURL by configuring an API token, domain, and extension call.

*Learn how to minify the long website links in your text messages using TinyURL.*

## Before you begin

1. Sign up with [TinyURL](https://tinyurl.com/app/login)
2. Once you have logged in, click on Account in the top right corner.
3. In the left navigation pane, select API.
4. Create an API Token by giving it a name and permission to Create TinyURL.
5. Make note of the API Token as it will be required in Extension's settings.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the TinyURL extension.
3. Open the settings and enter the TinyURL API Token.
4. If you have chosen a paid plan, you can also save your BYO domain or subdomain. Default is set to `tinyurl.com`
5. Save your settings.

<Note>
  BYO Domain

  If you don't plan on using a custom domain, please save `tinyurl.com` as the default value here.
</Note>

## How does it work?

This extension uses the `callExtension` method provided by CometChat SDK. You can call the extension as follows:

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension("url-shortener-tinyurl", "POST", "v1/shorten", {
      text: "Your message with URL https://yourdomain.com/very/very/long/url",
    })
      .then((response) => {
        // minifiedText in response
      })
      .catch((error) => {
        // Error occured
      });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String URL = "/v1/shorten";
    JSONObject body=new JSONObject();

    body.put("text", "Your message with URL https://yourdomain.com/very/very/long/url");

    CometChat.callExtension("url-shortener-tinyurl", "POST", URL, body,
    new CometChat.CallbackListener < JSONObject > () {
        @Override
        public void onSuccess(JSONObject jsonObject) {
            // minifiedText from the extension
        }
        @Override
        public void onError(CometChatException e) {
            // Some error occured
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "url-shortener-tinyurl", type: .post, endPoint: "v1/shorten", body: ["text": "Your message with URL https://yourdomain.com/very/very/long/url"], onSuccess: { (response) in
            // minifiedText from the extension
          }) { (error) in
            // Some error occured
          }
        }
    ```
  </Tab>
</Tabs>


# Authentication and User Management
Source: https://www.cometchat.com/docs/fundamentals/user-auth

Create users, issue auth tokens, and log users into CometChat.

## Create and Log In a User

### Guide details

This guide provides a step-by-step guide on creating and logging in a user using the CometChat platform with authentication using the Authentication Token. Additionally, you will need to make sure you have initialized CometChat in your app prior to logging in the user.

### Introduction

To log in a user, they must first be registered on the CometChat server. For first-time logins, the user needs to be created in CometChat. After this initial creation, we can generate an authentication token for the user.

This authentication token, created via the CometChat API, will be used on the front-end to log the user into the **CometChat UI Kit, SDK, or Widget**.

Once the user is successfully logged into CometChat, we can proceed to request or post any necessary data for the app.

## Prerequisites

* CometChat App (You can create one via the [CometChat Dashboard](https://app.cometchat.com/apps)).
* CometChat UI Kit or SDK (Custom Widget as well).
* Your application: Front-end and Back-end / Server Side.

## Create Chat User in CometChat

1. Handle the user creation endpoint in your application.

2. Add the user to your database.

3. Invoke the [CometChat API endpoint to create a user](/docs/rest-api/chat-apis).

   * Optionally, pass a parameter to generate an authentication token for this user.

4. CometChat will respond with the authentication token to your server.

5. Your server will send the successful user creation response to your front-end application.

6. Utilize the CometChat auth token to log the user into the [CometChat SDK / UI Kit](https://www.cometchat.com/docs/javascript-chat-sdk/authentication#login-using-auth-token), or [Widget](/docs/widget/html/integration#3-backend-created-user-auth-token-login).

<Frame>
  <img alt="CometChat - Create Chat User" />
</Frame>

## Log In an Existing User

1. Authenticate the user within your application.
2. Your API will then request a CometChat auth token for the user. You can call the [create auth token API endpoint](/docs/rest-api/chat-apis) to create a new one.
3. Your server responds with the successful retrieval of the CometChat auth token to your front-end application.
4. Utilize the CometChat auth token to log the user into the [CometChat SDK / UI Kit](https://www.cometchat.com/docs/javascript-chat-sdk/authentication#login-using-auth-token),
5. If you’re using the **Widget Builder**, refer to the documentation on **[auth token–based user login](/docs/widget/html/integration#3-backend-created-user-auth-token-login)**.

<Frame>
  <img alt="CometChat - Logging On a User" />
</Frame>

## Migrate Existing Users to CometChat

If you need to migrate the existing users, refer to the [Data Import Guide](https://www.cometchat.com/docs/rest-api/data-import)


# User Roles And Permissions In CometChat
Source: https://www.cometchat.com/docs/fundamentals/user-roles-and-permissions

Review CometChat dashboard roles and permissions for owners, admins, moderators, and developers across platform sections.

CometChat provides a comprehensive roles and permissions system to ensure that team members have the appropriate level of access to platform features and settings. Properly assigning these roles helps maintain security, streamline workflows, and delegate responsibilities effectively.

## User Roles Overview

* **Owner** – Unrestricted access to every feature, including Plans & Billing.
* **Admin** – Full access to all sections except Plans & Billing.
* **Moderator** – Manages content and user interactions; limited to moderation-related features.
* **Developer** – Configures integrations and technical settings; does not have access to moderation controls.

## Permissions Matrix

| **Section**         | **Permission**       | **Owner** | **Admin** | **Moderator** | **Developer** |
| ------------------- | -------------------- | --------- | --------- | ------------- | ------------- |
| **Overview**        | Overview             | Yes       | Yes       | No            | No            |
| **Integrate**       | Integrate            | Yes       | Yes       | No            | Yes           |
| **Manage**          | User                 | Yes       | Yes       | Yes           | Yes           |
|                     | Group                | Yes       | Yes       | Yes           | Yes           |
|                     | User Roles           | Yes       | Yes       | Yes           | Yes           |
| **Chats**           | Logs                 | Yes       | Yes       | Yes           | Yes           |
|                     | Widget               | Yes       | Yes       | No            | Yes           |
|                     | Features             | Yes       | Yes       | No            | Yes           |
|                     | Moderation           | Yes       | Yes       | Yes           | No            |
| **Insights**        | Insights             | Yes       | Yes       | Yes           | Yes           |
| **Settings**        | Settings             | Yes       | Yes       | No            | No            |
| **Calls**           | Logs                 | Yes       | Yes       | Yes           | Yes           |
|                     | Insights             | Yes       | Yes       | Yes           | Yes           |
|                     | Moderation           | Yes       | Yes       | Yes           | No            |
| **AI Chatbot**      | Bots                 | Yes       | Yes       | No            | Yes           |
|                     | Instructions         | Yes       | Yes       | No            | Yes           |
| **Non-AI Bots**     | Bots                 | Yes       | Yes       | No            | Yes           |
|                     | Instructions         | Yes       | Yes       | No            | Yes           |
| **Notifications**   | Notifications        | Yes       | Yes       | Yes           | Yes           |
|                     | Legacy Notifications | Yes       | Yes       | Yes           | Yes           |
|                     | Insights             | Yes       | Yes       | Yes           | Yes           |
| **Application**     | Credentials          | Yes       | Yes       | No            | Yes           |
|                     | Webhooks             | Yes       | Yes       | No            | Yes           |
|                     | Legacy Webhooks      | Yes       | Yes       | Yes           | Yes           |
|                     | Team Members         | Yes       | Yes       | Yes           | Yes           |
| **Plans & Billing** | Settings             | No        | No        | No            | No            |


# Live Streaming By API Video (Deprecated)
Source: https://www.cometchat.com/docs/fundamentals/video-broadcasting

Set up CometChat live streaming with api.video, OBS broadcast details, viewer embed links, and recording options.

<Warning>
  Deprecated: This extension is no longer maintained and will not receive further updates.
</Warning>

The Live streaming by api.video extension enables you to set up a live stream to broadcast to a large number of users.

## Before you begin

1. Sign up with [api.video](https://api.video/)
2. Get your **API Key**. Make sure you set up a payment method with them in order to get the **Production API key**. The Sandbox API Key will not work.
3. Broadcaster needs to download and install [OBS](https://obsproject.com/), a free and open-source software.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Live Streaming (Video Broadcasting) extension.
3. Open the Settings for this extension.
4. Enter the api.video Production API Key.
5. You can also select whether you want to record the live stream.

## How does it work?

This extension delivers 2 different configurations:

1. The broadcaster gets the `server` address and `streamKey`.
2. The viewers get the `embed link` along with a few more details.

### Broadcaster

#### 1. Get broadcast details

The CometChat SDKs provide a `callExtension` method that can be called to trigger this extension. The broadcaster has to provide the following:

1. Receiver type - `user` or `group`
2. The `receiver` of the broadcast link (can be a `uid` for a user or `guid` in case of a group)

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    CometChat.callExtension('broadcast', 'POST', 'v1/broadcast', {
      receiverType: 'user/group',
      receiver: 'uid/guid'
    }).then(response => {
     // Success response
    }).catch(error => {
     // Some error occured
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import org.json.simple.JSONObject;

    JSONObject body=new JSONObject();
    body.put("receiverType", "user/group");
    body.put("receiver", "uid/guid");

    CometChat.callExtension("broadcast", "POST", "/v1/broadcast", body,
        new CometChat.CallbackListener<JSONObject>() {
        @Override
        public void onSuccess(JSONObject responseObject) {
            // Broadcaster details
        }

        @Override
        public void onError(CometChatException e) {
            // Some error occured.
        }
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CometChat.callExtension(slug: "broadcast", type: .post, endPoint: "v1/broadcast", body: ["receiverType":"user/group", "receiver":"uid/guid"], onSuccess: { (response) in
            // Success response
          }) { (error) in
            // Some error occured
          }
    ```
  </Tab>
</Tabs>

If the call is successful, the method will return the following JSON response:

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
       "broadcaster": {
          "server": "rtmp://broadcast.api.video_s",
          "streamKey": "04cb0167-5za4-4ba6-831x-efa28e1917o3"
       }
    }
    ```
  </Tab>
</Tabs>

#### 2. Start Streaming

In order to start streaming/broadcasting, launch OBS studio and go to: **Settings > Stream > Select `Custom`** from drop-down and enter the `server` and `streamKey`**.**

Once the details have been entered, click OK and close the Settings Panel. Next, you can click on the "Start Streaming" button.

### Viewers

The viewers can either be a Group or a User.

The recipient(s) will receive a text message with `embed link` and `metadata` as follows:

<Tabs>
  <Tab title="Text message">
    ```json theme={null}
    Hello! I’m currently broadcasting. Use this link to join the broadcast: https://embed.api.video/live/li3WPpN3Ixj7dTDwdtL0dKt1
    ```
  </Tab>

  <Tab title="JSON">
    ```json theme={null}
    "@injected": {
      "extensions": {
        "broadcast": {
          "hls": "https://live.api.video/li6xl2dCcboxPGTFq1D4Fhmb.m3u8",
          "iframe": "<iframe src=\"https://embed.api.video/live/li6xl2dCcboxPGTFq1D4Fhmb\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
          "player": "https://embed.api.video/live/li6xl2dCcboxPdGTFq1D4Fhmb",
          "thumbnail": "https://cdn.api.video/live/li6xl2dCcboxPGTFq1D4Fhmb/thumbnail.jpg"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Implementation

At the viewers' end, from the message object, you can fetch the metadata by calling the getMetadata() method. Using this metadata, you can fetch the broadcast details.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    var metadata = message.getMetadata();
    if (metadata != null) {
      var injectedObject = metadata["@injected"];
      if (injectedObject != null && injectedObject.hasOwnProperty("extensions")) {
        var extensionsObject = injectedObject["extensions"];
        if (
          extensionsObject != null &&
          extensionsObject.hasOwnProperty("broadcast")
        ) {
          var broadcastObject = extensionsObject["broadcast"];
        }
      }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    JSONObject metadata = message.getMetadata();
    if (metadata != null) {
      JSONObject injectedObject = metadata.getJSONObject("@injected");
      if (injectedObject != null && injectedObject.has("extensions")) {
        JSONObject extensionsObject = injectedObject.getJSONObject("extensions");
        if (extensionsObject != null && extensionsObject.has("broadcast")) {
              JSONObject broadcastObject = extensionsObject.getJSONObject("broadcast");
            }
        }
    }
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    if (metadata != null) {
      if (metadata.has("@injected")) {
       val injectedJSONObject = metadata.getJSONObject("@injected")
       if (injectedJSONObject != null && injectedJSONObject.has("extensions")) {
       val extensionsObject = injectedJSONObject.getJSONObject("extensions")

       if (extensionsObject != null && extensionsObject.has("broadcast")) {
         val broadcastObject = extensionsObject.getJSONObject("broadcast")
       }
      }
     }
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    let textMessage = message as? TextMessage
    var metadata : [String : Any]? = textMessage.metaData
    if metadata != nil {

        var injectedObject : [String : Any]? = (metadata?["@injected"] as? [String : Any])!
                
        if injectedObject != nil && (injectedObject!["extensions"] != nil){

          var extensionsObject : [String : Any]? = injectedObject?["extensions"] as? [String : Any]

          if extensionsObject != nil && extensionsObject?["broadcast"] != nil {
            var broadcastObject = extensionsObject?["broadcast"] as! [String :  Any]
          }
       }
    }
    ```
  </Tab>
</Tabs>


# Voice Transcription
Source: https://www.cometchat.com/docs/fundamentals/voice-transcription

Enable CometChat voice transcription with Rev.ai to convert audio messages into text and receive transcription metadata.

Voice transcription extension allows you to convert an audio message into text.

## Before you begin

1. Sign up with [Rev.ai](https://rev.ai/)
2. Get your `Access Token` for configuring this extension.

## Extension settings

1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
2. Go to the Extensions section and enable the Voice Transcription extension.
3. Open the Settings for this extension.
4. Enter the Rev.ai Access Token, and click on save.

## How does it work?

Once the Extension is enabled for your App and the settings are done, the recipients will receive metadata with the transcription details.

The transcription information will be updated later for the message and hence you need to implement the `onMessageEdited` listener. Please check our [Edit ,message](/docs/sdk/javascript/edit-message) documentation under the SDK of your choice.

Here is a sample response:

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    "@injected": {
      "extensions": {
        "voice-transcription": {
          "transcribed_message": "This is a test"
      }
    }
    ```
  </Tab>
</Tabs>

If the voice-transcription key is missing, it means that either the extension is not enabled or has timed out.

## Implementation

At the recipients' end, from the message object, you can fetch the metadata by calling the getMetadata() method. Using this metadata, you can fetch the Rich Media Embed.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    var metadata = message.getMetadata();
    if (metadata != null) {
      var injectedObject = metadata["@injected"];
      if (injectedObject != null && injectedObject.hasOwnProperty("extensions")) {
        var extensionsObject = injectedObject["extensions"];
        if (
          extensionsObject != null &&
          extensionsObject.hasOwnProperty("voice-transcription")
        ) {
          var voiceTranscriptionObject = extensionsObject["voice-transcription"];
          var transcribed_message = voiceTranscriptionObject["transcribed_message"];
        }
      }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    JSONObject metadata = message.getMetadata();
    if (metadata != null) {
      JSONObject injectedObject = metadata.getJSONObject("@injected");
      if (injectedObject != null && injectedObject.has("extensions")) {
        JSONObject extensionsObject = injectedObject.getJSONObject("extensions");
        if (extensionsObject != null && extensionsObject.has("voice-transcription")) {
              JSONObject transcriptionObject = extensionsObject.getJSONObject("voice-transcription");
            }
        }
    }
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    if (metadata != null) {
      if (metadata.has("@injected")) {
       val injectedJSONObject = metadata.getJSONObject("@injected")
       if (injectedJSONObject != null && injectedJSONObject.has("extensions")) {
       val extensionsObject = injectedJSONObject.getJSONObject("extensions")

       if (extensionsObject != null && extensionsObject.has("voice-transcription")) {
         val transcriptionObject = extensionsObject.getJSONObject("voice-transcription")
       }
      }
     }
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    let textMessage = message as? TextMessage
    var metadata : [String : Any]? = textMessage.metaData
    if metadata != nil {

        var injectedObject : [String : Any]? = (metadata?["@injected"] as? [String : Any])!
                
        if injectedObject != nil && (injectedObject!["extensions"] != nil){

          var extensionsObject : [String : Any]? = injectedObject?["extensions"] as? [String : Any]

          if extensionsObject != nil && extensionsObject?["voice-transcription"] != nil {
            var transcriptionObject = extensionsObject?["voice-transcription"] as! [String :  Any]
          }
       }
    }
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    Map<String, dynamic>? metadata = message.metadata;
    try {
      if (metadata != null) {
        Map? injectedObject = metadata["@injected"];

        if (injectedObject != null &&
            injectedObject.containsKey("extensions")) {
          Map extensionsObject = injectedObject["extensions"];

          if (extensionsObject.containsKey("voice-transcription")) {
            Map voiceTranscriptionObject =
                extensionsObject["voice-transcription"];

            List attachments = voiceTranscriptionObject['attachments'];

            for (var attachment in attachments) {
              if (attachment['error'] == null) {
                final attachmentData = attachment['data'];
                final transcribedMessage = attachmentData['transcribed_message'];
              }
            }
          }
        }
      }
    } catch (e, stack) {
      debugPrint("$stack");
    }
    ```
  </Tab>
</Tabs>


# Webhooks
Source: https://www.cometchat.com/docs/fundamentals/webhooks

Use CometChat webhooks to send real-time chat, user, group, call, and moderation events to your server.

CometChat Webhooks enable real-time, event-driven communication with your server by sending HTTP POST requests whenever specific events occur in your chat application.

## What Are Webhooks?

Webhooks are automated notifications that CometChat sends to your server when events happen—such as messages being sent, users coming online, or group membership changes. Instead of polling for updates, your server receives instant notifications, enabling real-time integrations.

## Common Use Cases

Webhooks enable you to build powerful integrations and automations:

* **Notifications**: Send SMS, email, or push notifications when users receive messages
* **Analytics**: Track messaging activity and user engagement in your analytics platform
* **Moderation**: Trigger content review workflows when messages are flagged
* **Sync**: Keep external systems (CRM, support tools, databases) in sync with chat activity
* **Automation**: Trigger business workflows based on chat events

## Supported Events

CometChat webhooks cover a comprehensive range of events across different categories:

### Message Events

Notifications for message lifecycle events including sent, edited, deleted, delivered, read, and reactions.

### User Events

Notifications for user actions such as blocking/unblocking users and connection status changes (online/offline).

### Group Events

Notifications for group lifecycle and membership events including creation, updates, member joins/leaves, bans, and scope changes.

### Call and Meeting Events

Notifications for voice/video call events including initiation, start, end, participant joins/leaves, and recording generation.

### Moderation Events

Notifications for content moderation outcomes including auto-approved, auto-blocked, and manually approved messages.

### Campaign Events

Notifications for campaign lifecycle events including campaign completion, failure, notification creation, feed item delivery (sent, delivered, read, interacted), and push notification delivery (sent, delivered, clicked).

## Webhook Requirements

Your webhook endpoint must:

* Use **HTTPS** for secure communication
* Be **publicly accessible** from the internet
* Accept **HTTP POST** requests with JSON content
* Respond with **HTTP 200 OK** to acknowledge receipt

## Security

CometChat supports **Basic Authentication** to secure your webhook endpoints. When configured, every webhook request includes an Authorization header with your credentials, ensuring only authorized requests are processed.

## Best Practices

* **Handle retries gracefully**: Use event IDs to deduplicate retried deliveries
* **Respond quickly**: Return 200 OK within 2 seconds; queue longer processing tasks
* **Log everything**: Maintain detailed logs for debugging and monitoring
* **Test thoroughly**: Simulate various conditions before going to production

## Getting Started

You can configure webhooks through the CometChat Dashboard or programmatically via the Management APIs.

For detailed setup instructions and API documentation, refer to the [Webhooks REST APIs](/docs/rest-api/management-apis/webhooks/overview).


# Home
Source: https://www.cometchat.com/docs/index

Technical documentation & Implementation guides to add In-app Messaging & Voice & Video Calling to your apps and websites in minutes.

<div>
  <div>
    <h2>
      Products
    </h2>

    <p>
      Explore our core offerings to power your in-app communication needs.
    </p>

    <CardGroup>
      <Card title="Chat & Messaging" icon={<img src="https://mintcdn.com/cometchat-22654f5b/3DLmgeJDJ1LVnju4/images/products/chat.svg?fit=max&auto=format&n=3DLmgeJDJ1LVnju4&q=85&s=134bc4c99880ddc09a889584408340d0" alt="Chat & Messaging" />} href="/chat-call">
        Lightning-fast conversations & calling with enterprise scalability
      </Card>

      <Card
        title="Voice & Video Calling"
        icon={
<img src="https://mintcdn.com/cometchat-22654f5b/3DLmgeJDJ1LVnju4/images/products/calls.svg?fit=max&auto=format&n=3DLmgeJDJ1LVnju4&q=85&s=66f74c19b7782d98af0c4e75cd57730c" alt="Voice & Video Calling" />
}
        href="/calls"
      >
        Add real-time voice and video calling to your apps with ease.
      </Card>

      <Card title="AI Agents" icon={<img src="https://mintcdn.com/cometchat-22654f5b/3DLmgeJDJ1LVnju4/images/products/ai-agents.svg?fit=max&auto=format&n=3DLmgeJDJ1LVnju4&q=85&s=4871cb17496c8aaede06248b2940e34a" alt="AI Agents" />} href="/ai-agents">
        Automate conversations using AI-powered chatbot technology.
      </Card>

      <Card title="Campaigns" icon={<img src="https://mintcdn.com/cometchat-22654f5b/6Q4FMfBUbw_1bl7H/images/products/campaigns.svg?fit=max&auto=format&n=6Q4FMfBUbw_1bl7H&q=85&s=1bcb770b47c22efba7bfec182843fcb1" alt="Campaigns" />} href="/campaigns">
        Send notifications & campaigns with an in-app feed and push.
      </Card>
    </CardGroup>
  </div>

  <div>
    <h2>
      Features
    </h2>

    <p>
      Enhance your app with these powerful communication features.
    </p>

    <CardGroup>
      <Card
        title="AI Moderation"
        icon={
<img src="https://mintcdn.com/cometchat-22654f5b/3DLmgeJDJ1LVnju4/images/products/ai-moderation.svg?fit=max&auto=format&n=3DLmgeJDJ1LVnju4&q=85&s=2456f5acc92059d681dfea8275575729" alt="AI Moderation" />
}
        href="/moderation/overview"
      >
        Ensure safety with advanced content filtering tools.
      </Card>

      <Card
        title="Notifications"
        icon={
<img src="https://mintcdn.com/cometchat-22654f5b/3DLmgeJDJ1LVnju4/images/products/notifications.svg?fit=max&auto=format&n=3DLmgeJDJ1LVnju4&q=85&s=86899b4971f24d73ed64496bc7403a07" alt="Notifications" />
}
        href="/notifications"
      >
        Boost engagement by sending instant user notifications.
      </Card>

      <Card title="Insights" icon={<img src="https://mintcdn.com/cometchat-22654f5b/3DLmgeJDJ1LVnju4/images/products/insights.svg?fit=max&auto=format&n=3DLmgeJDJ1LVnju4&q=85&s=53649a711ddf9c26321d33222f734ad4" alt="Insights" />} href="/insights">
        Generate AI-powered insights for meaningful conversations.
      </Card>
    </CardGroup>
  </div>

  <div>
    <h2>More</h2>

    <p>
      Additional solutions to customize your CometChat experience.
    </p>

    <CardGroup>
      <Card
        title="On-Premise Deployment"
        icon={
<img src="https://mintcdn.com/cometchat-22654f5b/3DLmgeJDJ1LVnju4/images/products/on-prem.svg?fit=max&auto=format&n=3DLmgeJDJ1LVnju4&q=85&s=a67023f22d59645e4a2c30b9116f21fb" alt="On-Premise Deployment" />
}
        href="/on-premise-deployment/docker/overview"
      >
        Deploy CometChat on your own infrastructure for maximum control and security.
      </Card>

      <Card title="Docs MCP" icon="robot" href="/mcp-server">
        Add CometChat Docs MCP to your AI tools for instant documentation access.
      </Card>
    </CardGroup>
  </div>

  <div>
    <h2>
      Resources
    </h2>

    <p>
      Quick links to deeper integration guides, API references, and community
      support.
    </p>

    <CardGroup>
      <Card title="Help Center" icon="phone" href="https://help.cometchat.com/">
        Search our comprehensive knowledge base for all your CometChat questions.
      </Card>

      <Card title="Interactive Demo" icon="bolt-lightning" href="https://www.cometchat.com/interactive-demo">
        Experience CometChat in action with our live demo.
      </Card>

      <Card title="Product Updates" icon="newspaper" href="https://updates.cometchat.com/">
        Stay ahead of the curve with the latest features.
      </Card>

      <Card title="Status Page" icon="signal" href="https://status.cometchat.com/">
        Stay informed of any service interruptions.
      </Card>
    </CardGroup>
  </div>
</div>

<div>
  <div>
    <div>2026 © CometChat</div>

    <div>
      <a href="https://www.linkedin.com/company/cometchat">
        <svg>
          <path />
        </svg>

        <span>LinkedIn</span>
      </a>

      <a href="https://x.com/cometchat">
        <svg>
          <path />
        </svg>

        <span>Twitter</span>
      </a>

      <a href="https://github.com/cometchat">
        <svg>
          <path />
        </svg>

        <span>GitHub</span>
      </a>
    </div>
  </div>
</div>


# Use CometChat with AI Coding Agents (MCP)
Source: https://www.cometchat.com/docs/mcp-server

Connect CometChat to Claude, Cursor, Windsurf, VS Code, and any other Model Context Protocol–compatible agent. Search docs, fetch reference pages, and pull implementation bundles from inside the conversation.

The **CometChat MCP server** lets Claude, Cursor, Windsurf, VS Code, and any
other Model Context Protocol–compatible agent integrate CometChat into your
app from natural-language prompts. Ask the agent to *"add a chat tab where
users can DM each other"* and it uses the MCP to read CometChat's docs,
pick the right components for your stack, and write the integration code.

The server is **read-only** and **needs no account or API key** — it surfaces
CometChat's public documentation and curated implementation recipes.

## Connector URL

```
https://mcp.cometchat.com/mcp
```

Transport: HTTP with Server-Sent Events. No authentication required.

## Connect from your agent

### Claude (Desktop or claude.ai)

1. Open **Settings → Connectors**.
2. Click **Add custom connector**.
3. Name it `CometChat`, paste the URL `https://mcp.cometchat.com/mcp`, and click **Add**.
4. In a new conversation, attach **CometChat** from the connectors picker and prompt away.

### Cursor

1. `Cmd+Shift+P` (macOS) / `Ctrl+Shift+P` (Windows) → **Open MCP settings**.
2. Click **Add custom MCP** and paste:

```json theme={null}
{
  "mcpServers": {
    "cometchat": {
      "url": "https://mcp.cometchat.com/mcp"
    }
  }
}
```

### Windsurf

1. Click the **Plugins** (hammer) icon → **Manage plugins** → **View raw config**.
2. Paste:

```json theme={null}
{
  "mcpServers": {
    "cometchat": {
      "type": "sse",
      "serverUrl": "https://mcp.cometchat.com/mcp"
    }
  }
}
```

3. Save and click **Refresh**.

### Visual Studio Code (Copilot Agent)

1. `Cmd+Shift+P` / `Ctrl+Shift+P` → **MCP: Add MCP Server**.
2. Enter:
   * **Server Name:** `CometChat`
   * **Server URL:** `https://mcp.cometchat.com/mcp`
   * **Transport:** SSE
3. Confirm.

## Example prompts

Once connected, try these in a fresh agent conversation:

* *"Add a chat tab where users can DM each other in my React app."*
* *"Let project members talk in a group chat with file sharing."*
* *"Add video calling between two users with a click-to-call button."*
* *"Set up content moderation so banned words are blocked before delivery."*
* *"Build a multi-tenant SaaS chat where each workspace's users are isolated."*
* *"Add presence indicators and typing dots to my conversation list."*

The agent will search the docs, pull the matching implementation bundle,
and write the code into your project.

## What the connector exposes

### Three tools (all read-only)

<CardGroup>
  <Card title="search_cometchat_docs" icon="magnifying-glass">
    Search SDK guides, UI Kit references, REST API docs, and OpenAPI
    specs. Returns ranked snippets with direct links.
  </Card>

  <Card title="fetch_cometchat_doc_page" icon="file-lines">
    Fetch the full content of any documentation page as markdown by URL
    or relative path.
  </Card>

  <Card title="get_cometchat_implementation_bundle" icon="box-open">
    Return a curated implementation recipe — prerequisites, install,
    configuration, working code — for a named scenario.
  </Card>
</CardGroup>

### Ten curated implementation bundles

| Bundle                          | What it covers                                                     |
| ------------------------------- | ------------------------------------------------------------------ |
| `react-uikit-quickstart`        | React UI Kit install, init, login, conversations list, chat window |
| `react-native-uikit-quickstart` | React Native UI Kit install, navigation, basic chat screen         |
| `flutter-uikit-quickstart`      | Flutter UI Kit install, init, login, basic chat                    |
| `ios-uikit-quickstart`          | iOS UI Kit (SwiftUI) install, init, login, chat view               |
| `android-uikit-quickstart`      | Android UI Kit (Compose) install, init, login, chat screen         |
| `js-sdk-messaging-basics`       | Vanilla JS SDK install, send/receive text and media messages       |
| `widget-embed`                  | No-code widget embed for an existing site                          |
| `moderation-setup`              | AI moderation, profanity filter, image moderation, webhooks        |
| `multi-tenant-chat`             | Multi-tenant SaaS chat — auth, isolation, tenant-scoped users      |
| `presence-and-typing`           | Online presence, typing indicators, read receipts                  |

### Orientation skill resource

The MCP also exposes a `cometchat://skills/overview` resource — a structured
markdown document the agent reads once to orient itself on CometChat's
products, decision tree, and common pitfalls.

## Source

The MCP server is open-source at
[`github.com/cometchat/cometchat-mcp`](https://github.com/cometchat/docs-mcp).
Built from this very documentation repository, so the content it surfaces
is always in sync with what you see on the docs site.

## Support

Questions, feedback, or feature requests: open an issue on the
[GitHub repository](https://github.com/cometchat/docs-mcp/issues)


# Air-Gapped Deployment
Source: https://www.cometchat.com/docs/on-premise-deployment/docker/air-gapped-deployment

Deploy CometChat on-premise in air-gapped environments with offline images, local registries, certificates, and backup planning.

Guidelines for deploying the platform in offline or isolated (air-gapped) environments.

## Offline installation steps

* Export required Docker images with `docker save`
* Transfer images via removable media, secure copy (SSH), or an isolated internal network
* Import images on the target system with `docker load`

## Local registry

* Host images in Harbor, Nexus, or a private Docker registry
* Enforce role-based access control (RBAC) and image retention policies

## Limitations in air-gapped mode

* No access to external push notification services
* No S3 or other cloud object storage unless internally emulated
* No cloud-hosted analytics, logging, or monitoring integrations

Air-gapped deployments require careful planning for certificate management, image updates, and backup strategies. For assistance with compliance requirements (HIPAA, FedRAMP, ISO 27001) or custom air-gapped architectures, [contact us](https://www.cometchat.com/contact-sales).


# Configuration Reference
Source: https://www.cometchat.com/docs/on-premise-deployment/docker/configuration-reference

Reference CometChat on-premise Docker configuration for domains, service environment variables, CORS, webhooks, and routing.

Use this reference when updating domains, migrating environments, troubleshooting misconfiguration, or performing production deployments. Values are sourced from `docker-compose.yml`, service-level `.env` files, and the domain update guide.

Use this when:

* Updating domains
* Migrating environments
* Troubleshooting service misconfiguration
* Performing production deployments

## Global notes

* All services read environment variables from their respective directories.
* Domain values must be updated consistently across API, WebSocket, Notifications, Webhooks, and NGINX configurations.
* Changing the primary domain impacts reverse proxy routing, OAuth headers, CORS, webhook endpoints, and TiDB host references.

## Chat API

Update these values when changing domains:

* `MAIN_DOMAIN="<your-domain>"`
* `EXTENSION_DOMAIN="<your-domain>"`
* `WEBHOOKS_BASE_URL="https://webhooks.<your-domain>/v1/webhooks"`
* `TRIGGERS_BASE_URL="https://webhooks.<your-domain>/v1/triggers"`
* `EXTENSION_BASE_URL="https://notifications.<your-domain>"`
* `MODERATION_ENABLED=true`
* `RULES_BASE_URL="https://moderation.<your-domain>/v1/moderation-service"`
* `ADMIN_API_HOST="api.<your-domain>"`
* `CLIENT_API_HOST="apiclient.<your-domain>"`
* `ALLOWED_API_DOMAINS="<your-domain>,<additional-domain>"`
* `DB_HOST="tidb.<your-domain>"`

## Management API (MGMT API)

* `ADMIN_API_HOST="api.<your-domain>"`
* `CLIENT_API_HOST="apiclient.<your-domain>"`
* `APP_HOST="dashboard.<your-domain>"`
* `API_HOST="https://mgmt-api.<your-domain>"`
* `MGMT_DOMAIN="<your-domain>"`
* `RULES_BASE_URL="https://moderation.<your-domain>/v1/moderation"`
* `ACCESS_CONTROL_ALLOW_ORIGIN="<your-domain>,<additional-domain>"`

## WebSocket

Hostnames are derived automatically from NGINX and Chat API configuration; no manual domain updates are required.

## Notifications service

* `CHAT_API_DOMAIN="<your-domain>"` (controls routing, token validation, and push delivery)

## Moderation service

* `CHAT_API_URL="<your-domain>"` for rule evaluation, metadata retrieval, and decision submission

## Webhooks service

* `CHAT_API_DOMAIN="<your-domain>"` - must match the Chat API domain exactly to avoid retries or signature verification failures

## Extensions

```json theme={null}
"DOMAINS": [
  "<allowed-domain-1>",
  "<allowed-domain-2>",
  "<your-domain>"
],
"DOMAIN_NAME": "<your-domain>"
```

Defines CORS and allowed origins for extension traffic.

## Receipt Service

* `RECEIPTS_MYSQL_HOST="tidb.<your-domain>"` for delivery receipts, read receipts, and thread metadata

## Data Sync Service

```json theme={null}
"CONNECTION_CONFIG": {
  "host": "<tidb-host>"
},
"ALTER_USER_CONFIG": {
  "host": "<tidb-host>"
},
"API_CONFIG": {
  "API_DOMAIN": "<api-domain>"
}
```

Controls database migrations, multi-tenant provisioning, and internal requests to Chat API.

## NGINX configuration files

Update domain values in:

* chatapi.conf
* extensions.conf
* mgmtapi.conf
* notifications.conf
* dashboard.conf
* globalwebhooks.conf
* moderation.conf
* websocket.conf

These govern TLS termination, routing, reverse proxy rules, and WebSocket upgrades.

## Summary of domain values to update

* Chat API, Client API, and Management API
* Notifications, Moderation, Webhooks, and Extensions services
* NGINX reverse proxy hostnames
* TiDB host references
* WebSocket host configuration in Chat API

Configuration changes should be tested in staging environments before production deployment. For assistance with complex multi-region setups, custom domain architectures, or migration planning, [contact us](https://www.cometchat.com/contact-sales).


# Monitoring
Source: https://www.cometchat.com/docs/on-premise-deployment/docker/monitoring

Monitor CometChat on-premise deployments with Prometheus, Grafana, Loki, Promtail, Node Exporter, and cAdvisor.

Monitoring ensures system health, operational visibility, and SLA compliance for CometChat on-premise deployments.

## Monitoring stack

The following open-source tools form the monitoring and observability stack for CometChat on-premise deployments:

* **Prometheus**: Collects and stores metrics from all services
* **Grafana**: Visualizes metrics with dashboards and alerts
* **Loki**: Stores and queries logs from all containers
* **Promtail**: Tails logs from Docker containers and pushes them to Loki
* **Node Exporter**: Collects host-level metrics (CPU, memory, disk, network)
* **cAdvisor**: Collects container-level resource usage metrics

## Architecture

```mermaid theme={null}
graph TB
    Grafana[Grafana<br/>Dashboards & Visualization]
    Prometheus[Prometheus<br/>Metrics Store]
    Loki[Loki<br/>Log Store]
    NodeExporter[Node Exporter<br/>Host Metrics]
    cAdvisor[cAdvisor<br/>Container Metrics]
    Promtail[Promtail<br/>Log Collection]
    Swarm[Docker Swarm<br/>CometChat Services]
    
    Grafana -->|Query Metrics| Prometheus
    Grafana -->|Query Logs| Loki
    Prometheus -->|Scrape /metrics| NodeExporter
    Prometheus -->|Scrape /metrics| cAdvisor
    Promtail -->|Push Logs| Loki
    NodeExporter -->|Monitor| Swarm
    cAdvisor -->|Monitor| Swarm
    Promtail -->|Collect Logs| Swarm
```

## Key metrics to monitor

### Infrastructure

* CPU usage per node
* Memory usage per node
* Disk space and I/O
* Network traffic
* Container resource usage

### Application services

* WebSocket active connections
* Chat API request rate and latency
* API error rates (4xx, 5xx)
* Service uptime

### Data stores

* **Kafka**: Consumer lag, message throughput
* **Redis**: Memory usage, cache hit ratio, connected clients
* **MongoDB**: Operation latency, connections, replication lag
* **TiDB**: Query duration, region health, storage capacity

### Load balancer

* NGINX request rate
* Response status codes
* Active connections

## Alerting

Alerts should focus on user impact, capacity risks, and data integrity rather than raw metric noise.

Set up alerts for these critical conditions:

* CPU usage > 80% for 5 minutes
* Memory usage > 85% for 5 minutes
* Disk space \< 15%
* Service down for 2 minutes
* Database query latency > 100ms
* Kafka consumer lag > 10,000 messages
* Redis memory > 90%
* WebSocket connection errors > 10/second
* API error rate > 5%
* Container restarts

These thresholds are recommended starting points and should be adjusted based on workload characteristics and environment scale.

## Grafana dashboards

Create dashboards to visualize:

1. **Overview**: System health, active users, request rates, error rates
2. **Infrastructure**: CPU, memory, disk, network per node
3. **WebSocket**: Active connections, message throughput, errors
4. **API**: Request rate, latency, error rates by endpoint
5. **Databases**: Query performance, connections, replication status
6. **Kafka**: Consumer lag, throughput, partition health
7. **Logs & Error Analysis**: Error aggregation, log volume, search, and correlation with metrics

### Logs & Error Analysis Dashboard

This dashboard provides centralized visibility into application errors, log patterns, and system anomalies for rapid troubleshooting and incident investigation.

**Key Visualizations:**

* **Error Volume by Service**: Time-series graph showing error log count per service, helping identify which components are experiencing issues
* **Top Error Messages**: Table displaying the most frequent error messages with occurrence counts, enabling quick identification of recurring problems
* **Log Volume Trends**: Track total log volume over time to detect unusual spikes that may indicate issues or attacks
* **Error Rate by Severity**: Breakdown of errors by severity level (CRITICAL, ERROR, WARNING) for prioritization
* **Service Health Correlation**: Side-by-side view of error logs and service metrics (CPU, memory, latency) to correlate errors with resource constraints
* **Search & Filter**: Interactive LogQL query panel for ad-hoc log searches and pattern matching
* **Recent Critical Errors**: Live feed of the latest critical errors across all services for immediate awareness

## Log queries

Use Loki's LogQL to search and filter logs across all services:

```logql theme={null}
# View all errors
{service="chat-api"} |= "error"

# WebSocket connection issues
{service="websocket"} |~ "connection.*failed"

# API 5xx errors
{service="nginx"} |~ "HTTP/[0-9.]+ 5[0-9]{2}"

# High latency requests
{service="chat-api"} | json | latency > 1000
```

## Troubleshooting

### First check Grafana dashboards

Start with the Overview dashboard to determine blast radius before drilling into component-level dashboards. Confirm whether the issue is node-level, service-level, or data-store related before diving into individual components.

### Check Prometheus targets

```bash theme={null}
curl http://localhost:9090/api/v1/targets
```

### Check Loki status

```bash theme={null}
curl http://localhost:3100/ready
```

### View Promtail logs

```bash theme={null}
docker service logs promtail
```

### Check service metrics

```bash theme={null}
# Node Exporter
curl http://localhost:9100/metrics

# cAdvisor
curl http://localhost:8080/metrics
```


# On-Premise Deployment Overview
Source: https://www.cometchat.com/docs/on-premise-deployment/docker/overview

Deploy CometChat on-premise for self-hosted messaging, data sovereignty, compliance, predictable performance, and enterprise control.

CometChat on-premise delivers an enterprise-grade, self-hosted real-time messaging platform engineered for mission-critical applications requiring complete data sovereignty, regulatory compliance, and predictable performance at scale. Built on battle-tested open-source technologies and cloud-native principles, this deployment architecture supports workloads from 10,000 to 250,000+ monthly active users with linear scalability and sub-100ms message latency.

**This guide covers Docker Swarm deployments.** For Kubernetes deployments (recommended for 200k+ MAU or multi-region requirements), see the [Kubernetes deployment guide](../kubernetes/overview) or [contact us](https://www.cometchat.com/contact-sales) for enterprise support.

**Enterprise Value Proposition**

* **Data Sovereignty**: Complete control over data residency, encryption, and access policies to meet GDPR, HIPAA, SOC 2, and industry-specific compliance requirements
* **Predictable Economics**: Eliminate per-user SaaS pricing with fixed infrastructure costs and transparent capacity planning
* **Operational Control**: Full visibility into system behavior, customizable monitoring, and direct access to all components for troubleshooting and optimization
* **Security Posture**: Deploy within your existing security perimeter with private networks, custom authentication integration, and air-gapped deployment options
* **Performance Guarantees**: Achieve consistent sub-100ms latency with dedicated resources and optimized data locality

## Who this guide is for

This comprehensive deployment guide is designed for technical decision-makers and implementation teams responsible for enterprise infrastructure:

* **DevOps & SRE Teams**: Operations professionals managing production uptime, incident response, capacity planning, and continuous deployment pipelines
* **Platform & Backend Engineers**: Technical leads architecting scalable systems, optimizing performance, and integrating real-time messaging into existing application ecosystems
* **Infrastructure Architects**: Strategic planners designing multi-region deployments, disaster recovery strategies, compliance frameworks, and long-term scalability roadmaps
* **Security & Compliance Officers**: Stakeholders ensuring data protection, access controls, audit logging, and regulatory adherence across all system components

## Platform capabilities

CometChat on-premise provides a comprehensive suite of real-time communication features designed for enterprise applications:

**Core Messaging Infrastructure**

* **1:1 and Group Conversations**: Scalable messaging architecture supporting unlimited conversation threads with persistent message history, rich media attachments, and message threading
* **Real-time Event Streaming**: WebSocket-based bi-directional communication delivering instant presence updates, typing indicators, delivery receipts, read receipts, and custom event propagation
* **Message Delivery Guarantees**: Effectively-once message delivery semantics using idempotent producers, automatic retry logic, offline message queuing, and synchronization across multiple devices

**Enterprise Features**

* **Distributed Event Pipeline**: Apache Kafka-powered event backbone enabling decoupled microservices architecture, guaranteed message ordering, and fault-tolerant event processing at scale
* **Push Notifications**: Multi-provider notification delivery supporting Firebase Cloud Messaging (FCM), Apple Push Notification Service (APNs), and custom webhook integrations with intelligent batching and delivery optimization
* **Content Moderation**: Configurable policy engine with real-time profanity filtering, spam detection, image moderation, and extensible AI/ML adapter framework for custom moderation workflows
* **Webhooks & Integrations**: Reliable outbound event delivery system with configurable retry policies, secure authentication, and comprehensive audit trails for third-party system integration

**API & Developer Experience**

* **RESTful APIs**: Comprehensive HTTP APIs for user management, conversation operations, group administration, metadata queries, and administrative functions with OpenAPI documentation
* **Horizontal Scalability**: Stateless service design enabling linear scaling by adding compute resources without architectural changes or data migration
* **Multi-tenancy Support**: Logical isolation of tenant data with tenant-specific configurations, rate limits, and resource quotas

## Data architecture & storage

The platform employs a polyglot persistence strategy with multiple storage technologies optimized for specific data access patterns and consistency requirements:

**Primary Data Stores**

* **TiDB Cluster**: Horizontally scalable, MySQL-compatible distributed SQL database providing ACID transactions, automatic sharding, and multi-region replication. Composed of three components:
  * **Placement Driver (PD)**: Cluster metadata management and intelligent data placement
  * **TiKV**: Distributed key-value storage engine with Raft consensus for strong consistency
  * **TiDB SQL Layer**: MySQL-compatible query interface with distributed transaction coordination

* **MongoDB**: Document-oriented database optimized for flexible schema evolution and semi-structured data with native JSON support and rich query capabilities

* **Redis Clusters**: Dedicated in-memory data structure stores providing sub-millisecond latency for high-frequency operations:
  * **Cache Cluster**: Application-level caching, query result caching, and frequently accessed data
  * **Session & Rate Limiting Cluster**: User session management, authentication tokens, and distributed rate limiting counters

**Event Streaming Platform**

* **Apache Kafka**: Distributed commit log serving as the central event backbone for asynchronous communication between microservices
  * **Guarantees**: 100% real-time message delivery with sub-second latency, guaranteed message delivery with no message loss, configurable retention policies, and horizontal scalability

**Optional Storage Systems**

* **Object Storage**: S3-compatible storage (Amazon S3, MinIO, Ceph, or Google Cloud Storage) for unstructured data and large binary objects
  * **Features**: Lifecycle policies, versioning, encryption at rest, and cost-optimized storage tiers

**Data Durability & Backup**

* Automated backup strategies with point-in-time recovery capabilities
* Configurable retention policies aligned with compliance requirements

## Deployment models

CometChat on-premise supports multiple deployment architectures to match your operational maturity, scale requirements, and infrastructure preferences:

### Docker Swarm (Recommended: 10k-200k MAU)

**Target Environment**: Production deployments up to \~200,000 monthly active users and \~20,000 peak concurrent connections

**Characteristics**:

* Lightweight orchestration with native Docker integration and minimal operational overhead
* Predictable service placement with node constraints and resource reservations
* Secure overlay networking with encrypted service-to-service communication
* Rolling updates with configurable health checks and automatic rollback capabilities
* Built-in load balancing and service discovery without external dependencies

**Enterprise Benefits**:

* Lower operational complexity compared to Kubernetes while maintaining production-grade reliability
* Faster deployment cycles with straightforward configuration management
* Reduced infrastructure costs with efficient resource utilization
* Proven architecture supporting hundreds of production deployments

**Recommended For**: Mid-market enterprises, SaaS platforms, healthcare applications, financial services, and organizations prioritizing operational simplicity

***

### Kubernetes (Enterprise & Multi-Region)

For large-scale deployments exceeding 200,000 MAU, multi-region architectures, or advanced orchestration requirements, see the [Kubernetes deployment guide](../kubernetes/overview).

## High-level architecture

The CometChat on-premise platform employs a modern, microservices-based architecture designed for enterprise-grade reliability, security, and performance. The system is built on proven open-source technologies and follows cloud-native principles to ensure operational excellence at scale.

<img alt="CometChat On-premise Architecture" />

### Architecture Components

**Client Layer**

* **Desktop Clients**: Native desktop applications and web browsers accessing the platform via HTTPS and WebSocket protocols
* **Mobile Apps**: iOS and Android applications with persistent connections for real-time messaging and push notification support
* **Cloud Services**: Third-party integrations, webhooks consumers, and external systems interfacing with the platform APIs

**Load Balancer**

* Enterprise-grade traffic distribution layer providing high availability, SSL/TLS termination, health checking, and automatic failover across Docker Swarm nodes
* Supports session affinity for WebSocket connections and intelligent routing based on service health metrics

**Docker Swarm Cluster**

The core platform runs within a Docker Swarm orchestration environment, providing service discovery, load balancing, and automated container management.

**Backend Services**

*NGINX Reverse Proxy*

* TLS/SSL termination with configurable cipher suites and certificate management
* HTTP/2 and WebSocket protocol support with automatic upgrade handling
* Request routing to microservices based on URL patterns and headers
* Rate limiting, request buffering, and connection pooling for optimal performance

*Microservices Layer*

* **WebSocket Gateway**: Maintains persistent bi-directional connections for real-time event delivery, presence management, typing indicators, and instant message routing with automatic reconnection and session recovery
* **Chat API Service**: RESTful API handling message CRUD operations, conversation management, user operations, group administration, and metadata queries with transaction support
* **Moderation Service**: Content filtering engine with configurable policies, profanity detection, spam prevention, image moderation, and AI/ML integration for advanced threat detection
* **Notifications Service**: Asynchronous push notification dispatcher supporting FCM, APNs, and custom providers with intelligent batching, retry logic, and delivery tracking
* **Webhooks Service**: Outbound event delivery system with configurable retry policies, exponential backoff, secure authentication, and comprehensive audit logging

**Kafka Event Bus**

* Distributed event streaming platform serving as the central message backbone for inter-service communication
* Provides guaranteed message ordering, fault-tolerant persistence, and horizontal scalability
* Enables decoupled microservices architecture with publish-subscribe and event sourcing patterns
* Handles real-time message routing, event notifications, and asynchronous processing pipelines

**Data Store Components**

**TiDB Cluster (Distributed SQL Database)**

* **Placement Driver (PD)**: Cluster metadata management, timestamp allocation, and intelligent data placement decisions
* **TiKV**: Distributed transactional key-value storage engine with Raft consensus protocol ensuring strong consistency and automatic data replication
* **TiDB SQL Layer**: MySQL-compatible query interface with distributed transaction coordination, supporting ACID guarantees and horizontal scalability

**Redis Clusters**

* Dedicated in-memory data structure stores providing sub-millisecond latency
* **Cache Cluster**: Application-level caching, query result caching, and frequently accessed data
* **Session & Rate Limiting Cluster**: User session management, authentication tokens, and distributed rate limiting counters

**MongoDB**

* Document-oriented database for flexible schema requirements
* Stores moderation policies, user preferences, custom metadata, webhook configurations, and audit logs
* Provides native JSON support and rich query capabilities for semi-structured data

**Frontend Service**

* **Frontend Application**: Web-based administrative dashboard and user interface components

**Monitoring Stack**

* **Prometheus**: Time-series metrics collection system scraping service endpoints, storing performance data, and triggering alerts based on configurable thresholds
* **Grafana**: Visualization platform providing real-time operational dashboards, SLA monitoring, capacity planning insights, and customizable alerting workflows
* **Loki & Promtail**: Centralized log aggregation and querying infrastructure enabling rapid troubleshooting and audit trail analysis
* **Node Exporter & cAdvisor**: Host and container-level metrics collection for infrastructure monitoring and capacity planning

**Infrastructure Layer**

**Host Infrastructure**

* Physical or virtual compute resources running Docker Swarm nodes
* Persistent storage volumes for stateful services (databases, Kafka, logs)
* Resource allocation and isolation using Docker resource constraints

**Private Network**

* Secure overlay network isolating backend services from external access
* Encrypted service-to-service communication using Docker Swarm's built-in encryption
* Network segmentation separating public-facing services from data stores
* Optimized routing paths minimizing inter-service latency and maximizing throughput

***


# Persistence & Backup
Source: https://www.cometchat.com/docs/on-premise-deployment/docker/persistence-and-backup

Plan CometChat on-premise persistence, backups, restore testing, storage requirements, retention, and disaster recovery.

Defines how persistent data is stored, backed up, and restored in production environments. Proper backup and disaster recovery procedures are essential for business continuity and data protection.

**Key Objectives:**

* Protect against data loss from hardware failures, human errors, or disasters
* Enable point-in-time recovery for compliance and operational requirements
* Minimize Recovery Time Objective (RTO) and Recovery Point Objective (RPO)
* Validate backup integrity through regular restore testing

## Volume layout

Docker volumes provide persistent storage for stateful services. Each service stores data at specific mount points within containers:

| Service | Default path          | Data stored                           |
| ------- | --------------------- | ------------------------------------- |
| TiKV    | `/data`               | Distributed key-value data, Raft logs |
| PD      | `/data`               | Cluster metadata, timestamp oracle    |
| Kafka   | `/var/lib/kafka/data` | Message logs, topic partitions        |
| Redis   | `/data`               | Cache data, session state             |
| MongoDB | `/data/db`            | Document collections, indexes         |

**Storage requirements:**

* All persistent volumes should be backed by SSD or NVMe storage for production deployments
* Provision adequate IOPS for database workloads (minimum 3000 IOPS for TiKV)
* Monitor disk space usage and set alerts at 75% capacity
* Plan for 30-50% growth buffer beyond current usage

## Backup strategy

Implement automated, regular backups for all stateful services with appropriate retention policies:

### TiDB backups

**Frequency**: Daily full backups, hourly incremental backups (for critical deployments)

**Method**: Use TiDB BR (Backup & Restore) tool for consistent cluster snapshots

```bash theme={null}
# Full backup
tiup br backup full \
  --pd <pd-address>:2379 \
  --storage "local:///backup/$(date +%Y%m%d)" \
  --ratelimit 120 \
  --log-file backup.log

# Incremental backup
tiup br backup incremental \
  --pd <pd-address>:2379 \
  --storage "local:///backup/incremental/$(date +%Y%m%d_%H%M)" \
  --lastbackupts <last-backup-timestamp>
```

**Storage**: Secure, off-cluster storage (S3, NFS, or dedicated backup server)

**Retention**: 30 days for daily backups, 90 days for monthly backups (adjust based on compliance requirements)

### Kafka backups

**Frequency**: Weekly segment-level backups

**Method**: Copy Kafka data directories or use MirrorMaker for replication to backup cluster

```bash theme={null}
# Stop Kafka broker (if taking offline backup)
docker service scale kafka=0

# Backup Kafka data directory
tar -czf kafka-backup-$(date +%Y%m%d).tar.gz /var/lib/kafka/data

# Restart Kafka broker
docker service scale kafka=1
```

**⚠️ Warning**: Stopping Kafka brokers will interrupt message delivery. Perform offline backups only during maintenance windows.

**Retention**: 4 weeks (Kafka data is typically transient with configurable retention)

### MongoDB backups

**Frequency**: Daily backups

**Method**: Use mongodump for logical backups or filesystem snapshots for physical backups

```bash theme={null}
# Logical backup with mongodump
# Ensure mongodump uses a read-only backup user with minimal privileges
docker exec mongodb mongodump \
  --out /backup/mongodb-$(date +%Y%m%d) \
  --gzip

# Copy backup to secure storage
docker cp mongodb:/backup/mongodb-$(date +%Y%m%d) /secure/backup/location/
```

**Retention**: 30 days for daily backups, 1 year for monthly backups

### Redis backups

**Frequency**: RDB snapshots every 6 hours

**Method**: Redis automatically creates RDB snapshots based on configuration

```bash theme={null}
# Trigger manual snapshot
docker exec redis redis-cli BGSAVE

# Copy RDB file to backup location
docker cp redis:/data/dump.rdb /backup/redis-$(date +%Y%m%d_%H%M).rdb
```

**Note**: Redis data is non-authoritative and can be safely rebuilt from TiDB and Kafka in most scenarios. Backups are primarily for faster recovery rather than data preservation.

**Retention**: 7 days (cache data has short-term value)

### Backup validation

**Monthly restore tests**: Perform full restore to staging environment to verify backup integrity

```bash theme={null}
# Example: Restore TiDB backup
tiup br restore full \
  --pd <staging-pd-address>:2379 \
  --storage "local:///backup/20240119" \
  --log-file restore.log

# Verify data integrity
# Run application smoke tests against restored data
```

**Validation checklist**:

* Backup files are complete and not corrupted
* Restore process completes without errors
* Data integrity checks pass (row counts, checksums)
* Application can connect and query restored data
* Restore time meets RTO requirements

## Disaster recovery

Establish comprehensive disaster recovery procedures to ensure business continuity in the event of catastrophic failures.

### Recovery objectives

Define clear recovery targets based on business requirements:

* **RTO (Recovery Time Objective)**: Maximum acceptable downtime (typically 1-4 hours for production systems)
* **RPO (Recovery Point Objective)**: Maximum acceptable data loss (typically 1-24 hours depending on backup frequency)

**Note**: Actual RTO/RPO depends on backup size, network bandwidth, and restore automation maturity. Test and validate your specific recovery times.

### Disaster recovery procedures

**Full cluster restoration from backups:**

1. **Provision new infrastructure** matching production specifications

2. **Restore data stores** in dependency order:
   * TiDB/TiKV (primary data store) - Restore TiDB first as it is the authoritative source of user, conversation, and message metadata
   * MongoDB (metadata and configuration)
   * Kafka (if message history is critical)
   * Redis (optional, can rebuild from primary data)

3. **Restore application services** and verify connectivity

4. **Validate data integrity** through application smoke tests

5. **Update DNS** to point to new cluster

6. **Monitor closely** for 24-48 hours post-recovery

**Example TiDB restore:**

```bash theme={null}
# Restore TiDB cluster from backup
tiup br restore full \
  --pd <new-pd-address>:2379 \
  --storage "s3://backup-bucket/20240119" \
  --log-file restore.log

# Verify cluster health
tiup cluster display <cluster-name>

# Run data integrity checks
# Check row counts, run application queries
```

### Geographic redundancy

**Backup storage locations:**

* Maintain a minimum of three geographically isolated backup copies
* Primary backup: Same region as production (fast recovery)
* Secondary backup: Different region (regional disaster protection)
* Tertiary backup: Different cloud provider or on-premiseises (provider-level disaster protection)

**Important**: Ensure backups are completed and verified before object storage lifecycle rules expire older snapshots.

**Replication strategies:**

* Use cloud storage replication (S3 cross-region replication, GCS multi-region)
* Implement backup verification at each location
* Test restore from each backup location quarterly

### Disaster recovery testing

**Quarterly DR simulations:**

Run staged disaster recovery exercises to validate procedures and train teams:

1. **Warm-standby restoration**: Restore to standby environment, validate without cutting over
2. **Full cluster rehydration**: Complete restore from backups in isolated environment
3. **Failover testing**: Practice DNS cutover and traffic migration procedures
4. **Rollback testing**: Validate ability to roll back to previous state if needed

**DR drill checklist:**

* [ ] Backup files are accessible from all locations
* [ ] Restore procedures are documented and up-to-date
* [ ] Team members know their roles and responsibilities
* [ ] Communication channels are established
* [ ] Restore time meets RTO requirements
* [ ] Data integrity is validated post-restore
* [ ] Application functionality is verified
* [ ] Lessons learned are documented and procedures updated

### Backup security

**Encryption:**

* Encrypt backups at rest using AES-256 or equivalent
* Encrypt backups in transit using TLS
* Store encryption keys separately from backup data (use key management service)

**Access control:**

* Restrict backup access to authorized personnel only
* Use separate credentials for backup operations
* Audit all backup access and modifications
* Implement multi-factor authentication for backup system access


# Prerequisites
Source: https://www.cometchat.com/docs/on-premise-deployment/docker/prerequisites

Review CometChat on-premise prerequisites for hardware sizing, Linux versions, Docker, network planning, and storage.

This guide outlines the infrastructure, software, and network requirements for deploying CometChat on-premise. Proper capacity planning ensures optimal performance, cost efficiency, and scalability as your user base grows.

**Planning Considerations:**

* **Hardware Sizing**: Select appropriate compute and storage resources based on expected monthly active users (MAU) and peak concurrent connections (PCC)
* **Operating System**: Choose enterprise-grade Linux distributions with long-term support
* **Network Architecture**: Plan for secure network segmentation and firewall configurations
* **Storage Strategy**: Account for data retention policies, backup requirements, and growth projections

## Supported operating systems

CometChat on-premise is tested and supported on enterprise Linux distributions with long-term support (LTS) and security updates:

* **Ubuntu 20.04 / 22.04 / 24.04 LTS**: Recommended for most deployments with 5-year support lifecycle
* **RedHat Enterprise Linux 8+**: Ideal for enterprises requiring commercial support and compliance certifications

**Why these distributions:**

* Long-term security updates and kernel patches
* Docker and container runtime compatibility
* Enterprise support availability
* Proven stability in production environments

## Required software

Ensure these software dependencies are installed before deployment:

* **Docker Engine >= 24**: Container runtime for service orchestration
* **Docker Compose v2**: Required for local development and non-Swarm workflows
* **Git**: Version control for deployment scripts and configuration management
* **OpenSSL >= 1.1**: TLS/SSL certificate generation and cryptographic operations
* **jq, curl, net-tools**: Command-line utilities for configuration, API testing, and network diagnostics

**Installation Note**: The quick start guide includes automated installation scripts for Docker and Docker Compose on Ubuntu systems.

## Minimum hardware (testing / QA)

For development, testing, and proof-of-concept environments:

* **8 vCPUs**: Sufficient for running all services with light load
* **16 GB RAM**: Minimum memory for core services and data stores
* **100 GB SSD**: Base storage for application data and logs (scale up based on workload and storage needs)

**Important**: This configuration is not suitable for production workloads or performance testing at scale.

## Production hardware

Production sizing is based on two key metrics: **Monthly Active Users (MAU)** and **Peak Concurrent Connections (PCC)**. Choose the sizing model that matches your expected usage patterns.

**Important**: The values below represent total cluster capacity and can be distributed across multiple nodes.

### Baseline sizing

Recommended for standard usage patterns where peak concurrent connections are approximately 5% of MAU:

| MAU  | Peak concurrent connections (PCC) | vCPUs | RAM     |
| ---- | --------------------------------- | ----- | ------- |
| 10k  | 500                               | 32    | 64 GiB  |
| 25k  | 1,250                             | 64    | 128 GiB |
| 50k  | 2,500                             | 96    | 192 GiB |
| 100k | 5,000                             | 156   | 312 GiB |
| 200k | 10,000                            | 272   | 544 GiB |

**Storage guidance**: Start at 100 GB SSD and scale to 500 GB to 2 TB SSD depending on workload and data retention policies.

### High-concurrency sizing

Recommended for applications with sustained high concurrency where peak connections reach 10% or more of MAU:

| MAU  | Peak concurrent connections (PCC) | vCPUs | RAM     |
| ---- | --------------------------------- | ----- | ------- |
| 10k  | 1,000                             | 48    | 96 GiB  |
| 25k  | 2,500                             | 96    | 192 GiB |
| 50k  | 5,000                             | 156   | 312 GiB |
| 100k | 10,000                            | 240   | 480 GiB |
| 200k | 20,000                            | 480   | 960 GiB |

**Storage guidance**: Expect to exceed 100 GB SSD; plan 500 GB to 2 TB SSD as concurrency and data volume grow.

### Storage planning considerations

**Factors affecting storage requirements:**

* **Message retention**: Longer retention periods require more storage
* **Media attachments**: Images, videos, and files significantly increase storage needs
* **Backup strategy**: Plan for 2-3x storage capacity to accommodate backups
* **Log retention**: Compliance requirements may mandate extended log retention (30-90 days or more)
* **Growth buffer**: Allocate 30-50% additional capacity for unexpected growth

**Storage performance**: Use SSD or NVMe storage for all production deployments to ensure optimal database and Kafka performance.

## Required ports

Configure firewall rules to allow traffic on these ports:

* **80 / 443**: HTTP and HTTPS traffic to NGINX (public-facing). Port 80 should be used only for HTTP-to-HTTPS redirection.

**Network security recommendations:**

* Restrict ports 80/443 to known IP ranges when possible
* Use TLS/SSL certificates for all HTTPS traffic
* Keep all backend services (databases, Kafka, Redis) on private networks without public exposure
* Implement rate limiting and DDoS protection at the load balancer level

**Additional ports for internal communication:**
All inter-service communication occurs on Docker Swarm's private overlay network and does not require external firewall rules. Services communicate securely within the cluster using Docker's encrypted overlay networking.


# Production Deployment
Source: https://www.cometchat.com/docs/on-premise-deployment/docker/production-deployment

Deploy CometChat on-premise to Docker Swarm with TLS, domains, service orchestration, health checks, and rollout steps.

This guide walks through deploying CometChat on-premise to a Docker Swarm cluster. The deployment process uses automated scripts to ensure consistent, repeatable deployments with proper service orchestration and zero-downtime updates.

**Deployment Overview:**

* Initialize Docker Swarm cluster for container orchestration
* Deploy all services using infrastructure-as-code approach
* Configure domain mappings and TLS certificates
* Validate deployment health across all components
* Establish operational procedures for updates and maintenance

**Prerequisites:**

* Infrastructure meeting [hardware requirements](./prerequisites)
* Docker Engine >= 24 installed on all nodes
* Network connectivity between cluster nodes
* Domain names configured and DNS records pointing to your cluster
* TLS/SSL certificates for HTTPS endpoints

## Initialize Docker Swarm (manager node)

Docker Swarm provides native clustering and orchestration for Docker containers. Initialize Swarm on your primary manager node:

```bash theme={null}
# Initialize Swarm cluster
docker swarm init

# For hosts with multiple network interfaces, specify the advertise address
docker swarm init --advertise-addr <manager-ip>

# Verify cluster status
docker node ls
```

**Expected output**: You should see one node listed with STATUS "Ready" and MANAGER STATUS showing "Leader".

**Multi-node clusters:**
For high availability, add additional manager and worker nodes:

```bash theme={null}
# On manager node: Get join token for additional managers
docker swarm join-token manager

# On manager node: Get join token for worker nodes
docker swarm join-token worker

# On additional nodes: Run the join command provided above
docker swarm join --token <token> <manager-ip>:2377
```

**High availability recommendations:**

* Deploy 3 or 5 manager nodes (odd numbers for quorum)
* Distribute manager nodes across availability zones when possible
* Use worker nodes for application workloads, managers for orchestration only

## Clone the repository

Clone the CometChat on-premise repository to access deployment scripts and configuration files:

```bash theme={null}
git clone https://github.com/cometchat/cometchat-on-premise.git
cd cometchat-on-premise
```

To access the repository, [contact us](https://www.cometchat.com/contact-sales).

## Deploy the complete infrastructure

Run the following from the repository root on the Swarm manager node:

```bash theme={null}
./deploy.sh
```

**What the deployment script does:**

1. Initializes required Docker volumes for persistent data
2. Creates secure overlay networks for service communication
3. Deploys all services defined in `docker-compose.yml` with proper dependencies
4. Starts components in the correct order (data stores → backend services → frontend)
5. Applies health checks and restart policies

**Deployment time**: Initial deployment typically takes 5-10 minutes depending on image pull speeds and cluster size.

**Monitoring deployment progress:**

```bash theme={null}
# Watch service deployment status
watch docker service ls

# Check specific service deployment
docker service ps <service-name>

# View service logs during deployment
docker service logs -f <service-name>
```

**Deployment validation:**
After deployment completes, verify all services are running:

```bash theme={null}
# All services should show replicas as "X/X" (e.g., "1/1" or "3/3")
docker service ls

# Check for any failed services
docker service ls | grep "0/"
```

## NGINX reverse proxy

NGINX serves as the edge layer, handling TLS termination, API routing, WebSocket protocol upgrades, and proxy buffering for optimal performance.

**Configuration files to update:**

Each service has a dedicated NGINX configuration file that must be updated with your production domain:

* `chatapi.conf` - Chat API routing and WebSocket upgrade rules
* `extensions.conf` - Extensions API routing
* `mgmtapi.conf` - Management API routing
* `notifications.conf` - Notifications service routing
* `dashboard.conf` - Frontend dashboard routing
* `globalwebhooks.conf` - Webhooks service routing
* `moderation.conf` - Moderation service routing
* `websocket.conf` - WebSocket gateway routing

**Key NGINX responsibilities:**

* **TLS/SSL Termination**: Decrypt HTTPS traffic at the edge, communicate with backend services over encrypted overlay network
* **Load Balancing**: Distribute requests across service replicas using round-robin or least-connections algorithms
* **WebSocket Upgrades**: Handle HTTP to WebSocket protocol upgrades for real-time connections
* **Request Buffering**: Buffer client requests to protect backend services from slow clients
* **Rate Limiting**: Protect services from abuse and DDoS attacks (configure as needed)

**TLS certificate configuration:**
Place your TLS certificates in the NGINX configuration directory and reference them in each `.conf` file:

```nginx theme={null}
ssl_certificate /path/to/your/certificate.crt;
ssl_certificate_key /path/to/your/private.key;
```

**Important**: Reload NGINX after updating certificates to apply changes without downtime:

```bash theme={null}
docker service update --force nginx
```

**Security recommendations:**

* Use TLS 1.2 or higher only
* Configure strong cipher suites
* Enable HSTS (HTTP Strict Transport Security)
* Implement rate limiting for public endpoints

## Domain configuration

Deployments require updating domain references across multiple services and configuration files. Replace all instances of `<your-domain>` with your actual domain.

**Services requiring domain configuration:**

* Chat API - Core messaging service endpoints
* Management API - Administrative and configuration endpoints
* Extensions - Custom extension endpoints
* Notifications - Push notification service
* Moderation - Content moderation service
* Webhooks - Outbound webhook delivery
* Data Sync Service - Data synchronization
* NGINX - Reverse proxy routing rules

**Critical alignment:**
Ensure the WebSocket host configured in Chat API matches your chosen domain exactly (e.g., `websocket.chat.example.com`). Mismatched domains will cause WebSocket connection failures.

**Configuration checklist:**

1. Update all service environment variables with your domains
2. Update NGINX configuration files with matching domains
3. Verify DNS records point to your cluster load balancer
4. Configure TLS certificates for all public-facing domains
5. Test domain resolution from external networks

**Example domain structure:**

```
api.example.com          → Chat API
apiclient.example.com    → Client API
apimgmt.example.com      → Management API
websocket.example.com    → WebSocket Gateway
notifications.example.com → Notifications Service
webhooks.example.com     → Webhooks Service
moderation.example.com   → Moderation Service
app.example.com          → Dashboard
```

**Note**: Ensure consistency across all configuration files and DNS records.

For detailed environment variable mappings, see the [Configuration Reference](./configuration-reference).

## Useful commands (Swarm operations)

### General service management

```bash theme={null}
# List all nodes in the cluster
docker node ls

# List all services and their status
docker service ls

# View detailed service information
docker service inspect <service-name>

# Check service replica status and placement
docker service ps <service-name>

# Follow service logs in real-time
docker service logs -f <service-name>

# Execute command in a service container
docker exec -it <container-id> bash

# Drain a node for maintenance (stops scheduling new tasks)
docker node update --availability drain <node-name>

# Return node to active status
docker node update --availability active <node-name>

# Scale a service to more replicas
docker service scale <service-name>=3
```

### Stack operations

```bash theme={null}
# Deploy or update entire stack
docker stack deploy -c docker-compose.yml cometchat

# Remove entire stack (WARNING: destructive)
docker stack rm cometchat

# List all services in a stack
docker stack services cometchat

# List all tasks in a stack
docker stack ps cometchat

# View stack configuration
docker stack config -c docker-compose.yml
```

### Troubleshooting commands

```bash theme={null}
# View service events and errors
docker service ps <service-name> --no-trunc

# Inspect service configuration
docker service inspect <service-name> --pretty

# Check service update status
docker service inspect <service-name> --format='{{json .UpdateStatus}}'

# View container resource usage
docker stats

# Inspect network configuration
docker network inspect <network-name>

# View volume information
docker volume ls
docker volume inspect <volume-name>
```

## Health check endpoints

After deployment, verify all services are healthy by checking their health endpoints:

| Component      | URL                                                     |
| -------------- | ------------------------------------------------------- |
| Dashboard      | `https://app.example.com`                               |
| Chat API       | `https://api.example.com/health-check`                  |
| Client API     | `https://apiclient.example.com/health-check`            |
| Management API | `https://apimgmt.example.com/health-check`              |
| Notifications  | `https://notifications.example.com/health-check`        |
| Moderation     | `https://rule.example.com/health`                       |
| WebSocket      | `https://websocket.example.com/v1/health`               |
| Webhooks       | `https://webhooks.example.com/v1/webhooks/health-check` |

Replace `example.com` with your actual domain.

**Health check validation:**

```bash theme={null}
# Check all health endpoints
curl -f https://api.example.com/health-check || echo "Chat API unhealthy"
curl -f https://websocket.example.com/v1/health || echo "WebSocket unhealthy"
curl -f https://notifications.example.com/health-check || echo "Notifications unhealthy"
```

**Expected responses:**

* HTTP 200 status code indicates healthy service
* HTTP 503 or connection errors indicate service issues requiring investigation

**Automation**: Health checks should be integrated into monitoring and automated validation scripts. See the [Monitoring](./monitoring) guide for comprehensive health monitoring setup.


# Scaling
Source: https://www.cometchat.com/docs/on-premise-deployment/docker/scaling

Scale CometChat on-premise deployments with vertical tuning, horizontal replicas, capacity planning, and performance thresholds.

Guidelines for scaling platform components based on load and resource requirements. Proper scaling ensures optimal performance, cost efficiency, and user experience as your deployment grows.

**Scaling Strategies:**

* **Vertical scaling**: Increase resources (CPU, RAM, storage) on existing nodes
* **Horizontal scaling**: Add more service replicas or nodes to distribute load
* **Capacity planning**: Proactively scale based on growth projections and monitoring data

**When to scale:**

* CPU utilization consistently above 70%
* Memory usage approaching 85%
* API latency exceeding SLA targets (P95 > 100ms)
* WebSocket connection limits approaching capacity
* Database query performance degrading

## Vertical scaling

Increase system resource limits and tune configurations to handle more load on existing servers. Vertical scaling is often the first step before adding more nodes.

**Benefits:**

* Simpler than horizontal scaling (no distributed system complexity)
* Immediate performance improvement
* Lower operational overhead

**Limitations:**

* Hardware limits (maximum CPU, RAM per server)
* Single point of failure remains
* Downtime required for hardware upgrades

**Key optimizations:**

* Raise file descriptor limits for high-concurrency workloads
* Tune kernel network queues (`somaxconn`, `netdev_max_backlog`)
* Increase worker processes and thread pools where supported
* Allocate more CPU and memory to Docker services

### Configure file descriptor limits

1. Edit `/etc/security/limits.conf` and add:

```
* soft nofile 500000
* hard nofile 500000
root soft nofile 500000
root hard nofile 500000
```

2. Configure systemd defaults:

```bash theme={null}
echo "DefaultLimitNOFILE=500000" | sudo tee -a /etc/systemd/system.conf
echo "DefaultLimitNOFILE=500000" | sudo tee -a /etc/systemd/user.conf
```

3. Reboot to apply changes:

```bash theme={null}
sudo reboot
```

4. Verify:

```bash theme={null}
ulimit -n
```

### Allocate more resources to Docker services

Increase CPU and memory limits for services experiencing resource constraints:

```bash theme={null}
# Update service resource limits
docker service update \
  --limit-cpu 4 \
  --limit-memory 8G \
  chat-api

# Verify updated limits
docker service inspect chat-api --format='{{.Spec.TaskTemplate.Resources.Limits}}'
```

## Horizontal scaling

Add more service replicas or nodes to distribute load across multiple servers. Horizontal scaling provides better fault tolerance and unlimited growth potential.

**Note:** Docker Swarm supports horizontal scaling through manual commands. Unlike Kubernetes, which offers automatic scaling based on metrics (HPA/VPA), Docker Swarm requires you to manually scale services using the commands below. Monitor your metrics and scale proactively based on load patterns.

### Scaling application services

**WebSocket Gateway:**

* **Scaling ratio**: Add \~1 replica per 1,000-1,500 peak concurrent connections (PCC)
* **Command**: `docker service scale websocket=5`
* **Considerations**: Ensure load balancer distributes connections evenly; sticky sessions if needed are typically handled at the NGINX layer using IP hash or consistent hashing

**Chat API:**

* **Scaling trigger**: Scale out when average CPU utilization exceeds \~60%
* **Command**: `docker service scale chat-api=5`
* **Considerations**: Stateless design allows unlimited horizontal scaling

**Notifications Service:**

* **Scaling trigger**: High push notification queue depth or processing delays
* **Command**: `docker service scale notifications=3`

**Webhooks Service:**

* **Scaling trigger**: Webhook delivery delays or high retry rates
* **Command**: `docker service scale webhooks=3`

### Scaling data stores

**Kafka:**

* **Scaling method**: Increase partition count to improve throughput and parallelism
* **Command**:
  ```bash theme={null}
  kafka-topics --alter --topic <topic-name> \
    --partitions <new-partition-count> \
    --bootstrap-server <kafka-broker>
  ```
* **Considerations**: More partitions = more parallelism, but also more overhead; balance based on workload. Avoid frequent partition changes during peak traffic to prevent rebalance storms.

**Redis:**

* **Scaling trigger**: Enable Redis Cluster mode when deployments exceed \~200k MAU
* **Benefits**: Distributes data across multiple nodes, improves scalability and fault tolerance
* **⚠️ Warning**: Redis Cluster mode is not backward-compatible with standalone Redis. Migration requires application awareness and careful testing.

**TiDB/TiKV:**

* **Scaling method**: Add more TiKV nodes to distribute data and increase storage capacity
* **Command**: Add nodes to cluster using TiUP
* **Considerations**: TiDB automatically rebalances data across new nodes

**MongoDB:**

* **Scaling method**: Enable sharding for horizontal data distribution
* **⚠️ Warning**: Shard key selection is critical and effectively irreversible. Poor shard keys can cause uneven data distribution and performance issues.

### Monitoring scaling effectiveness

After scaling, monitor these metrics to validate improvements:

* **CPU and memory utilization**: Should decrease proportionally
* **API latency**: P95 and P99 should improve
* **Error rates**: Should remain stable or decrease
* **Throughput**: Requests per second should increase
* **Connection counts**: Should distribute evenly across replicas

**Important**: If metrics do not improve within 10–15 minutes, reassess scaling assumptions or investigate downstream bottlenecks.

## When to migrate to Kubernetes

Docker Swarm is recommended for most deployments up to \~200k MAU. Consider migrating to Kubernetes when you need advanced orchestration features or exceed Swarm's practical limits.

**Kubernetes migration triggers:**

* **Scale**: MAU exceeds \~200k or peak concurrent connections exceed \~20k
* **Multi-region**: You need active-active deployments across multiple geographic regions
* **Latency requirements**: Sub-50ms latency targets requiring advanced traffic management
* **Autoscaling**: Dynamic autoscaling based on custom metrics (HPA/VPA) is critical
* **Service mesh**: You need mTLS, advanced traffic routing, or observability features (Istio, Linkerd)
* **Cloud-native tooling**: You want to leverage Kubernetes-native tools and operators

**Kubernetes benefits:**

* Unlimited horizontal scalability with automated capacity management
* Advanced autoscaling (Horizontal Pod Autoscaler, Vertical Pod Autoscaler)
* Multi-region active-active deployments with global load balancing
* Service mesh integration for mTLS and advanced traffic management
* Rich ecosystem of operators and tools (Kafka operators, database operators)
* GitOps workflows for declarative infrastructure management

**Migration considerations:**

* Higher operational complexity and learning curve
* More infrastructure overhead (control plane, etcd, etc.)
* Requires Kubernetes expertise on the team
* Migration effort for existing deployments

**Next steps for Kubernetes:**

Our solutions team provides Kubernetes reference architectures, migration planning, and ongoing operational guidance tailored to your specific requirements.

**Contact Enterprise Solutions:**

For Kubernetes reference architectures, migration planning, and ongoing operational guidance tailored to your specific requirements, [contact us](https://www.cometchat.com/contact-sales).

**What to prepare:**

* Current or projected MAU and PCC
* Geographic distribution requirements
* Compliance requirements (GDPR, HIPAA, SOC 2)
* Existing infrastructure and Kubernetes experience
* Timeline and deployment goals

For detailed Kubernetes deployment information, see the [Kubernetes Overview](../kubernetes/overview).


# Security
Source: https://www.cometchat.com/docs/on-premise-deployment/docker/security

Secure CometChat on-premise deployments with JWT authentication, secrets management, TLS, network isolation, and abuse controls.

Security controls focus on authentication, secrets management, network isolation, TLS posture, and protective controls against abuse.

## Authentication

Use JWT-based authentication with RSA key pairs so only authorized users interact with the platform.

Actionable steps:

* Generate an RSA key pair (example):

```bash theme={null}
openssl genpkey -algorithm RSA -out private.key -pkeyopt rsa_keygen_bits:3072
openssl rsa -pubout -in private.key -out public.key
```

* Validate JWTs in your backend with the public key.
* Rotate signing keys every 30-90 days for long-running deployments.

## Secrets management

Centralize and encrypt sensitive data such as passwords, API keys, database credentials, and tokens. Avoid storing secrets directly in environment variables or committing them to configuration files. Use secrets managers or mounted secret files instead.

### HashiCorp Vault (recommended for enterprise)

Vault provides enterprise-grade secrets management with RBAC, audit logging, and encrypted storage:

**Key features:**

* Dynamic secrets with automatic rotation
* Fine-grained access control policies
* Comprehensive audit trails for compliance
* Encryption as a service
* Multi-cloud and hybrid support

**Basic usage:**

```bash theme={null}
# Store a secret
vault kv put secret/database/password value="your-secure-password"

# Retrieve a secret
vault kv get secret/database/password

# Rotate a secret
vault kv put secret/database/password value="new-secure-password"
```

**Integration with applications:**

* Use Vault APIs or client libraries to retrieve secrets at runtime
* Implement automatic secret rotation without service restarts
* Configure lease durations and renewal policies
* Enable audit logging for all secret access

### Docker Swarm secrets

For simpler deployments, use Docker Swarm's built-in secrets management:

**Create and use secrets:**

```bash theme={null}
# Create a secret from stdin
echo "your-secure-password" | docker secret create db_password -

# Create a secret from file
docker secret create tls_cert ./certificate.crt

# List secrets
docker secret ls

# Use secret in service
docker service create \
  --name myservice \
  --secret db_password \
  myimage:latest
```

**Access secrets in containers:**
Secrets are mounted as files in `/run/secrets/` directory:

```bash theme={null}
# Read secret in application
cat /run/secrets/db_password
```

**Security properties:**

* Encrypted in transit and at rest
* Only accessible to authorized services
* Automatically removed when service is deleted
* Immutable (must delete and recreate to update)

### Best practices

* **Principle of least privilege**: Grant secrets access only to services that need them
* **Regular rotation**: Rotate secrets on a defined schedule (30-90 days)
* **Audit logging**: Monitor and log all secret access for security analysis
* **Backup and recovery**: Maintain secure backups of secrets management systems
* **Separation of duties**: Require multiple approvals for sensitive secret operations

## Network security

Run backend services on private overlay networks and expose only NGINX to the internet.

Actionable steps:

* Create a private overlay network:

```bash theme={null}
docker network create --driver overlay private_network
```

* Harden firewall rules to allow only the necessary ports (80/443) and block the rest. Apply firewall rules at the host or network perimeter level, not inside containers:

```bash theme={null}
sudo ufw allow 80,443/tcp
sudo ufw default deny incoming
sudo ufw enable
```

## TLS configuration

Encrypt all traffic with modern TLS protocols and strong cipher suites.

### NGINX TLS configuration

Configure NGINX with security best practices:

```nginx theme={null}
# Use only modern TLS versions
ssl_protocols TLSv1.2 TLSv1.3;

# Strong cipher suites (prioritize forward secrecy)
ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305';
ssl_prefer_server_ciphers off;

# Enable HSTS (HTTP Strict Transport Security)
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

# Disable SSL session tickets for better security
ssl_session_tickets off;

# OCSP stapling for certificate validation
ssl_stapling on;
ssl_stapling_verify on;
resolver 8.8.8.8 8.8.4.4 valid=300s;  # Use internal DNS resolvers where required by corporate security policies
resolver_timeout 5s;

# DH parameters for forward secrecy
ssl_dhparam /path/to/dhparam.pem;
```

### Certificate management

**Obtain certificates:**

* **Let's Encrypt**: Free, automated certificates with 90-day validity
* **Commercial CA**: Extended validation (EV) certificates for enterprise trust
* **Internal CA**: For internal services and development environments

**Certificate rotation strategy:**

```bash theme={null}
# Generate DH parameters (one-time, takes several minutes)
openssl dhparam -out /etc/nginx/dhparam.pem 2048

# Maintain multiple certificates for zero-downtime rotation
# 1. Obtain new certificate
# 2. Update NGINX configuration with new certificate path
# 3. Test configuration
nginx -t

# 4. Reload NGINX (zero downtime)
docker service update --force nginx
```

**Automation with Let's Encrypt:**

* Use Certbot or similar tools for automatic renewal
* Configure renewal hooks to reload NGINX after certificate updates
* Monitor certificate expiration dates (alert 30 days before expiry)

### Internal service encryption

**Docker Swarm overlay network encryption:**

```bash theme={null}
# Create encrypted overlay network
docker network create \
  --driver overlay \
  --opt encrypted \
  secure_backend
```

**Benefits:**

* Automatic encryption of all inter-service communication
* No application code changes required
* Protects against network sniffing within the cluster

**Database connections:**

* Enable TLS for TiDB, MongoDB, and Redis connections
* Use certificate-based authentication where supported
* Encrypt backup data in transit and at rest

## Additional security measures

* Rate limiting: protect against abuse or DDoS using NGINX rate limits. Tune rate limits based on expected traffic patterns to avoid impacting legitimate users:

```nginx theme={null}
limit_req_zone $binary_remote_addr zone=mylimit:10m rate=10r/s;
limit_req zone=mylimit burst=20;
```

* IP allowlisting: restrict access to sensitive services:

```bash theme={null}
sudo ufw allow from 192.168.1.0/24 to any port 3306
```

* Log monitoring: collect and monitor logs (e.g., Prometheus alerts, Grafana dashboards, ELK/Loki) to detect suspicious activity.


# Troubleshooting
Source: https://www.cometchat.com/docs/on-premise-deployment/docker/troubleshooting

Troubleshoot CometChat on-premise Docker issues with 502 errors, Kafka lag, Redis eviction, TiKV errors, and service logs.

Common operational issues and debugging guidance.

## Common problems and likely causes

### 502 errors

* Possible cause: Chat API unreachable or unhealthy behind NGINX.
* Resolution:
  * Ensure the Chat API service is running: `docker service ps <chat-api-service>`
  * Check NGINX logs and upstream configuration to verify routing and upstream health.

### Kafka lag

* Possible cause: Consumer slowdown or insufficient partition count.
* Resolution:
  * Check Kafka consumer lag: `kafka-consumer-groups --describe --group <your-consumer-group> --bootstrap-server <kafka-broker>`
  * Increase partitions if needed: `kafka-topics --alter --partitions <new-partition-count> --topic <your-topic> --bootstrap-server <kafka-broker>`

### Redis eviction

* Possible cause: Memory pressure or incorrect eviction policy.
* Resolution:
  * Inspect memory settings: `redis-cli config get maxmemory` and `redis-cli config get maxmemory-policy`
  * Set an eviction policy such as `redis-cli config set maxmemory-policy allkeys-lru`

### TiKV region errors

* Possible cause: Disk latency, resource contention, or store imbalance.
* Resolution:
  * Check TiKV store status: `tiup cluster display`
  * Rebalance regions if needed: `tiup cluster restart <cluster-name> --force`

## Debugging commands

### Container and Swarm diagnostics

* View container logs: `docker logs <container-name>`
* Check service status: `docker service ps <service-name>`
* Inspect container details: `docker inspect <container-name>`

### TiDB cluster status

* Display cluster status with TiUP: `tiup cluster display <cluster-name>`


# Upgrades
Source: https://www.cometchat.com/docs/on-premise-deployment/docker/upgrades

Upgrade CometChat on-premise Docker deployments with backups, health checks, image pulls, staged rollout, and rollback planning.

This document outlines the recommended upgrade strategy to ensure zero downtime and safe production rollouts.

## Required inputs

Before starting the upgrade, ensure you have:

* Target release version (e.g., v3.9.52)
* Container registry access credentials
* Access to the Swarm manager node

## Pre-upgrade checklist

Before performing any upgrade:

1. **Backup critical data**:
   * Database snapshots (TiDB/TiKV)
   * Redis persistence files
   * Configuration files

2. **Verify current system health**:
   ```bash theme={null}
   docker service ls
   docker stack ps <stack-name>
   ```

3. **Test the upgrade in a staging environment** first

4. **Schedule maintenance window** (if needed for major upgrades)

5. **Notify team members** of the upgrade

## Upgrade execution steps

Upgrades should be performed during low-traffic periods whenever possible.

### Step 1: Pull latest images

```bash theme={null}
docker pull <registry>/chat-api:<new-version>
docker pull <registry>/websocket-gateway:<new-version>
# Pull other service images as needed
```

### Step 2: Apply updates using the update script

To update services without full redeploy:

```bash theme={null}
./update.sh
```

This script is provided as part of the CometChat on-premise deployment and must be executed from the Swarm manager node. It performs rolling updates of services while maintaining availability and honoring Docker Swarm update policies.

### Step 3: Monitor the rollout

Watch service updates in real-time:

```bash theme={null}
docker service ps <service-name> --no-trunc
docker service logs -f <service-name>
```

### Step 4: Verify health checks

Ensure new replicas pass health checks:

```bash theme={null}
docker service inspect <service-name> --format='{{json .UpdateStatus}}'
```

## Rolling updates

Docker Swarm performs rolling updates automatically when using `./update.sh` or manual service updates:

```bash theme={null}
# Example for updating a single service
docker service update --image <registry>/chat-api:<new-version> <service-name>
```

The process:

* Deploy new service replicas alongside existing ones
* Gradually shift traffic to the updated replicas
* Retire older replicas only after health checks pass

### Configure update behavior

Control rolling update parameters:

```bash theme={null}
docker service update \
  --update-parallelism 2 \
  --update-delay 10s \
  --update-failure-action rollback \
  <service-name>
```

## Database migrations

### Step 1: Backup database

```bash theme={null}
# TiDB backup example
tiup br backup full --pd <pd-address> --storage "local:///backup/$(date +%Y%m%d)"
```

### Step 2: Test migration in staging

Always test migrations in a staging environment before production.

### Step 3: Run migration

```bash theme={null}
# Example migration command (adjust for your setup)
docker exec -it <api-container> npm run migrate
```

**Important:** Ensure only one instance runs migrations to avoid concurrent schema changes.

### Best practices

* Prefer backward-compatible schema changes
* Avoid dropping or renaming columns while serving live traffic
* Use feature flags to decouple code deployment from schema changes
* Keep migrations idempotent (safe to run multiple times)

## Post-upgrade verification

After upgrade completes:

1. **Check service status**:
   ```bash theme={null}
   docker service ls
   docker service ps <service-name>
   ```

2. **Verify application health**:
   ```bash theme={null}
   curl http://<api-endpoint>/health
   ```

3. **Monitor logs for errors**:
   ```bash theme={null}
   docker service logs --tail 100 <service-name>
   ```

4. **Check metrics and dashboards** (Prometheus/Grafana) for latency, error rates, and resource spikes

5. **Test critical user flows** (login, messaging, etc.)

## Rollback procedures

If issues are detected after upgrade:

### Automatic rollback

Docker Swarm can automatically rollback on failure:

```bash theme={null}
docker service update --rollback <service-name>
```

### Manual rollback to previous image

```bash theme={null}
docker service update --image <registry>/chat-api:<previous-version> <service-name>
```

### Database rollback

If database migration needs reverting:

```bash theme={null}
# Run down migration (adjust for your setup)
docker exec -it <api-container> npm run migrate:down
```

Or restore from backup:

```bash theme={null}
# TiDB restore example
tiup br restore full --pd <pd-address> --storage "local:///backup/<backup-date>"
```

### Rollback checklist

1. Revert service images to previous versions
2. Rollback database migrations if schema changed
3. Restore configuration files if modified
4. Validate application behavior and data integrity
5. Monitor the system for 15–30 minutes before restoring full traffic
6. Document the issue and root cause for post-mortem


# Kubernetes Deployment
Source: https://www.cometchat.com/docs/on-premise-deployment/kubernetes/overview

Deploy CometChat on-premise on Kubernetes for large-scale, multi-region, autoscaled, and service-mesh-ready environments.

CometChat on-premise on Kubernetes provides enterprise-grade orchestration for large-scale deployments requiring advanced features like multi-region active-active architectures, dynamic autoscaling, and service mesh integration.

## When to use Kubernetes

Kubernetes is recommended for deployments that meet one or more of these criteria:

**Scale Requirements:**

* Monthly Active Users (MAU) exceeding 200,000
* Peak Concurrent Connections (PCC) exceeding 20,000
* Multi-region or global deployments with active-active failover

**Advanced Features:**

* Dynamic autoscaling based on custom metrics (HPA/VPA)
* Service mesh for mTLS and advanced traffic management (Istio, Linkerd)
* GitOps workflows for declarative infrastructure management
* Cloud-native operators for Kafka, databases, and other components

**Operational Requirements:**

* Sub-50ms latency targets requiring sophisticated traffic routing
* Compliance requirements demanding advanced security policies
* Integration with existing Kubernetes infrastructure

## Kubernetes vs Docker Swarm

| Feature                    | Docker Swarm           | Kubernetes         |
| -------------------------- | ---------------------- | ------------------ |
| **Recommended Scale**      | Up to 200k MAU         | 200k+ MAU          |
| **Operational Complexity** | Low                    | High               |
| **Learning Curve**         | Minimal                | Steep              |
| **Autoscaling**            | Manual                 | Advanced (HPA/VPA) |
| **Multi-region**           | Manual setup           | Native support     |
| **Service Mesh**           | Not supported          | Native integration |
| **Ecosystem**              | Limited                | Extensive          |
| **Best For**               | Mid-market, simplicity | Enterprise, scale  |

## Architecture highlights

**Kubernetes deployment includes:**

* Horizontal Pod Autoscaler (HPA) for automatic scaling based on CPU, memory, or custom metrics
* Vertical Pod Autoscaler (VPA) for right-sizing pod resource requests
* Multi-region active-active deployments with global load balancing
* Service mesh integration (Istio, Linkerd) for mTLS, traffic management, and observability
* Cloud-native Kafka operators (Strimzi, Confluent) for automated cluster management
* Advanced security policies with Pod Security Standards and Network Policies
* GitOps workflows with ArgoCD or Flux for declarative infrastructure management

## Enterprise support

Kubernetes deployments require specialized expertise and planning. Our solutions team provides:

**Architecture & Planning:**

* Custom reference architectures tailored to your requirements
* Capacity planning and sizing recommendations
* Multi-region deployment strategies
* Migration planning from Docker Swarm or other platforms

**Implementation Support:**

* Helm charts and Kubernetes manifests
* CI/CD pipeline integration
* Service mesh configuration
* Monitoring and observability setup

**Ongoing Operations:**

* Operational runbooks and best practices
* Scaling and performance optimization
* Disaster recovery planning
* Security hardening and compliance guidance

## Contact us

To discuss Kubernetes deployment for your organization:

**Enterprise Sales & Solutions:**

For Kubernetes deployments, reference architectures, migration planning, and ongoing operational guidance, [contact us](https://www.cometchat.com/contact-sales).

**What to prepare for the consultation:**

* Current or projected Monthly Active Users (MAU)
* Peak Concurrent Connections (PCC) estimates
* Geographic distribution requirements
* Compliance and security requirements (GDPR, HIPAA, SOC 2, etc.)
* Existing infrastructure (cloud provider, Kubernetes experience)
* Timeline and deployment goals

**Response time:** Our solutions team typically responds within 1 business day for enterprise inquiries.


# Advanced CometChat Widget Setup for Static HTML
Source: https://www.cometchat.com/docs/widget/html/advanced

Explore advanced setup options for the CometChat Widget in static HTML websites, including custom sign-in methods and configurations.

<Info>
  **Quick Reference for AI Agents & Developers**

  * **What this page covers**: Advanced JavaScript controls for the CometChat Widget — open specific chats, listen for events, manage users/groups, control auth sessions, and change localization.
  * **Prerequisites**: The standard widget snippet from the [Integration guide](/docs/widget/html/integration) must already be on your page.
  * **Key action**: Add a `<script type="module">` block after the widget snippet and use the `CometChatApp` global helper to control the widget programmatically.
</Info>

## Advanced JavaScript Controls

The embed works out of the box. Use the helpers below only if you need to open a specific chat, listen for widget events, or change settings on the fly.

### Before you follow advanced setup steps

1. Keep the standard widget snippet (from the Integration guide) on your page.
2. Add another `<script type="module">` right after it or inside your site builder’s “custom code” area.
3. Wrap your code in `window.addEventListener("DOMContentLoaded", () => { ... })` so it runs after the widget loads.
4. Replace placeholder text such as `UID`, `GUID`, and `LANGUAGE_CODE` with your real values.

When the widget is ready, it exposes a global helper named `CometChatApp`. Every example below shows a tiny recipe you can paste inside the script mentioned above.

### Open a chat or start a call

Use these helpers when you want the widget to jump straight to a person/group or begin a call. Drop the snippet inside your custom script and replace `UID`/`GUID` with real IDs from your CometChat app.

```js theme={null}
// Open chat with a specific person
CometChatApp.chatWithUser("UID");

// Open chat with a specific group
CometChatApp.chatWithGroup("GUID");

// Start a call with a person or a group
CometChatApp.callUser("UID");
CometChatApp.callGroup("GUID");

// Toggle extra UI bits
CometChatApp.showGroupActionMessages(true); // Show join/leave messages
CometChatApp.showDockedUnreadCount(true);   // Show unread badge on docked bubble
```

### Listen for widget events

Run your own code when something happens inside the widget—new message, docked bubble opened, or someone switching chats. Keep the event names as shown; just change what happens inside each arrow function.

```js theme={null}
// Fire when a new message arrives
CometChatApp.uiEvent("onMessageReceived", (message) => {
  console.log("New message:", message);
});

// Fire when the docked bubble opens or closes
CometChatApp.uiEvent("onOpenChat", () => console.log("Chat opened"));
CometChatApp.uiEvent("onCloseChat", () => console.log("Chat closed"));

// Fire when the user switches between conversations
CometChatApp.uiEvent("onActiveChatChanged", (chat) => {
  console.log("Now viewing:", chat);
});
```

### Create/Update users on the fly

* This will only work with authKey

If you collect names, avatars, or profile links on your site, you can push them straight into CometChat.
Replace the placeholders and run the snippet after the widget loads.

```js theme={null}
// Create or update a user
const user = new CometChatApp.CometChat.User("UID");
user.setName("User Name");
user.setAvatar("https://example.com/avatar.png");
user.setLink("https://example.com/profile");

CometChatApp.createOrUpdateUser(user).then((result) => {
  console.log("User saved:", result);
});
```

### Create/Update groups on the fly

If you want to create groups directly from your page, use this snippet. Replace the placeholders and run the snippet after the widget loads.

```js theme={null}
// Create or update a group
const group = new CometChatApp.CometChat.Group("GUID", "GROUP_NAME", "public");

CometChatApp.createOrUpdateGroup(group).then((result) => {
  console.log("Group saved:", result);
});
```

### Log users in or out with code

Use an auth token if you have a backend, or fall back to a plain UID for quick tests. Run these helpers after the widget loads.

```js theme={null}
// Sign in with a secure auth token from your server
CometChatApp.login({ authToken: "USER_AUTH_TOKEN" });

// ...or sign in directly with a UID (less secure, but fast for demos)
CometChatApp.login({ uid: "UID" });

// Sign the current user out
CometChatApp.logout();

// Listen for logout so you can clean up your UI
CometChatApp.uiEvent("onLogout", () => {
  console.log("User logged out");
});
```

### Control where data is stored

Pick whether the widget should remember login info in the browser tab only (`SESSION`) or across visits (`LOCAL`). Update the placeholders, then drop this script right after the default widget embed.

```js lines highlight={5} theme={null}
const COMETCHAT_DATA = {
  appID: "<YOUR_APP_ID>",
  appRegion: "<YOUR_APP_REGION>",
  authKey: "<YOUR_AUTH_KEY>",
  storageMode: "SESSION", // or "LOCAL" (default)
};

const COMETCHAT_USER_UID = "UID"; // The person who should log in

const COMETCHAT_LAUNCH_OPTIONS = {
  targetElementID: "cometChatMount",
  isDocked: true,
  width: "700px",
  height: "500px",
};

window.addEventListener("DOMContentLoaded", () => {
  CometChatApp.init(COMETCHAT_DATA)
    .then(() => CometChatApp.login({ uid: COMETCHAT_USER_UID }))
    .then(() => CometChatApp.launch(COMETCHAT_LAUNCH_OPTIONS))
    .catch(console.error);
});

// Optional extras:
// COMETCHAT_LAUNCH_OPTIONS.variantID = "YOUR_VARIANT_ID";
// COMETCHAT_LAUNCH_OPTIONS.chatType = "user" | "group";
// COMETCHAT_LAUNCH_OPTIONS.defaultChatID = "uid_or_guid";
// COMETCHAT_LAUNCH_OPTIONS.dockedAlignment = "left" | "right";
```

### Change the widget language

The widget auto-detects the browser language, but you can force it to any supported locale. Run the helper once after the widget loads and swap in the language code you need.

```js theme={null}
CometChatApp.localize("en-US"); // Example: force English (United States)
```

**Popular codes**

| Language                 | Code    |
| ------------------------ | ------- |
| English (United States)  | `en-US` |
| English (United Kingdom) | `en-GB` |
| Dutch                    | `nl`    |
| French                   | `fr`    |
| German                   | `de`    |
| Hindi                    | `hi`    |
| Italian                  | `it`    |
| Japanese                 | `ja`    |
| Korean                   | `ko`    |
| Portuguese               | `pt`    |
| Russian                  | `ru`    |
| Spanish                  | `es`    |
| Turkish                  | `tr`    |
| Chinese (Simplified)     | `zh`    |
| Chinese (Traditional)    | `zh-TW` |
| Malay                    | `ms`    |
| Swedish                  | `sv`    |
| Lithuanian               | `lt`    |
| Hungarian                | `hu`    |

Need another locale? Use the same pattern with its code (for example `CometChatApp.localize("ko")` for Korean).

## Next Steps

<CardGroup>
  <Card title="HTML Integration" href="/widget/html/integration">
    Go back to the basic integration guide to set up the widget snippet.
  </Card>

  <Card title="Legacy Widget" href="https://assets.cometchat.io/legacy-docs/widget/html/legacy.html">
    Using the older CometChat Widget? See the legacy integration guide.
  </Card>

  <Card title="Widget Overview" href="/widget/html/overview">
    Return to the Widget Builder overview for a high-level walkthrough.
  </Card>
</CardGroup>


# Add CometChat Widget to a Static HTML Website
Source: https://www.cometchat.com/docs/widget/html/integration

Learn how to integrate the CometChat Widget into a static HTML website with step-by-step instructions.

Add the CometChat Widget by pasting one small HTML snippet. It drops in like any other embed—copy the code, paste it into your page, then tell the widget how people should sign in.

**Choose the sign-in option that matches your site:**

<CardGroup>
  <Card title="Anonymous Chat (Guest Mode)" href="#1-anonymous-chat-guest-mode">
    * Let anyone chat anonymously without signing up or logging in.
    * Perfect for marketing pages, help centers, or demo sites.
  </Card>

  <Card title="Create + Log In User On The Fly" href="#2-create-+-log-in-user-on-the-fly">
    * Use your existing user IDs (email, username etc.) to create and log in users automatically.
    * No backend needed—CometChat creates users the first time they visit.
  </Card>

  <Card title="Backend-Created User (Auth Token Login)" href="#3-backend-created-user-auth-token-login">
    * Create your users via server and login them using secure auth token on frontend.
    * Ideal for sites with existing login systems and backends.
  </Card>
</CardGroup>

***

## 1. Anonymous Chat (Guest Mode)

**Use this when:**

* Anyone should be able to start chatting instantly
* You do not have (or do not want) your own login form yet

### Copy this into `<head>`

```html theme={null}
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
```

### Copy this into `<body>`

```html lines highlight={8-9, 11, 13, 17-19, 24-26} theme={null}
<!-- Where the chat widget should appear -->
<div id="cometChatMount"></div>

<script type="module">

  //  EDIT ONLY THE TEXT INSIDE QUOTES
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",   // e.g. "us", "eu", "in"
    mode: "guest",               // keep this as "guest"
    authKey: "YOUR_AUTH_KEY",

    language: "en-US",           // optional, defaults to "en-US"

    // Optional: how the guest appears in chat
    user: {
      name: "Guest User",
      avatar: "",                // e.g. "https://example.com/guest.png"
      link: ""                   // e.g. "https://example.com/profile"
    },

    // Widget placement + size
    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,               // true = docked widget (recommended)
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
    //autoOpenFirstItem: false,
  };

  CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
</script>
```

### Update these values

| Setting                                 | What to enter / where to find it                                                                                                                                                              |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appID`, `region`, `authKey`            | Copy from **[Dashboard](https://app.cometchat.com)**                                                                                                                                          |
| `language`                              | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. |
| `user.name`, `user.avatar`, `user.link` | Optional guest display info—leave blank if you don’t need it.                                                                                                                                 |
| `width`, `height`, `isDocked`           | <p>Adjust the widget width & height.</p><p>**isDocked = true** - appears as icon on page and expands when clicked.</p> <p>**isDocked = false** - appears embedded on the page.</p>            |
| `variantID`                             | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used.                                                                     |
| `chatType`                              | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat).                                                                                   |
| `defaultChatID`                         | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads.                                                                                   |
| `dockedAlignment`                       | Controls the position of the docked widget interface on the page (left side or right side).                                                                                                   |
| `autoOpenFirstItem`                     | When set to `false`, the widget does not automatically open the first conversation on load. Defaults to `true`.                                                                               |

## 2. Create + Log In User On The Fly

**Use this when:**

* Every person already has an ID inside your product (email, username etc.)
* You want that ID to drive their chat identity automatically

### Copy this into `<head>`

```html theme={null}
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
```

### Copy this into `<body>`

```html lines highlight={8-9, 11, 14, 16, 20-22, 27-29} theme={null}
<!-- Where the chat widget should appear -->
<div id="cometChatMount"></div>

<script type="module">

  //  EDIT ONLY THE TEXT INSIDE QUOTES
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",      // e.g. "us", "eu", "in"
    mode: "uid",                    // keep this as "uid"
    authKey: "YOUR_AUTH_KEY",

    // IMPORTANT: this must be unique per user
    uid: "UNIQUE_USER_ID",          // e.g. "user_123", "customer_42"

    language: "en-US",              // optional, defaults to "en-US"

    // Optional: user profile shown in chat
    user: {
      name: "User Name",            // e.g. "Alex Johnson"
      avatar: "https://example.com/uid.png",
      link: "https://example.com/profile/uid"
    },

    // Widget placement + size
    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
    //autoOpenFirstItem: false,
  };

  CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
</script>
```

### Update these values

| Setting                                 | What to enter / where to find it                                                                                                                                                              |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appID`, `region`, `authKey`            | Copy from **[Dashboard](https://app.cometchat.com)**                                                                                                                                          |
| `uid`                                   | Pass the unique ID from your page (for example `customer.id`). CometChat creates the user the first time it sees that ID.                                                                     |
| `language`                              | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. |
| `user.name`, `user.avatar`, `user.link` | Optional profile info you already store for that person.                                                                                                                                      |
| `mode`                                  | Keep this as `"uid"` so the widget knows you’re logging in with IDs.                                                                                                                          |
| `width`, `height`, `isDocked`           | <p>Adjust the widget width & height.</p><p>**isDocked = true** - appears as icon on page and expands when clicked.</p> <p>**isDocked = false** - appears embedded on the page.</p>            |
| `variantID`                             | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used.                                                                     |
| `chatType`                              | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat).                                                                                   |
| `defaultChatID`                         | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads.                                                                                   |
| `dockedAlignment`                       | Controls the position of the docked widget interface on the page (left side or right side).                                                                                                   |
| `autoOpenFirstItem`                     | When set to `false`, the widget does not automatically open the first conversation on load. Defaults to `true`.                                                                               |

## 3. Backend-Created User (Auth Token Login)

**Use this when:**

* People sign in through your backend, and you generate their CometChat auth token server-side.

**Server-side flow (auth token login):**

1. Authenticate the user in your app.
2. If it’s their first time, call **Create User** ([https://www.cometchat.com/docs/rest-api/users/create](https://www.cometchat.com/docs/rest-api/users/create)) — you can also request an auth token in that call.
3. For returning users, call **Create Auth Token** ([https://www.cometchat.com/docs/rest-api/auth-tokens/create](https://www.cometchat.com/docs/rest-api/auth-tokens/create)) to issue a fresh token.
4. Send the token to the browser and place it in the widget config below.
5. The same token works for the CometChat Widget, UI Kit, or SDK.

Full walkthrough: [How to properly log in and create users in CometChat](https://community.cometchat.com/t/how-to-properly-log-in-and-create-users-in-cometchat/31).

### Copy this into `<head>`

```html theme={null}
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
```

### Copy this into `<body>`

```html lines highlight={8-9, 11, 13, 15, 19-20} theme={null}
<!-- Where the chat widget should appear -->
<div id="cometChatMount"></div>

<script type="module">

  //  EDIT ONLY THE TEXT INSIDE QUOTES
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",       // e.g. "us", "eu", "in"
    mode: "authToken",               // keep this as "authToken"

    // Generated BY YOUR BACKEND after user login
    authToken: "USER_AUTH_TOKEN",

    language: "en-US",               // optional, defaults to "en-US"

    // Widget placement + size
    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
    //autoOpenFirstItem: false,
  };

  CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
</script>
```

### Update these values

| Setting                       | What to enter / where to find it                                                                                                                                                              |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appID`, `region`             | Copy from **[Dashboard](https://app.cometchat.com)**                                                                                                                                          |
| `mode`                        | Keep as `"authToken"` so the widget expects a server-issued token.                                                                                                                            |
| `authToken`                   | Generate on your **server**: (1) call the CometChat Auth Token API with your API key, (2) get the token for that user, (3) send it to the page and place it here.                             |
| `language`                    | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. |
| `width`, `height`, `isDocked` | <p>Adjust the widget width & height.</p><p>**isDocked = true** - appears as icon on page and expands when clicked.</p> <p>**isDocked = false** - appears embedded on the page.</p>            |
| `variantID`                   | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used.                                                                     |
| `chatType`                    | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat).                                                                                   |
| `defaultChatID`               | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads.                                                                                   |
| `dockedAlignment`             | Controls the position of the docked widget interface on the page (left side or right side).                                                                                                   |
| `autoOpenFirstItem`           | When set to `false`, the widget does not automatically open the first conversation on load. Defaults to `true`.                                                                               |


# CometChat Widget Builder For HTML
Source: https://www.cometchat.com/docs/widget/html/overview

CometChat Widget Builder for HTML is a no-code solution that lets you embed a fully functional chat interface into any HTML website using a simple code snippet.

It provides a ready-to-use chat widget backed by CometChat's real-time infrastructure — no frontend framework required.

With CometChat Widget Builder, you can:

* Embed chat and calling into any HTML page
* Customize themes, colors, and typography
* Toggle features on and off
* Go live with a simple embed code snippet

The widget connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling.

<Card title="Ready to add chat to your HTML website?" icon="rocket" href="/widget/html/integration">
  Go to the Integration Guide
</Card>

<Warning>
  The Chat Widget is not customizable beyond the configuration options available in the Widget Builder in dashboard. If you require deeper customization, consider using our [UI Kits](/docs/ui-kit/react/overview) instead.
</Warning>

<Note>
  **Legacy Widget (v3):** If you previously used the legacy CometChat Widget (v3), the legacy widget section in the Dashboard is only visible for apps that had legacy widgets configured before the migration to Widget Builder. New apps will not see the legacy widget section. For migration guidance, see the [Migration Guide](/docs/articles/migration-guide).
</Note>

***

## Widget Builder Features

**No-Code Visual Configuration** — Widget Builder provides a visual configuration environment for designing your chat widget before embedding.

**Toggle-Based Feature Control** — Messaging and calling features can be controlled through configuration settings in the Widget Builder in dashboard.

**Ready-to-Embed Code** — After configuration, Widget Builder generates a code snippet you can paste directly into your HTML page.

***

## How to Use Widget Builder

### 1. Design

Customize your chat widget using the visual Widget Builder:

* **Configure layout** — Toggle all the required features in the dashboard.
* **Toggle features** — Turn chat and calling features on and off from the builder interface.
* **Themes** — Select between system, light, and dark themes. Choose custom colors and typography.

<Frame>
  <img />
</Frame>

### 2. Get Embed Code

Once configured, get the embed code snippet for your widget.

1. Click on **Get Embedded Code**
2. Note your app credentials (App ID, Auth Key, Region, Variant ID)
3. Copy the code snippet

### 3. Integrate

Add the embed code to your HTML page and go live.

1. **Paste the code snippet** into your HTML file
2. **Configure credentials** — Set your App ID, Region, and Auth Key
3. **User Authentication** — CometChat uses a UID (User ID) to identify each user. Authenticate users to enable chat functionality.
4. **Launch** — Open your HTML page and the chat widget is live

<Card title="Follow the full Integration Guide" icon="book" href="/widget/html/integration">
  Step-by-step instructions for embedding the Widget Builder into your HTML website
</Card>

***

## Try Live Demo

Experience the CometChat Widget Builder in action:

<CardGroup>
  <Card title="Launch Live Demo" icon="play" href="https://preview.cometchat.com/" />
</CardGroup>

<Frame>
  <iframe title="YouTube video" />
</Frame>

***

## Need Help?

<CardGroup>
  <Card title="Developer Community" icon="users" href="https://community.cometchat.com/">
    Connect with other developers and get answers
  </Card>

  <Card title="Support Portal" icon="headset" href="https://help.cometchat.com/hc/en-us/requests/new">
    Contact our support team for assistance
  </Card>
</CardGroup>

***

## Related Resources

<CardGroup>
  <Card title="JavaScript Chat SDK" href="/sdk/javascript/overview">
    Learn more about the CometChat JavaScript SDK
  </Card>

  <Card title="Advanced Widget Setup" href="/widget/html/advanced">
    Explore advanced JavaScript controls — open chats, listen for events, and more
  </Card>

  <Card title="WordPress Widget" href="/widget/wordpress/overview">
    Widget Builder for WordPress websites
  </Card>

  <Card title="Shopify Widget" href="/widget/shopify/overview">
    Widget Builder for Shopify stores
  </Card>
</CardGroup>


# Add CometChat Widget to Shopify
Source: https://www.cometchat.com/docs/widget/shopify/integration

Drop the CometChat Widget into your Shopify store and pick the sign-in flow: guest, Shopify customer IDs, or backend auth tokens.

Add the CometChat Widget with a single snippet inside your Shopify theme. Choose the sign-in flow that matches your store: guests, auto-created users from Shopify customers, or backend-issued auth tokens.

**Choose how shoppers sign in:**

<CardGroup>
  <Card title="Anonymous Chat (Guest Mode)" href="#1-anonymous-chat-guest-mode">
    * Visitors can chat without accounts.
    * Fastest, friction-free setup.
  </Card>

  <Card title="Create + Log In User On The Fly (Shopify Customers)" href="#2-create-+-log-in-user-on-the-fly-shopify-customers">
    * Auto-create CometChat users from Shopify customers.
    * Falls back to guests when no one is logged in.
  </Card>

  <Card title="Backend-Created User (Auth Token Login)" href="#3-backend-created-user-auth-token-login">
    * Use your backend to issue auth tokens.
    * Keep your Auth Key off the storefront.
  </Card>
</CardGroup>

***

## Where to paste the snippet in Shopify

1. In Shopify Admin, go to **Online Store → Themes → … → Edit code**.
2. Open **layout/theme.liquid** (or a section where you want the widget).
3. Scroll near `</body>` and paste the snippet from the option you choose.
4. Save and refresh your storefront to confirm chat loads.
5. For page-specific placement, paste the snippet into a section or template instead of the global layout.

***

## 1. Anonymous Chat (Guest Mode)

**Use this when:** you want anyone to chat without signing in.

### Paste this near `</body>` in `layout/theme.liquid`

```liquid theme={null}
<div id="cometChatMount"></div>
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>

<script type="module">
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",
    mode: "guest",
    authKey: "YOUR_AUTH_KEY",

    language: "en-US",      // optional, defaults to "en-US"

    user: {
      name: "Guest User",
      avatar: "",
      link: ""
    },

    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
    //autoOpenFirstItem: false,
  };

  CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
</script>
```

**Update these values:**

* `appID`, `region`, `authKey`: Copy from the CometChat Dashboard (use an **App Auth Key**, not REST API key).
* `language`: Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`.
* `user.name`, `user.avatar`, `user.link`: Optional guest display info.
* `width`, `height`, `isDocked`: Size/placement (`isDocked = true` shows a docked bubble).
* `variantID`, `chatType`, `defaultChatID`, `dockedAlignment`, `autoOpenFirstItem`: Optional widget targeting/placement controls. Set `autoOpenFirstItem: false` to prevent the widget from automatically opening the first conversation on load.

***

## 2. Create + Log In User On The Fly (Shopify Customers)

**Use this when:** you have Shopify customer accounts and want logged-in shoppers to automatically become CometChat users. Falls back to a persistent guest ID for visitors.

> Turn on **Shopify customer accounts** so `{{ customer.id }}` and `{{ customer.first_name }}` populate.

### Paste this near `</body>` in `layout/theme.liquid`

```liquid theme={null}
<div id="cometChatMount"></div>
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>

<script type="module">
  const SHOPIFY_CUSTOMER_ID = {{ customer.id | json }};
  const SHOPIFY_CUSTOMER_NAME = {{ customer.first_name | json }};

  const uidFromShopify = SHOPIFY_CUSTOMER_ID ? String(SHOPIFY_CUSTOMER_ID) : null;
  const savedGuestId = localStorage.getItem("cometchat_guest_uid") || `guest_${Date.now()}`;
  localStorage.setItem("cometchat_guest_uid", savedGuestId);

  const uid = uidFromShopify || savedGuestId;
  const name = SHOPIFY_CUSTOMER_NAME || "Guest User";

  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",
    mode: "uid",
    authKey: "YOUR_AUTH_KEY",

    language: "en-US",      // optional, defaults to "en-US"

    uid,
    user: {
      name,
      avatar: "",
      link: ""
    },

    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
  };

  CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
</script>
```

**Update these values:**

* `appID`, `region`, `authKey`: Copy from Dashboard (App Auth Key).
* `uid`: Leave as-is; it pulls Shopify customer ID or a stored guest ID.
* `language`: Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`.
* `user.name`, `user.avatar`, `user.link`: Optional profile info shown in chat.
* `width`, `height`, `isDocked`, `variantID`, `chatType`, `defaultChatID`, `dockedAlignment`: Optional UI/placement controls.

**How it works:**

* Uses Shopify `customer.id` + `customer.first_name` when a shopper is logged in.
* Stores a stable guest ID in `localStorage` for visitors so their chat history persists across pages.
* CometChat auto-creates the UID the first time it sees it.

***

## 3. Backend-Created User (Auth Token Login)

**Use this when:** people sign in through your backend and you generate their CometChat auth token server-side. This keeps your Auth Key off the page.

**Server-side flow (auth token login):**

1. Authenticate the user in your app.
2. If it’s their first time, call **Create User** ([https://www.cometchat.com/docs/rest-api/users/create](https://www.cometchat.com/docs/rest-api/users/create)) — you can also request an auth token in that call.
3. For returning users, call **Create Auth Token** ([https://www.cometchat.com/docs/rest-api/auth-tokens/create](https://www.cometchat.com/docs/rest-api/auth-tokens/create)) to issue a fresh token.
4. Send the token to the browser and place it in the widget config below.
5. The same token works for the CometChat Widget, UI Kit, or SDK.

Full walkthrough: [How to properly log in and create users in CometChat](https://community.cometchat.com/t/how-to-properly-log-in-and-create-users-in-cometchat/31).

**Use this when:** you issue CometChat auth tokens from your backend and don’t want an Auth Key in the browser.

### Paste this near `</body>` in `layout/theme.liquid`

```liquid theme={null}
<div id="cometChatMount"></div>
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>

<script type="module">
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",
    mode: "authToken",

    // Inject the token your backend generated for the logged-in customer
    authToken: "USER_AUTH_TOKEN",

    language: "en-US",      // optional, defaults to "en-US"

    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
  };

  CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
</script>
```

**Update these values:**

* `appID`, `region`: Copy from Dashboard.
* `authToken`: Generate server-side after the user logs in (using CometChat Auth Token API) and output it into this snippet (e.g., from a Shopify app proxy or metafield).
* `language`: Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`.
* UI options: `width`, `height`, `isDocked`, `variantID`, `chatType`, `defaultChatID`, `dockedAlignment`.

***

### Optional: Make credentials editable in Theme settings

Add this block to `config/settings_schema.json` (just before the final `]`). Then replace hardcoded values in the snippets with `{{ settings.cometchat_app_id }}` etc.

```jsonc theme={null}
,
{
  "name": "CometChat Settings",
  "settings": [
    {
      "type": "text",
      "id": "cometchat_app_id",
      "label": "CometChat App ID",
      "default": "YOUR_APP_ID"
    },
    {
      "type": "text",
      "id": "cometchat_app_region",
      "label": "CometChat App Region",
      "default": "YOUR_REGION"
    },
    {
      "type": "text",
      "id": "cometchat_auth_key",
      "label": "CometChat Auth Key",
      "default": "YOUR_AUTH_KEY"
    }
  ]
}
```

***

### Optional: Add as an Online Store 2.0 section/app block

1. **Online Store → Themes → Edit code**.
2. Under **Sections**, create `cometchat-widget.liquid` and paste one of the snippets above.
3. Save, then add it in **Customize theme** under **App embeds** or as a section on any template:

```liquid theme={null}
{% section 'cometchat-widget' %}
```

***

## Advanced JavaScript Controls

The embed works out of the box. Use the helpers below only if you need to open a specific chat, listen for widget events, or change settings on the fly.

### Before you follow advanced setup steps

1. Keep the standard widget snippet (from the Integration guide) on your page.
2. Add another `<script type="module">` right after it or inside your site builder’s “custom code” area.
3. Wrap your code in `window.addEventListener("DOMContentLoaded", () => { ... })` so it runs after the widget loads.
4. Replace placeholder text such as `UID`, `GUID`, and `LANGUAGE_CODE` with your real values.

When the widget is ready, it exposes a global helper named `CometChatApp`. Every example below shows a tiny recipe you can paste inside the script mentioned above.

### Open a chat or start a call

Use these helpers when you want the widget to jump straight to a person/group or begin a call. Drop the snippet inside your custom script and replace `UID`/`GUID` with real IDs from your CometChat app.

```js theme={null}
// Open chat with a specific person
CometChatApp.chatWithUser("UID");

// Open chat with a specific group
CometChatApp.chatWithGroup("GUID");

// Start a call with a person or a group
CometChatApp.callUser("UID");
CometChatApp.callGroup("GUID");

// Toggle extra UI bits
CometChatApp.showGroupActionMessages(true); // Show join/leave messages
CometChatApp.showDockedUnreadCount(true);   // Show unread badge on docked bubble
```

### Listen for widget events

Run your own code when something happens inside the widget—new message, docked bubble opened, or someone switching chats. Keep the event names as shown; just change what happens inside each arrow function.

```js theme={null}
// Fire when a new message arrives
CometChatApp.uiEvent("onMessageReceived", (message) => {
  console.log("New message:", message);
});

// Fire when the docked bubble opens or closes
CometChatApp.uiEvent("onOpenChat", () => console.log("Chat opened"));
CometChatApp.uiEvent("onCloseChat", () => console.log("Chat closed"));

// Fire when the user switches between conversations
CometChatApp.uiEvent("onActiveChatChanged", (chat) => {
  console.log("Now viewing:", chat);
});
```

### Create/Update users on the fly

* This will only work with authKey

If you collect names, avatars, or profile links on your site, you can push them straight into CometChat.
Replace the placeholders and run the snippet after the widget loads.

```js theme={null}
// Create or update a user
const user = new CometChatApp.CometChat.User("UID");
user.setName("User Name");
user.setAvatar("https://example.com/avatar.png");
user.setLink("https://example.com/profile");

CometChatApp.createOrUpdateUser(user).then((result) => {
  console.log("User saved:", result);
});
```

### Create/Update groups on the fly

If you want to create groups directly from your page, use this snippet. Replace the placeholders and run the snippet after the widget loads.

```js theme={null}
// Create or update a group
const group = new CometChatApp.CometChat.Group("GUID", "GROUP_NAME", "public");

CometChatApp.createOrUpdateGroup(group).then((result) => {
  console.log("Group saved:", result);
});
```

### Log users in or out with code

Use an auth token if you have a backend, or fall back to a plain UID for quick tests. Run these helpers after the widget loads.

```js theme={null}
// Sign in with a secure auth token from your server
CometChatApp.login({ authToken: "USER_AUTH_TOKEN" });

// ...or sign in directly with a UID (less secure, but fast for demos)
CometChatApp.login({ uid: "UID" });

// Sign the current user out
CometChatApp.logout();

// Listen for logout so you can clean up your UI
CometChatApp.uiEvent("onLogout", () => {
  console.log("User logged out");
});
```

### Control where data is stored

Pick whether the widget should remember login info in the browser tab only (`SESSION`) or across visits (`LOCAL`). Update the placeholders, then drop this script right after the default widget embed.

```js lines highlight={5} theme={null}
const COMETCHAT_DATA = {
  appID: "<YOUR_APP_ID>",
  appRegion: "<YOUR_APP_REGION>",
  authKey: "<YOUR_AUTH_KEY>",
  storageMode: "SESSION", // or "LOCAL" (default)
};

const COMETCHAT_USER_UID = "UID"; // The person who should log in

const COMETCHAT_LAUNCH_OPTIONS = {
  targetElementID: "cometChatMount",
  isDocked: true,
  width: "700px",
  height: "500px",
};

window.addEventListener("DOMContentLoaded", () => {
  CometChatApp.init(COMETCHAT_DATA)
    .then(() => CometChatApp.login({ uid: COMETCHAT_USER_UID }))
    .then(() => CometChatApp.launch(COMETCHAT_LAUNCH_OPTIONS))
    .catch(console.error);
});

// Optional extras:
// COMETCHAT_LAUNCH_OPTIONS.variantID = "YOUR_VARIANT_ID";
// COMETCHAT_LAUNCH_OPTIONS.chatType = "user" | "group";
// COMETCHAT_LAUNCH_OPTIONS.defaultChatID = "uid_or_guid";
// COMETCHAT_LAUNCH_OPTIONS.dockedAlignment = "left" | "right";
```

### Change the widget language

The widget auto-detects the browser language, but you can force it to any supported locale. Run the helper once after the widget loads and swap in the language code you need.

```js theme={null}
CometChatApp.localize("en-US"); // Example: force English (United States)
```

**Popular codes**

| Language                 | Code    |
| ------------------------ | ------- |
| English (United States)  | `en-US` |
| English (United Kingdom) | `en-GB` |
| Dutch                    | `nl`    |
| French                   | `fr`    |
| German                   | `de`    |
| Hindi                    | `hi`    |
| Italian                  | `it`    |
| Japanese                 | `ja`    |
| Korean                   | `ko`    |
| Portuguese               | `pt`    |
| Russian                  | `ru`    |
| Spanish                  | `es`    |
| Turkish                  | `tr`    |
| Chinese (Simplified)     | `zh`    |
| Chinese (Traditional)    | `zh-TW` |
| Malay                    | `ms`    |
| Swedish                  | `sv`    |
| Lithuanian               | `lt`    |
| Hungarian                | `hu`    |

Need another locale? Use the same pattern with its code (for example `CometChatApp.localize("ko")` for Korean).

***

## Troubleshooting

* **Widget not appearing?** Confirm the embed script loads (`chat-embed@1.x.x`), the mount div exists, and no ad blockers or CSP rules are blocking it.
* **Shopify customer info not showing?** Ensure customer accounts are enabled and you’re previewing as a logged-in shopper (not just the Theme Editor).
* **Login/auth errors?** For UID mode, verify the Auth Key is an App Auth Key and UIDs are unique; for auth token mode, ensure the token matches the logged-in user.
* **Docked vs embedded view wrong?** Adjust `isDocked`, `width`, `height`, and optional alignment settings.
* **Still stuck?** Inspect `CometChatApp.CometChatAuth` calls in the browser console for errors.

***

## Need Help?

Reach out to [CometChat Support](https://www.cometchat.com/contact) or visit our [docs](https://www.cometchat.com/docs).


# CometChat Widget Builder For Shopify
Source: https://www.cometchat.com/docs/widget/shopify/overview

CometChat Widget Builder for Shopify is a no-code solution for embedding a fully functional chat interface with a simple code snippet.

It provides a ready-to-use chat widget backed by CometChat's real-time infrastructure — paste the embed code into your Shopify theme and go live.

With CometChat Widget Builder, you can:

* Embed chat and calling into any Shopify store
* Customize themes, colors, and typography
* Toggle features on and off
* Go live with a simple embed code snippet

The widget connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling.

<Card title="Ready to add chat to your Shopify store?" icon="rocket" href="/widget/shopify/integration">
  Go to the Integration Guide
</Card>

***

## Widget Builder Features

**No-Code Visual Configuration** — Widget Builder provides a visual configuration environment for designing your chat widget before embedding.

**Toggle-Based Feature Control** — Messaging and calling features can be controlled through configuration settings in the Widget Builder in dashboard.

**Ready-to-Embed Code** — After configuration, Widget Builder generates a code snippet you can paste directly into your Shopify theme.

***

## How to Use Widget Builder

### 1. Design

Customize your chat widget using the visual Widget Builder:

* **Configure layout** — Toggle all the required features in the dashboard.
* **Toggle features** — Turn chat and calling features on and off from the builder interface.
* **Themes** — Select between system, light, and dark themes. Choose custom colors and typography.

<Frame>
  <img />
</Frame>

### 2. Get Embed Code

Once configured, get the embed code snippet for your widget.

1. Click on **Get Embedded Code**
2. Note your app credentials (App ID, Auth Key, Region, Variant ID)
3. Copy the code snippet

### 3. Integrate

Add the embed code to your Shopify store and go live.

1. **Open your Shopify theme** — Go to Online Store → Themes → Edit Code
2. **Paste the code snippet** into your theme's layout file (e.g., `theme.liquid`)
3. **Configure credentials** — Set your App ID, Region, and Auth Key
4. **User Authentication** — CometChat uses a UID (User ID) to identify each user. Authenticate users to enable chat functionality.
5. **Launch** — Save your theme and the chat widget is live on your store

<Card title="Follow the full Integration Guide" icon="book" href="/widget/shopify/integration">
  Step-by-step instructions for embedding the Widget Builder into your Shopify store
</Card>

***

## Try Live Demo

Experience the CometChat Widget Builder in action:

<CardGroup>
  <Card title="Launch Live Demo" icon="play" href="https://preview.cometchat.com/" />
</CardGroup>

<Frame>
  <iframe title="YouTube video" />
</Frame>

***

## Need Help?

<CardGroup>
  <Card title="Developer Community" icon="users" href="https://community.cometchat.com/">
    Connect with other developers and get answers
  </Card>

  <Card title="Support Portal" icon="headset" href="https://help.cometchat.com/hc/en-us/requests/new">
    Contact our support team for assistance
  </Card>
</CardGroup>

***

## Related Resources

<CardGroup>
  <Card title="JavaScript Chat SDK" href="/sdk/javascript/overview">
    Learn more about the CometChat JavaScript SDK
  </Card>

  <Card title="HTML Widget" href="/widget/html/overview">
    Widget Builder for HTML websites
  </Card>

  <Card title="WordPress Widget" href="/widget/wordpress/overview">
    Widget Builder for WordPress websites
  </Card>

  <Card title="Wix Widget" href="/widget/wix/overview">
    Widget Builder for Wix websites
  </Card>
</CardGroup>


# Add CometChat Widget to Squarespace
Source: https://www.cometchat.com/docs/widget/squarespace/integration

Drop the CometChat Widget into Squarespace using Code Injection or a Code Block, then pick the sign-in flow that matches your site.

Add the CometChat Widget by pasting one small code snippet. It drops in like any other embed—copy the code, paste it into your site's Code Injection, then tell the widget how people should sign in.

**Choose the sign-in option that matches your site:**

<CardGroup>
  <Card title="Anonymous Chat (Guest Mode)" href="#1-anonymous-chat-guest-mode">
    * Visitors can chat without accounts.
    * Fastest, friction-free setup.
  </Card>

  <Card title="Create + Log In User On The Fly (Squarespace Members)" href="#2-create-+-log-in-user-on-the-fly-squarespace-members">
    * Auto-create CometChat users for Squarespace members.
    * Falls back to guests for non-members.
  </Card>

  <Card title="Backend-Created User (Auth Token Login)" href="#3-backend-created-user-auth-token-login">
    * Maximum security; no authKey in the browser.
    * Use your backend to issue auth tokens.
  </Card>
</CardGroup>

***

### Steps to Add Custom Code in Squarespace (via Code Injection)

1. Log in to the Squarespace and open your website dashboard.
2. Choose the **Website** you want to integrate with CometChat.
3. Click **Edit Pages** and open **Custom Code**.
4. Click **Code Injection**.
5. You’ll see **Header** and **Footer**. Paste your chosen integration snippet into **Footer**.
6. Click **Save**.
7. Refresh your site and open a page to confirm chat loads.

***

## 1. Anonymous Chat (Guest Mode)

**Use this when:**

* You want visitors to chat without creating accounts.
* You don’t have a member area or user authentication.
* You want quick, friction-free chat access.

### Paste this into Footer (Code Injection)

```html lines highlight={6-7,9} theme={null}
<div id="cometChatMount"></div>
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>

<script>
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",
    mode: "guest",
    authKey: "YOUR_AUTH_KEY",

    language: "en-US",      // optional, defaults to "en-US"

    user: {
      name: "Guest User",
      avatar: "",
      link: ""
    },

    mount: "#cometChatMount",
    width: "400px",
    height: "80vh",
    isDocked: true,
    //autoOpenFirstItem: false,
  };

  const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", startWidget);
  } else {
    startWidget();
  }
</script>
```

**Update these values:**

* `appID`, `region`, `authKey`: Copy from Dashboard.
* `language`: Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`.
* `user.name`, `user.avatar`, `user.link`: Optional guest display info.
* `width`, `height`, `isDocked`: Widget dimensions (`isDocked = true` = floating icon; `false` = embedded).

***

## 2. Create + Log In User On The Fly (Squarespace Members)

**Use this when:**

* You have Squarespace Member Areas enabled.
* You want members to automatically get CometChat accounts.
* You want to support both members and guest visitors.

### Paste this into Footer (Code Injection)

```html lines highlight={7-9,12} theme={null}
<div id="cometChatMount"></div>

<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>

<script>
const COMETCHAT_CONFIG = {
  appID: "YOUR_APP_ID",
  region: "YOUR_APP_REGION",      // e.g. "us", "eu", "in"
  authKey: "YOUR_AUTH_KEY"
};

const GUEST_ID_KEY = "cometchat_guest_id";

function getSquarespaceMember() {
  const cookieName = "SiteUserInfo=";
  const cookies = decodeURIComponent(document.cookie).split(";");
  for (let c of cookies) {
    c = c.trim();
    if (c.startsWith(cookieName)) {
      try {
        const data = JSON.parse(c.substring(cookieName.length));
        if (data.authenticated) {
          return {
            uid: String(data.siteUserId),
            name: data.firstName || "Member",
            isMember: true,
          };
        }
      } catch {}
    }
  }

  return null;
}

function resolveUser() {
  const member = getSquarespaceMember();
  if (member) return member;

  let guestId = localStorage.getItem(GUEST_ID_KEY);
  if (!guestId) {
    guestId = `guest_${Math.random().toString(36).slice(2, 11)}`;
    localStorage.setItem(GUEST_ID_KEY, guestId);
  }

  return {
    uid: guestId,
    name: "Guest User",
    isMember: false,
  };
}

function initializeCometChat() {
  const start = async () => {
    try {
      const user = resolveUser();
      await CometChatApp.init(COMETCHAT_CONFIG);
      const loggedInUser = await CometChatApp.CometChat.getLoggedinUser();
      if (!loggedInUser || loggedInUser.uid !== user.uid) {
        if (loggedInUser) {
          await CometChatApp.logout();
        }
        const ccUser = new CometChatApp.CometChat.User(user.uid);
        ccUser.setName(user.name);
        try {
          await CometChatApp.createOrUpdateUser(ccUser);
        } catch {}
        await CometChatApp.login({
          uid: user.uid,
          authKey: COMETCHAT_CONFIG.authKey,
        });
      }
      CometChatApp.launch({
        targetElementID: "cometChatMount",
        isDocked: true,
        width: "400px",
        height: "80vh",
        //autoOpenFirstItem: false,
      });
    } catch {}
  };

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", start, { once: true });
  } else {
    start();
  }
}

initializeCometChat();
</script>
```

**How it works:**

* Detects Squarespace members via the `SiteUserInfo` cookie.
* Creates CometChat users on-the-fly when members first visit; falls back to guest for others.
* Persists guest IDs in `localStorage` to keep a consistent identity.

***

## 3. Backend-Created User (Auth Token Login)

**Use this when:** people sign in through your backend and you generate their CometChat auth token server-side. This keeps your Auth Key off the page.

**Server-side flow (auth token login):**

1. Authenticate the user in your app.
2. If it’s their first time, call **Create User** ([https://www.cometchat.com/docs/rest-api/users/create](https://www.cometchat.com/docs/rest-api/users/create)) — you can also request an auth token in that call.
3. For returning users, call **Create Auth Token** ([https://www.cometchat.com/docs/rest-api/auth-tokens/create](https://www.cometchat.com/docs/rest-api/auth-tokens/create)) to issue a fresh token.
4. Send the token to the browser and place it in the widget config below.
5. The same token works for the CometChat Widget, UI Kit, or SDK.

Full walkthrough: [How to properly log in and create users in CometChat](https://community.cometchat.com/t/how-to-properly-log-in-and-create-users-in-cometchat/31).

**Use this when:**

* You need maximum security (no authKey exposed in the frontend).
* You have a custom backend or serverless functions.
* You want full control over user creation and authentication.

### Paste this into Footer (Code Injection)

```html lines highlight={6-7,9} theme={null}
<div id="cometChatMount"></div>
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>

<script>
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",
    mode: "authToken",
    authToken: "USER_AUTH_TOKEN",

    language: "en-US",      // optional, defaults to "en-US"

    mount: "#cometChatMount",
    width: "400px",
    height: "80vh",
    isDocked: true,
    //autoOpenFirstItem: false,
  };

  const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", startWidget);
  } else {
    startWidget();
  }
</script>
```

**Update these values:**

* `appID`, `region`, `authKey` | Copy from **Dashboard**.
* `authToken` | Generated by your backend and passed to this page.
* `language` | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`.
* `width`, `height`, `isDocked` | Adjust widget dimensions/placement.

***

### Troubleshooting

* **Widget not appearing?** Verify App ID, Region & Auth Key (or auth token), and check browser console for CSP/ad-blocker errors.
* **Login fails?** For UID mode, ensure the `uid` exists or is created on first visit; for auth token mode, make sure the token matches the logged-in user.
* **Styling issues?** Add custom CSS in **Design → Custom CSS** to override defaults.
* **Page-specific placement?** Use a page-level Code Block instead of the global Footer if you only want it on one page.

***

## Advanced JavaScript Controls

The embed works out of the box. Use the helpers below only if you need to open a specific chat, listen for widget events, or change settings on the fly.

### Before you follow advanced setup steps

1. Keep the standard widget snippet (from the Integration guide) on your page.
2. Add another `<script type="module">` right after it or inside your site builder’s “custom code” area.
3. Wrap your code in `window.addEventListener("DOMContentLoaded", () => { ... })` so it runs after the widget loads.
4. Replace placeholder text such as `UID`, `GUID`, and `LANGUAGE_CODE` with your real values.

When the widget is ready, it exposes a global helper named `CometChatApp`. Every example below shows a tiny recipe you can paste inside the script mentioned above.

### Open a chat or start a call

Use these helpers when you want the widget to jump straight to a person/group or begin a call. Drop the snippet inside your custom script and replace `UID`/`GUID` with real IDs from your CometChat app.

```js theme={null}
// Open chat with a specific person
CometChatApp.chatWithUser("UID");

// Open chat with a specific group
CometChatApp.chatWithGroup("GUID");

// Start a call with a person or a group
CometChatApp.callUser("UID");
CometChatApp.callGroup("GUID");

// Toggle extra UI bits
CometChatApp.showGroupActionMessages(true); // Show join/leave messages
CometChatApp.showDockedUnreadCount(true);   // Show unread badge on docked bubble
```

### Listen for widget events

Run your own code when something happens inside the widget—new message, docked bubble opened, or someone switching chats. Keep the event names as shown; just change what happens inside each arrow function.

```js theme={null}
// Fire when a new message arrives
CometChatApp.uiEvent("onMessageReceived", (message) => {
  console.log("New message:", message);
});

// Fire when the docked bubble opens or closes
CometChatApp.uiEvent("onOpenChat", () => console.log("Chat opened"));
CometChatApp.uiEvent("onCloseChat", () => console.log("Chat closed"));

// Fire when the user switches between conversations
CometChatApp.uiEvent("onActiveChatChanged", (chat) => {
  console.log("Now viewing:", chat);
});
```

### Create/Update users on the fly

* This will only work with authKey

If you collect names, avatars, or profile links on your site, you can push them straight into CometChat.
Replace the placeholders and run the snippet after the widget loads.

```js theme={null}
// Create or update a user
const user = new CometChatApp.CometChat.User("UID");
user.setName("User Name");
user.setAvatar("https://example.com/avatar.png");
user.setLink("https://example.com/profile");

CometChatApp.createOrUpdateUser(user).then((result) => {
  console.log("User saved:", result);
});
```

### Create/Update groups on the fly

If you want to create groups directly from your page, use this snippet. Replace the placeholders and run the snippet after the widget loads.

```js theme={null}
// Create or update a group
const group = new CometChatApp.CometChat.Group("GUID", "GROUP_NAME", "public");

CometChatApp.createOrUpdateGroup(group).then((result) => {
  console.log("Group saved:", result);
});
```

### Log users in or out with code

Use an auth token if you have a backend, or fall back to a plain UID for quick tests. Run these helpers after the widget loads.

```js theme={null}
// Sign in with a secure auth token from your server
CometChatApp.login({ authToken: "USER_AUTH_TOKEN" });

// ...or sign in directly with a UID (less secure, but fast for demos)
CometChatApp.login({ uid: "UID" });

// Sign the current user out
CometChatApp.logout();

// Listen for logout so you can clean up your UI
CometChatApp.uiEvent("onLogout", () => {
  console.log("User logged out");
});
```

### Control where data is stored

Pick whether the widget should remember login info in the browser tab only (`SESSION`) or across visits (`LOCAL`). Update the placeholders, then drop this script right after the default widget embed.

```js lines highlight={5} theme={null}
const COMETCHAT_DATA = {
  appID: "<YOUR_APP_ID>",
  appRegion: "<YOUR_APP_REGION>",
  authKey: "<YOUR_AUTH_KEY>",
  storageMode: "SESSION", // or "LOCAL" (default)
};

const COMETCHAT_USER_UID = "UID"; // The person who should log in

const COMETCHAT_LAUNCH_OPTIONS = {
  targetElementID: "cometChatMount",
  isDocked: true,
  width: "700px",
  height: "500px",
};

window.addEventListener("DOMContentLoaded", () => {
  CometChatApp.init(COMETCHAT_DATA)
    .then(() => CometChatApp.login({ uid: COMETCHAT_USER_UID }))
    .then(() => CometChatApp.launch(COMETCHAT_LAUNCH_OPTIONS))
    .catch(console.error);
});

// Optional extras:
// COMETCHAT_LAUNCH_OPTIONS.variantID = "YOUR_VARIANT_ID";
// COMETCHAT_LAUNCH_OPTIONS.chatType = "user" | "group";
// COMETCHAT_LAUNCH_OPTIONS.defaultChatID = "uid_or_guid";
// COMETCHAT_LAUNCH_OPTIONS.dockedAlignment = "left" | "right";
```

### Change the widget language

The widget auto-detects the browser language, but you can force it to any supported locale. Run the helper once after the widget loads and swap in the language code you need.

```js theme={null}
CometChatApp.localize("en-US"); // Example: force English (United States)
```

**Popular codes**

| Language                 | Code    |
| ------------------------ | ------- |
| English (United States)  | `en-US` |
| English (United Kingdom) | `en-GB` |
| Dutch                    | `nl`    |
| French                   | `fr`    |
| German                   | `de`    |
| Hindi                    | `hi`    |
| Italian                  | `it`    |
| Japanese                 | `ja`    |
| Korean                   | `ko`    |
| Portuguese               | `pt`    |
| Russian                  | `ru`    |
| Spanish                  | `es`    |
| Turkish                  | `tr`    |
| Chinese (Simplified)     | `zh`    |
| Chinese (Traditional)    | `zh-TW` |
| Malay                    | `ms`    |
| Swedish                  | `sv`    |
| Lithuanian               | `lt`    |
| Hungarian                | `hu`    |

Need another locale? Use the same pattern with its code (for example `CometChatApp.localize("ko")` for Korean).

***

## Need Help?

If you have questions or run into issues, reach out to [CometChat Support](https://www.cometchat.com/contact).


# CometChat Widget Builder For Squarespace
Source: https://www.cometchat.com/docs/widget/squarespace/overview

CometChat Widget Builder for Squarespace is a no-code solution for embedding a fully functional chat interface with a simple code snippet.

It provides a ready-to-use chat widget backed by CometChat's real-time infrastructure — add the embed code via Code Injection and go live.

With CometChat Widget Builder, you can:

* Embed chat and calling into any Squarespace website
* Customize themes, colors, and typography
* Toggle features on and off
* Go live with a simple embed code snippet

The widget connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling.

<Card title="Ready to add chat to your Squarespace website?" icon="rocket" href="/widget/squarespace/integration">
  Go to the Integration Guide
</Card>

***

## Widget Builder Features

**No-Code Visual Configuration** — Widget Builder provides a visual configuration environment for designing your chat widget before embedding.

**Toggle-Based Feature Control** — Messaging and calling features can be controlled through configuration settings in the Widget Builder in dashboard.

**Ready-to-Embed Code** — After configuration, Widget Builder generates a code snippet you can add to your Squarespace site via Code Injection.

***

## How to Use Widget Builder

### 1. Design

Customize your chat widget using the visual Widget Builder:

* **Configure layout** — Toggle all the required features in the dashboard.
* **Toggle features** — Turn chat and calling features on and off from the builder interface.
* **Themes** — Select between system, light, and dark themes. Choose custom colors and typography.

<Frame>
  <img />
</Frame>

### 2. Get Embed Code

Once configured, get the embed code snippet for your widget.

1. Click on **Get Embedded Code**
2. Note your app credentials (App ID, Auth Key, Region, Variant ID)
3. Copy the code snippet

### 3. Integrate

Add the embed code to your Squarespace website and go live.

1. **Open Code Injection** — Go to Settings → Advanced → Code Injection in your Squarespace dashboard
2. **Paste the code snippet** into the Footer section of Code Injection
3. **Configure credentials** — Set your App ID, Region, and Auth Key
4. **User Authentication** — CometChat uses a UID (User ID) to identify each user. Authenticate users to enable chat functionality.
5. **Launch** — Save and the chat widget is live on your Squarespace site

<Card title="Follow the full Integration Guide" icon="book" href="/widget/squarespace/integration">
  Step-by-step instructions for embedding the Widget Builder into your Squarespace website
</Card>

***

## Try Live Demo

Experience the CometChat Widget Builder in action:

<CardGroup>
  <Card title="Launch Live Demo" icon="play" href="https://preview.cometchat.com/" />
</CardGroup>

<Frame>
  <iframe title="YouTube video" />
</Frame>

***

## Need Help?

<CardGroup>
  <Card title="Developer Community" icon="users" href="https://community.cometchat.com/">
    Connect with other developers and get answers
  </Card>

  <Card title="Support Portal" icon="headset" href="https://help.cometchat.com/hc/en-us/requests/new">
    Contact our support team for assistance
  </Card>
</CardGroup>

***

## Related Resources

<CardGroup>
  <Card title="JavaScript Chat SDK" href="/sdk/javascript/overview">
    Learn more about the CometChat JavaScript SDK
  </Card>

  <Card title="HTML Widget" href="/widget/html/overview">
    Widget Builder for HTML websites
  </Card>

  <Card title="Wix Widget" href="/widget/wix/overview">
    Widget Builder for Wix websites
  </Card>

  <Card title="Webflow Widget" href="/widget/webflow/overview">
    Widget Builder for Webflow websites
  </Card>
</CardGroup>


# Add CometChat Widget to Webflow
Source: https://www.cometchat.com/docs/widget/webflow/integration

Drop the CometChat Widget into Webflow with an Embed component, then choose the sign-in flow: guest, logged-in IDs, or backend auth tokens.

Add the CometChat Widget with a single snippet in a Webflow **Embed** element. Pick the sign-in flow that matches your site: guests, auto-created users from your IDs, or backend-issued auth tokens.

**Choose how visitors sign in:**

<CardGroup>
  <Card title="Anonymous Chat (Guest Mode)" href="#1-anonymous-chat-guest-mode">
    * Visitors can chat without accounts.
    * Fastest, friction-free setup.
  </Card>

  <Card title="Create + Log In User On The Fly" href="#2-create-+-log-in-user-on-the-fly">
    * Auto-create CometChat users with your existing IDs (email, user ID, etc.).
    * No backend needed; CometChat creates users on first visit.
  </Card>

  <Card title="Backend-Created User (Auth Token Login)" href="#3-backend-created-user-auth-token-login">
    * Use your backend to issue auth tokens.
    * Keep your Auth Key off the page.
  </Card>
</CardGroup>

***

## Where to place the snippet in Webflow

<Steps>
  <Step title="Open Custom Code settings">
    Log in to Webflow, select your site, then open **Site Settings → Custom Code**.
  </Step>

  <Step title="Load the CometChat script once (recommended)">
    Add this to **Head Code** so every Embed can reuse it:

    ```html theme={null}
    <script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
    ```

    If you prefer, you can keep the script tag directly inside the Embed snippet instead.
  </Step>

  <Step title="Save and publish">
    Click **Save**, publish the site, then **Visit Website** to confirm the widget appears.
  </Step>
</Steps>

***

## 1. Anonymous Chat (Guest Mode)

**Use this when:** you want visitors to chat without signing in.

### Paste this into the Webflow Embed

```html theme={null}
<div id="cometChatMount"></div>

<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
<script>
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",   // e.g. "us", "eu", "in"
    mode: "guest",               // keep this as "guest"
    authKey: "YOUR_AUTH_KEY",

    language: "en-US",           // optional, defaults to "en-US"

    // Optional: how the guest appears in chat
    user: {
      name: "Guest User",
      avatar: "",                // e.g. "https://example.com/guest.png"
      link: ""                   // e.g. "https://example.com/profile"
    },

    // Widget placement + size
    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,               // true = docked widget (recommended)
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
    //autoOpenFirstItem: false,
  };

  const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", startWidget);
  } else {
    startWidget();
  }
</script>
```

### Update these values

| Setting                                 | What to enter / where to find it                                                                                                                                                              |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appID`, `region`, `authKey`            | Copy from **[Dashboard](https://app.cometchat.com)**                                                                                                                                          |
| `language`                              | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. |
| `user.name`, `user.avatar`, `user.link` | Optional guest display info—leave blank if you don’t need it.                                                                                                                                 |
| `width`, `height`, `isDocked`           | <p>Adjust the widget width & height.</p><p>**isDocked = true** - appears as icon on page and expands when clicked.</p> <p>**isDocked = false** - appears embedded on the page.</p>            |
| `variantID`                             | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used.                                                                     |
| `chatType`                              | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat).                                                                                   |
| `defaultChatID`                         | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads.                                                                                   |
| `dockedAlignment`                       | Controls the position of the docked widget interface on the page (left side or right side).                                                                                                   |
| `autoOpenFirstItem`                     | When set to false, the widget does not automatically open the first conversation on load. Defaults to true.                                                                                   |

***

## 2. Create + Log In User On The Fly

**Use this when:** you already have user IDs (email, username, member ID) and want to log people in with that ID automatically. CometChat creates the user the first time it sees the ID.

### Add this to Site Settings → Custom Code → Head Code

```html theme={null}
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
```

### Paste this into the Webflow Embed

```html theme={null}
<div id="cometChatMount"></div>

<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
<script>
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",      // e.g. "us", "eu", "in"
    mode: "uid",                    // keep this as "uid"
    authKey: "YOUR_AUTH_KEY",

    // IMPORTANT: this must be unique per user
    uid: "UNIQUE_USER_ID",          // e.g. "user_123", "customer_42"

    language: "en-US",              // optional, defaults to "en-US"

    // Optional: user profile shown in chat
    user: {
      name: "User Name",            // e.g. "Alex Johnson"
      avatar: "https://example.com/uid.png",
      link: "https://example.com/profile/uid"
    },

    // Widget placement + size
    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
    //autoOpenFirstItem: false,
  };

  const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", startWidget);
  } else {
    startWidget();
  }
</script>
```

### Update these values

| Setting                                 | What to enter / where to find it                                                                                                                                                              |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appID`, `region`, `authKey`            | Copy from **[Dashboard](https://app.cometchat.com)**                                                                                                                                          |
| `uid`                                   | Pass the unique ID from your page (for example `member.id`, email, or a UUID). CometChat creates the user the first time it sees that ID.                                                     |
| `language`                              | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. |
| `user.name`, `user.avatar`, `user.link` | Optional profile info you already store for that person.                                                                                                                                      |
| `mode`                                  | Keep this as `"uid"` so the widget knows you’re logging in with IDs.                                                                                                                          |
| `width`, `height`, `isDocked`           | <p>Adjust the widget width & height.</p><p>**isDocked = true** - appears as icon on page and expands when clicked.</p> <p>**isDocked = false** - appears embedded on the page.</p>            |
| `variantID`                             | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used.                                                                     |
| `chatType`                              | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat).                                                                                   |
| `defaultChatID`                         | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads.                                                                                   |
| `dockedAlignment`                       | Controls the position of the docked widget interface on the page (left side or right side).                                                                                                   |
| `autoOpenFirstItem`                     | When set to false, the widget does not automatically open the first conversation on load. Defaults to true.                                                                                   |

### Memberstack auto-login (Webflow + Memberstack, still UID flow)

Use this when your Webflow site uses Memberstack and you want the widget to log members in automatically (with a persistent guest fallback).

**Step 1 — add Memberstack to Head (Site Settings → Custom Code → Head):**

```html theme={null}
<!-- Memberstack Installation -->
<script
  data-memberstack-id="YOUR_PUBLIC_KEY_HERE"
  src="https://static.memberstack.com/scripts/v1/memberstack.js"
  type="text/javascript">
</script>
```

**Step 2 — add the chat widget (Site Settings → Custom Code → Footer, or a page Embed):**

```html theme={null}
<script src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
<div id="cometChatMount"></div>

<script>
  const COMETCHAT_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",
    authKey: "YOUR_AUTH_KEY",
    mount: "#cometChatMount",
    mode: "uid",
    language: "en-US",         // optional, defaults to "en-US"
    width: "700px",
    height: "500px",
    isDocked: true,
    // dockedAlignment: "right",
    // variantID: "YOUR_VARIANT_ID",
    // chatType: "user",
    // defaultChatID: "uid_or_guid",
  };

  const startWidget = async () => {
    try {
      const member = await window.$memberstackDom.getCurrentMember();
      let userConfig;

      if (member?.data) {
        const uid = member.data.id;
        const first = member.data.customFields["first-name"] || "";
        const last = member.data.customFields["last-name"] || "";
        const name = (first + " " + last).trim() || "User";

        userConfig = {
          uid,
          user: {
            name,
            avatar: member.data.profileImage || "",
            link: window.location.origin + "/profile/" + uid
          }
        };
      } else {
        let guestId = localStorage.getItem("cometchat_guest_id");
        if (!guestId) {
          guestId = "guest_" + Math.random().toString(36).substr(2, 9);
          localStorage.setItem("cometchat_guest_id", guestId);
        }

        userConfig = {
          uid: guestId,
          user: { name: "Guest User" }
        };
      }

      CometChatApp.CometChatAuth.start({
        ...COMETCHAT_CONFIG,
        ...userConfig
      });
    } catch (error) {
      console.error("CometChat init error:", error);

      const guestId = "guest_" + Math.random().toString(36).substr(2, 9);
      CometChatApp.CometChatAuth.start({
        ...COMETCHAT_CONFIG,
        uid: guestId,
        user: { name: "Guest User" }
      });
    }
  };

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", startWidget);
  } else {
    startWidget();
  }
</script>
```

**Optional (without reload):** listen for Memberstack auth changes and swap users/guests.

```html theme={null}
<script src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
<div id="cometChatMount"></div>

<script>
  const COMETCHAT_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",
    authKey: "YOUR_AUTH_KEY",
    mount: "#cometChatMount",
    mode: "uid",
    language: "en-US",         // optional, defaults to "en-US"
    width: "700px",
    height: "500px",
    isDocked: true,
  };

  let currentUid = null;

  const launchChat = (uid, name, avatar) => {
    if (currentUid === uid) return;
    currentUid = uid;

    CometChatApp.CometChatAuth.start({
      ...COMETCHAT_CONFIG,
      uid,
      user: { name: name || "User", avatar: avatar || "" }
    });
  };

  const launchGuestChat = () => {
    let guestId = localStorage.getItem("cometchat_guest_id");
    if (!guestId) {
      guestId = "guest_" + Math.random().toString(36).substr(2, 9);
      localStorage.setItem("cometchat_guest_id", guestId);
    }
    launchChat(guestId, "Guest User", "");
  };

  const initCometChat = async () => {
    try {
      const member = await window.$memberstackDom.getCurrentMember();

      if (member?.data) {
        const uid = member.data.id;
        const first = member.data.customFields["first-name"] || "";
        const last = member.data.customFields["last-name"] || "";
        const name = (first + " " + last).trim() || "User";

        launchChat(uid, name, member.data.profileImage || "");
      } else {
        launchGuestChat();
      }
    } catch (error) {
      console.error("CometChat error:", error);
      launchGuestChat();
    }
  };

  window.$memberstackDom?.onAuthChange(async (member) => {
    if (member?.data) {
      const uid = member.data.id;
      const first = member.data.customFields["first-name"] || "";
      const last = member.data.customFields["last-name"] || "";
      const name = (first + " " + last).trim() || "User";

      if (currentUid && currentUid !== uid) {
        await CometChatApp.logout();
        document.getElementById("cometChatMount").innerHTML = "";
        currentUid = null;
      }

      launchChat(uid, name, member.data.profileImage || "");
    } else {
      if (currentUid) {
        await CometChatApp.logout();
        document.getElementById("cometChatMount").innerHTML = "";
        currentUid = null;
      }
      launchGuestChat();
    }
  });

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", initCometChat);
  } else {
    initCometChat();
  }
</script>
```

***

## 3. Backend-Created User (Auth Token Login)

**Use this when:** people sign in through your backend and you generate their CometChat auth token server-side. This keeps your Auth Key off the page.

**Server-side flow (auth token login):**

1. Authenticate the user in your app.
2. If it’s their first time, call **Create User** ([https://www.cometchat.com/docs/rest-api/users/create](https://www.cometchat.com/docs/rest-api/users/create)) — you can also request an auth token in that call.
3. For returning users, call **Create Auth Token** ([https://www.cometchat.com/docs/rest-api/auth-tokens/create](https://www.cometchat.com/docs/rest-api/auth-tokens/create)) to issue a fresh token.
4. Send the token to the browser and place it in the widget config below.
5. The same token works for the CometChat Widget, UI Kit, or SDK.

Full walkthrough: [How to properly log in and create users in CometChat](https://community.cometchat.com/t/how-to-properly-log-in-and-create-users-in-cometchat/31).

### Paste this into the Webflow Embed

```html theme={null}
<div id="cometChatMount"></div>

<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
<script>
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",       // e.g. "us", "eu", "in"
    mode: "authToken",               // keep this as "authToken"

    // Generated BY YOUR BACKEND after user login
    authToken: "USER_AUTH_TOKEN",

    language: "en-US",               // optional, defaults to "en-US"

    // Widget placement + size
    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
    //autoOpenFirstItem: false,
  };

  const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", startWidget);
  } else {
    startWidget();
  }
</script>
```

### Update these values

| Setting                       | What to enter / where to find it                                                                                                                                                              |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appID`, `region`             | Copy from **[Dashboard](https://app.cometchat.com)**                                                                                                                                          |
| `mode`                        | Keep as `"authToken"` so the widget expects a server-issued token.                                                                                                                            |
| `authToken`                   | Generate on your **server**: (1) call the CometChat Auth Token API with your API key, (2) get the token for that user, (3) send it to the page and place it here.                             |
| `language`                    | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. |
| `width`, `height`, `isDocked` | <p>Adjust the widget width & height.</p><p>**isDocked = true** - appears as icon on page and expands when clicked.</p> <p>**isDocked = false** - appears embedded on the page.</p>            |
| `variantID`                   | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used.                                                                     |
| `chatType`                    | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat).                                                                                   |
| `defaultChatID`               | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads.                                                                                   |
| `dockedAlignment`             | Controls the position of the docked widget interface on the page (left side or right side).                                                                                                   |
| `autoOpenFirstItem`           | When set to false, the widget does not automatically open the first conversation on load. Defaults to true.                                                                                   |

***

### Troubleshooting

* **Widget not appearing?** Ensure the Embed is set to **Code** and the script loads (`chat-embed@1.x.x`). Publish the site after adding the snippet.
* **Login/auth errors?** For UID mode, ensure the `uid` is unique and you’re using an **App Auth Key** (not REST API key). For auth token mode, make sure the token matches the logged-in user.
* **Only guests showing?** Confirm you’re providing `uid` or `authToken` in the snippet and that your page logic passes the right IDs.
* **Embed clipped?** Resize the Embed element to give the widget enough space (`width`/`height` also configurable in the config).

***

## Advanced JavaScript Controls

The embed works out of the box. Use the helpers below only if you need to open a specific chat, listen for widget events, or change settings on the fly.

### Before you follow advanced setup steps

1. Keep the standard widget snippet (from the Integration guide) on your page.
2. Add another `<script type="module">` right after it or inside your site builder’s “custom code” area.
3. Wrap your code in `window.addEventListener("DOMContentLoaded", () => { ... })` so it runs after the widget loads.
4. Replace placeholder text such as `UID`, `GUID`, and `LANGUAGE_CODE` with your real values.

When the widget is ready, it exposes a global helper named `CometChatApp`. Every example below shows a tiny recipe you can paste inside the script mentioned above.

### Open a chat or start a call

Use these helpers when you want the widget to jump straight to a person/group or begin a call. Drop the snippet inside your custom script and replace `UID`/`GUID` with real IDs from your CometChat app.

```js theme={null}
// Open chat with a specific person
CometChatApp.chatWithUser("UID");

// Open chat with a specific group
CometChatApp.chatWithGroup("GUID");

// Start a call with a person or a group
CometChatApp.callUser("UID");
CometChatApp.callGroup("GUID");

// Toggle extra UI bits
CometChatApp.showGroupActionMessages(true); // Show join/leave messages
CometChatApp.showDockedUnreadCount(true);   // Show unread badge on docked bubble
```

### Listen for widget events

Run your own code when something happens inside the widget—new message, docked bubble opened, or someone switching chats. Keep the event names as shown; just change what happens inside each arrow function.

```js theme={null}
// Fire when a new message arrives
CometChatApp.uiEvent("onMessageReceived", (message) => {
  console.log("New message:", message);
});

// Fire when the docked bubble opens or closes
CometChatApp.uiEvent("onOpenChat", () => console.log("Chat opened"));
CometChatApp.uiEvent("onCloseChat", () => console.log("Chat closed"));

// Fire when the user switches between conversations
CometChatApp.uiEvent("onActiveChatChanged", (chat) => {
  console.log("Now viewing:", chat);
});
```

### Create/Update users on the fly

* This will only work with authKey

If you collect names, avatars, or profile links on your site, you can push them straight into CometChat.
Replace the placeholders and run the snippet after the widget loads.

```js theme={null}
// Create or update a user
const user = new CometChatApp.CometChat.User("UID");
user.setName("User Name");
user.setAvatar("https://example.com/avatar.png");
user.setLink("https://example.com/profile");

CometChatApp.createOrUpdateUser(user).then((result) => {
  console.log("User saved:", result);
});
```

### Create/Update groups on the fly

If you want to create groups directly from your page, use this snippet. Replace the placeholders and run the snippet after the widget loads.

```js theme={null}
// Create or update a group
const group = new CometChatApp.CometChat.Group("GUID", "GROUP_NAME", "public");

CometChatApp.createOrUpdateGroup(group).then((result) => {
  console.log("Group saved:", result);
});
```

### Log users in or out with code

Use an auth token if you have a backend, or fall back to a plain UID for quick tests. Run these helpers after the widget loads.

```js theme={null}
// Sign in with a secure auth token from your server
CometChatApp.login({ authToken: "USER_AUTH_TOKEN" });

// ...or sign in directly with a UID (less secure, but fast for demos)
CometChatApp.login({ uid: "UID" });

// Sign the current user out
CometChatApp.logout();

// Listen for logout so you can clean up your UI
CometChatApp.uiEvent("onLogout", () => {
  console.log("User logged out");
});
```

### Control where data is stored

Pick whether the widget should remember login info in the browser tab only (`SESSION`) or across visits (`LOCAL`). Update the placeholders, then drop this script right after the default widget embed.

```js lines highlight={5} theme={null}
const COMETCHAT_DATA = {
  appID: "<YOUR_APP_ID>",
  appRegion: "<YOUR_APP_REGION>",
  authKey: "<YOUR_AUTH_KEY>",
  storageMode: "SESSION", // or "LOCAL" (default)
};

const COMETCHAT_USER_UID = "UID"; // The person who should log in

const COMETCHAT_LAUNCH_OPTIONS = {
  targetElementID: "cometChatMount",
  isDocked: true,
  width: "700px",
  height: "500px",
};

window.addEventListener("DOMContentLoaded", () => {
  CometChatApp.init(COMETCHAT_DATA)
    .then(() => CometChatApp.login({ uid: COMETCHAT_USER_UID }))
    .then(() => CometChatApp.launch(COMETCHAT_LAUNCH_OPTIONS))
    .catch(console.error);
});

// Optional extras:
// COMETCHAT_LAUNCH_OPTIONS.variantID = "YOUR_VARIANT_ID";
// COMETCHAT_LAUNCH_OPTIONS.chatType = "user" | "group";
// COMETCHAT_LAUNCH_OPTIONS.defaultChatID = "uid_or_guid";
// COMETCHAT_LAUNCH_OPTIONS.dockedAlignment = "left" | "right";
```

### Change the widget language

The widget auto-detects the browser language, but you can force it to any supported locale. Run the helper once after the widget loads and swap in the language code you need.

```js theme={null}
CometChatApp.localize("en-US"); // Example: force English (United States)
```

**Popular codes**

| Language                 | Code    |
| ------------------------ | ------- |
| English (United States)  | `en-US` |
| English (United Kingdom) | `en-GB` |
| Dutch                    | `nl`    |
| French                   | `fr`    |
| German                   | `de`    |
| Hindi                    | `hi`    |
| Italian                  | `it`    |
| Japanese                 | `ja`    |
| Korean                   | `ko`    |
| Portuguese               | `pt`    |
| Russian                  | `ru`    |
| Spanish                  | `es`    |
| Turkish                  | `tr`    |
| Chinese (Simplified)     | `zh`    |
| Chinese (Traditional)    | `zh-TW` |
| Malay                    | `ms`    |
| Swedish                  | `sv`    |
| Lithuanian               | `lt`    |
| Hungarian                | `hu`    |

Need another locale? Use the same pattern with its code (for example `CometChatApp.localize("ko")` for Korean).

***

## Need Help?

If you have questions or run into issues, reach out to [CometChat Support](https://www.cometchat.com/contact).


# CometChat Widget Builder For Webflow
Source: https://www.cometchat.com/docs/widget/webflow/overview

CometChat Widget Builder for Webflow is a no-code solution for embedding a fully functional chat interface with a simple code snippet.

It provides a ready-to-use chat widget backed by CometChat's real-time infrastructure — add the embed code to your Webflow project and go live.

With CometChat Widget Builder, you can:

* Embed chat and calling into any Webflow website
* Customize themes, colors, and typography
* Toggle features on and off
* Go live with a simple embed code snippet

The widget connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling.

<Card title="Ready to add chat to your Webflow website?" icon="rocket" href="/widget/webflow/integration">
  Go to the Integration Guide
</Card>

***

## Widget Builder Features

**No-Code Visual Configuration** — Widget Builder provides a visual configuration environment for designing your chat widget before embedding.

**Toggle-Based Feature Control** — Messaging and calling features can be controlled through configuration settings in the Widget Builder in dashboard.

**Ready-to-Embed Code** — After configuration, Widget Builder generates a code snippet you can add to your Webflow project using a custom code embed.

***

## How to Use Widget Builder

### 1. Design

Customize your chat widget using the visual Widget Builder:

* **Configure layout** — Toggle all the required features in the dashboard.
* **Toggle features** — Turn chat and calling features on and off from the builder interface.
* **Themes** — Select between system, light, and dark themes. Choose custom colors and typography.

<Frame>
  <img />
</Frame>

### 2. Get Embed Code

Once configured, get the embed code snippet for your widget.

1. Click on **Get Embedded Code**
2. Note your app credentials (App ID, Auth Key, Region, Variant ID)
3. Copy the code snippet

### 3. Integrate

Add the embed code to your Webflow website and go live.

1. **Add a custom code embed** — In the Webflow Designer, add an Embed element to your page
2. **Paste the code snippet** into the Embed element
3. **Configure credentials** — Set your App ID, Region, and Auth Key
4. **User Authentication** — CometChat uses a UID (User ID) to identify each user. Authenticate users to enable chat functionality.
5. **Launch** — Publish your Webflow site and the chat widget is live

<Card title="Follow the full Integration Guide" icon="book" href="/widget/webflow/integration">
  Step-by-step instructions for embedding the Widget Builder into your Webflow website
</Card>

***

## Try Live Demo

Experience the CometChat Widget Builder in action:

<CardGroup>
  <Card title="Launch Live Demo" icon="play" href="https://preview.cometchat.com/" />
</CardGroup>

<Frame>
  <iframe title="YouTube video" />
</Frame>

***

## Need Help?

<CardGroup>
  <Card title="Developer Community" icon="users" href="https://community.cometchat.com/">
    Connect with other developers and get answers
  </Card>

  <Card title="Support Portal" icon="headset" href="https://help.cometchat.com/hc/en-us/requests/new">
    Contact our support team for assistance
  </Card>
</CardGroup>

***

## Related Resources

<CardGroup>
  <Card title="JavaScript Chat SDK" href="/sdk/javascript/overview">
    Learn more about the CometChat JavaScript SDK
  </Card>

  <Card title="HTML Widget" href="/widget/html/overview">
    Widget Builder for HTML websites
  </Card>

  <Card title="Shopify Widget" href="/widget/shopify/overview">
    Widget Builder for Shopify stores
  </Card>

  <Card title="Squarespace Widget" href="/widget/squarespace/overview">
    Widget Builder for Squarespace websites
  </Card>
</CardGroup>


# Add CometChat Widget to Wix
Source: https://www.cometchat.com/docs/widget/wix/integration

Drop the CometChat Widget into Wix using an HTML Embed block, then choose the sign-in flow that fits your site.

Add the CometChat Widget with a single snippet inside Wix’s **Embed HTML** element. Pick the sign-in flow that matches your site: guests, auto-created users by ID, or backend-issued auth tokens.

**Choose how visitors sign in:**

<CardGroup>
  <Card title="Anonymous Chat (Guest Mode)" href="#1-anonymous-chat-guest-mode">
    * Visitors can chat without accounts.
    * Fastest, friction-free setup.
  </Card>

  <Card title="Create + Log In User On The Fly" href="#2-create-+-log-in-user-on-the-fly">
    * Auto-create CometChat users with your existing IDs (email, user ID, etc.).
    * No backend needed; CometChat creates users on first visit.
  </Card>

  <Card title="Backend-Created User (Auth Token Login)" href="#3-backend-created-user-auth-token-login">
    * Use your backend to issue auth tokens.
    * Keep your Auth Key off the page.
  </Card>
</CardGroup>

***

## Where to place the snippet in Wix

1. In the Wix Editor, open the page where chat should appear.
2. Click **Add → Embed Code → Embed HTML**, then drag the block to where you want the widget (bottom-right is common).
3. Click **Enter Code / Edit Code**, switch to **Code** mode, and paste the snippet from your chosen option.
4. Resize the embed container if needed; the widget will fill the element.
5. Publish/preview the site to confirm the widget loads.

***

## 1. Anonymous Chat (Guest Mode)

**Use this when:** you want visitors to chat without signing in.

### Paste this into the Wix Embed HTML element

```html theme={null}
<div id="cometChatMount"></div>

<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
<script>
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",
    mode: "guest",
    authKey: "YOUR_AUTH_KEY",

    language: "en-US",          // optional, defaults to "en-US"

    // Optional: how the guest appears in chat
    user: {
      name: "Guest User",
      avatar: "",
      link: ""
    },

    // Widget placement + size
    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
    //autoOpenFirstItem: false,
  };

  const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", startWidget);
  } else {
    startWidget();
  }
</script>
```

### Update these values

| Setting                                 | What to enter / where to find it                                                                                                                                                              |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appID`, `region`, `authKey`            | Copy from **[Dashboard](https://app.cometchat.com)**                                                                                                                                          |
| `language`                              | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. |
| `user.name`, `user.avatar`, `user.link` | Optional guest display info—leave blank if you don’t need it.                                                                                                                                 |
| `width`, `height`, `isDocked`           | <p>Adjust the widget width & height.</p><p>**isDocked = true** - appears as icon on page and expands when clicked.</p> <p>**isDocked = false** - appears embedded on the page.</p>            |
| `variantID`                             | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used.                                                                     |
| `chatType`                              | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat).                                                                                   |
| `defaultChatID`                         | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads.                                                                                   |
| `dockedAlignment`                       | Controls the position of the docked widget interface on the page (left side or right side).                                                                                                   |
| `autoOpenFirstItem`                     | When set to false, the widget does not automatically open the first conversation on load. Defaults to true.                                                                                   |

***

## 2. Create + Log In User On The Fly

**Use this when:** you already have user IDs (email, username, member ID) and want to log people in with that ID automatically. CometChat creates the user the first time it sees the ID.

### Paste this into the Wix Embed HTML element

```html theme={null}
<div id="cometChatMount"></div>

<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
<script>
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",      // e.g. "us", "eu", "in"
    mode: "uid",                    // keep this as "uid"
    authKey: "YOUR_AUTH_KEY",

    // IMPORTANT: this must be unique per user
    uid: "UNIQUE_USER_ID",          // e.g. "user_123", "customer_42"

    language: "en-US",              // optional, defaults to "en-US"

    // Optional: user profile shown in chat
    user: {
      name: "User Name",            // e.g. "Alex Johnson"
      avatar: "https://example.com/uid.png",
      link: "https://example.com/profile/uid"
    },

    // Widget placement + size
    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
    //autoOpenFirstItem: false,
  };

  const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", startWidget);
  } else {
    startWidget();
  }
</script>
```

### Update these values

| Setting                                 | What to enter / where to find it                                                                                                                                                              |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appID`, `region`, `authKey`            | Copy from **[Dashboard](https://app.cometchat.com)**                                                                                                                                          |
| `uid`                                   | Pass the unique ID from your page (for example `member.id`, email, or a UUID). CometChat creates the user the first time it sees that ID.                                                     |
| `language`                              | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. |
| `user.name`, `user.avatar`, `user.link` | Optional profile info you already store for that person.                                                                                                                                      |
| `mode`                                  | Keep this as `"uid"` so the widget knows you’re logging in with IDs.                                                                                                                          |
| `width`, `height`, `isDocked`           | <p>Adjust the widget width & height.</p><p>**isDocked = true** - appears as icon on page and expands when clicked.</p> <p>**isDocked = false** - appears embedded on the page.</p>            |
| `variantID`                             | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used.                                                                     |
| `chatType`                              | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat).                                                                                   |
| `defaultChatID`                         | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads.                                                                                   |
| `dockedAlignment`                       | Controls the position of the docked widget interface on the page (left side or right side).                                                                                                   |
| `autoOpenFirstItem`                     | When set to false, the widget does not automatically open the first conversation on load. Defaults to true.                                                                                   |

***

## 3. Backend-Created User (Auth Token Login)

**Use this when:** people sign in through your backend and you generate their CometChat auth token server-side. This keeps your Auth Key off the page.

**Server-side flow (auth token login):**

1. Authenticate the user in your app.
2. If it’s their first time, call **Create User** ([https://www.cometchat.com/docs/rest-api/users/create](https://www.cometchat.com/docs/rest-api/users/create)) — you can also request an auth token in that call.
3. For returning users, call **Create Auth Token** ([https://www.cometchat.com/docs/rest-api/auth-tokens/create](https://www.cometchat.com/docs/rest-api/auth-tokens/create)) to issue a fresh token.
4. Send the token to the browser and place it in the widget config below.
5. The same token works for the CometChat Widget, UI Kit, or SDK.

Full walkthrough: [How to properly log in and create users in CometChat](https://community.cometchat.com/t/how-to-properly-log-in-and-create-users-in-cometchat/31).

### Paste this into the Wix Embed HTML element

```html theme={null}
<div id="cometChatMount"></div>

<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
<script>
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",       // e.g. "us", "eu", "in"
    mode: "authToken",               // keep this as "authToken"

    // Generated BY YOUR BACKEND after user login
    authToken: "USER_AUTH_TOKEN",

    language: "en-US",               // optional, defaults to "en-US"

    // Widget placement + size
    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
    //autoOpenFirstItem: false,
  };

  const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", startWidget);
  } else {
    startWidget();
  }
</script>
```

### Update these values

| Setting                       | What to enter / where to find it                                                                                                                                                              |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appID`, `region`             | Copy from **[Dashboard](https://app.cometchat.com)**                                                                                                                                          |
| `mode`                        | Keep as `"authToken"` so the widget expects a server-issued token.                                                                                                                            |
| `authToken`                   | Generate on your **server**: (1) call the CometChat Auth Token API with your API key, (2) get the token for that user, (3) send it to the page and place it here.                             |
| `language`                    | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. |
| `width`, `height`, `isDocked` | <p>Adjust the widget width & height.</p><p>**isDocked = true** - appears as icon on page and expands when clicked.</p> <p>**isDocked = false** - appears embedded on the page.</p>            |
| `variantID`                   | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used.                                                                     |
| `chatType`                    | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat).                                                                                   |
| `defaultChatID`               | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads.                                                                                   |
| `dockedAlignment`             | Controls the position of the docked widget interface on the page (left side or right side).                                                                                                   |
| `autoOpenFirstItem`           | When set to false, the widget does not automatically open the first conversation on load. Defaults to true.                                                                                   |

***

### Troubleshooting

* **Widget not appearing?** Confirm the HTML Embed is set to **Code** and the script loads (`chat-embed@1.x.x`). Resize the embed box if it’s too small.
* **Login/auth errors?** For UID mode, ensure the `uid` is unique and you’re using an **App Auth Key** (not REST API key). For auth token mode, make sure the token matches the logged-in user.
* **Still showing guests only?** Make sure you’re actually providing `uid` or `authToken` in the snippet (and that your page logic passes the right IDs).
* **Page preview vs published:** Test on a published page if preview blocks scripts.

***

## Advanced JavaScript Controls

The embed works out of the box. Use the helpers below only if you need to open a specific chat, listen for widget events, or change settings on the fly.

### Before you follow advanced setup steps

1. Keep the standard widget snippet (from the Integration guide) on your page.
2. Add another `<script type="module">` right after it or inside your site builder’s “custom code” area.
3. Wrap your code in `window.addEventListener("DOMContentLoaded", () => { ... })` so it runs after the widget loads.
4. Replace placeholder text such as `UID`, `GUID`, and `LANGUAGE_CODE` with your real values.

When the widget is ready, it exposes a global helper named `CometChatApp`. Every example below shows a tiny recipe you can paste inside the script mentioned above.

### Open a chat or start a call

Use these helpers when you want the widget to jump straight to a person/group or begin a call. Drop the snippet inside your custom script and replace `UID`/`GUID` with real IDs from your CometChat app.

```js theme={null}
// Open chat with a specific person
CometChatApp.chatWithUser("UID");

// Open chat with a specific group
CometChatApp.chatWithGroup("GUID");

// Start a call with a person or a group
CometChatApp.callUser("UID");
CometChatApp.callGroup("GUID");

// Toggle extra UI bits
CometChatApp.showGroupActionMessages(true); // Show join/leave messages
CometChatApp.showDockedUnreadCount(true);   // Show unread badge on docked bubble
```

### Listen for widget events

Run your own code when something happens inside the widget—new message, docked bubble opened, or someone switching chats. Keep the event names as shown; just change what happens inside each arrow function.

```js theme={null}
// Fire when a new message arrives
CometChatApp.uiEvent("onMessageReceived", (message) => {
  console.log("New message:", message);
});

// Fire when the docked bubble opens or closes
CometChatApp.uiEvent("onOpenChat", () => console.log("Chat opened"));
CometChatApp.uiEvent("onCloseChat", () => console.log("Chat closed"));

// Fire when the user switches between conversations
CometChatApp.uiEvent("onActiveChatChanged", (chat) => {
  console.log("Now viewing:", chat);
});
```

### Create/Update users on the fly

* This will only work with authKey

If you collect names, avatars, or profile links on your site, you can push them straight into CometChat.
Replace the placeholders and run the snippet after the widget loads.

```js theme={null}
// Create or update a user
const user = new CometChatApp.CometChat.User("UID");
user.setName("User Name");
user.setAvatar("https://example.com/avatar.png");
user.setLink("https://example.com/profile");

CometChatApp.createOrUpdateUser(user).then((result) => {
  console.log("User saved:", result);
});
```

### Create/Update groups on the fly

If you want to create groups directly from your page, use this snippet. Replace the placeholders and run the snippet after the widget loads.

```js theme={null}
// Create or update a group
const group = new CometChatApp.CometChat.Group("GUID", "GROUP_NAME", "public");

CometChatApp.createOrUpdateGroup(group).then((result) => {
  console.log("Group saved:", result);
});
```

### Log users in or out with code

Use an auth token if you have a backend, or fall back to a plain UID for quick tests. Run these helpers after the widget loads.

```js theme={null}
// Sign in with a secure auth token from your server
CometChatApp.login({ authToken: "USER_AUTH_TOKEN" });

// ...or sign in directly with a UID (less secure, but fast for demos)
CometChatApp.login({ uid: "UID" });

// Sign the current user out
CometChatApp.logout();

// Listen for logout so you can clean up your UI
CometChatApp.uiEvent("onLogout", () => {
  console.log("User logged out");
});
```

### Control where data is stored

Pick whether the widget should remember login info in the browser tab only (`SESSION`) or across visits (`LOCAL`). Update the placeholders, then drop this script right after the default widget embed.

```js lines highlight={5} theme={null}
const COMETCHAT_DATA = {
  appID: "<YOUR_APP_ID>",
  appRegion: "<YOUR_APP_REGION>",
  authKey: "<YOUR_AUTH_KEY>",
  storageMode: "SESSION", // or "LOCAL" (default)
};

const COMETCHAT_USER_UID = "UID"; // The person who should log in

const COMETCHAT_LAUNCH_OPTIONS = {
  targetElementID: "cometChatMount",
  isDocked: true,
  width: "700px",
  height: "500px",
};

window.addEventListener("DOMContentLoaded", () => {
  CometChatApp.init(COMETCHAT_DATA)
    .then(() => CometChatApp.login({ uid: COMETCHAT_USER_UID }))
    .then(() => CometChatApp.launch(COMETCHAT_LAUNCH_OPTIONS))
    .catch(console.error);
});

// Optional extras:
// COMETCHAT_LAUNCH_OPTIONS.variantID = "YOUR_VARIANT_ID";
// COMETCHAT_LAUNCH_OPTIONS.chatType = "user" | "group";
// COMETCHAT_LAUNCH_OPTIONS.defaultChatID = "uid_or_guid";
// COMETCHAT_LAUNCH_OPTIONS.dockedAlignment = "left" | "right";
```

### Change the widget language

The widget auto-detects the browser language, but you can force it to any supported locale. Run the helper once after the widget loads and swap in the language code you need.

```js theme={null}
CometChatApp.localize("en-US"); // Example: force English (United States)
```

**Popular codes**

| Language                 | Code    |
| ------------------------ | ------- |
| English (United States)  | `en-US` |
| English (United Kingdom) | `en-GB` |
| Dutch                    | `nl`    |
| French                   | `fr`    |
| German                   | `de`    |
| Hindi                    | `hi`    |
| Italian                  | `it`    |
| Japanese                 | `ja`    |
| Korean                   | `ko`    |
| Portuguese               | `pt`    |
| Russian                  | `ru`    |
| Spanish                  | `es`    |
| Turkish                  | `tr`    |
| Chinese (Simplified)     | `zh`    |
| Chinese (Traditional)    | `zh-TW` |
| Malay                    | `ms`    |
| Swedish                  | `sv`    |
| Lithuanian               | `lt`    |
| Hungarian                | `hu`    |

Need another locale? Use the same pattern with its code (for example `CometChatApp.localize("ko")` for Korean).

***

## Need Help?

If you have questions or run into issues, reach out to [CometChat Support](https://www.cometchat.com/contact).


# CometChat Widget Builder For Wix
Source: https://www.cometchat.com/docs/widget/wix/overview

CometChat Widget Builder for Wix is a no-code solution that lets you embed a fully functional chat interface into any Wix website using a simple code snippet.

It provides a ready-to-use chat widget backed by CometChat's real-time infrastructure — add the embed code to your Wix site and go live.

With CometChat Widget Builder, you can:

* Embed chat and calling into any Wix website
* Customize themes, colors, and typography
* Toggle features on and off
* Go live with a simple embed code snippet

The widget connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling.

<Card title="Ready to add chat to your Wix website?" icon="rocket" href="/widget/wix/integration">
  Go to the Integration Guide
</Card>

***

## Widget Builder Features

**No-Code Visual Configuration** — Widget Builder provides a visual configuration environment for designing your chat widget before embedding.

**Toggle-Based Feature Control** — Messaging and calling features can be controlled through configuration settings in the Widget Builder in dashboard.

**Ready-to-Embed Code** — After configuration, Widget Builder generates a code snippet you can embed into your Wix site using the HTML embed element.

***

## How to Use Widget Builder

### 1. Design

Customize your chat widget using the visual Widget Builder:

* **Configure layout** — Toggle all the required features in the dashboard.
* **Toggle features** — Turn chat and calling features on and off from the builder interface.
* **Themes** — Select between system, light, and dark themes. Choose custom colors and typography.

<Frame>
  <img />
</Frame>

### 2. Get Embed Code

Once configured, get the embed code snippet for your widget.

1. Click on **Get Embedded Code**
2. Note your app credentials (App ID, Auth Key, Region, Variant ID)
3. Copy the code snippet

### 3. Integrate

Add the embed code to your Wix website and go live.

1. **Add an HTML embed element** — In the Wix Editor, add an Embed HTML component to your page
2. **Paste the code snippet** into the HTML embed element
3. **Configure credentials** — Set your App ID, Region, and Auth Key
4. **User Authentication** — CometChat uses a UID (User ID) to identify each user. Authenticate users to enable chat functionality.
5. **Launch** — Publish your Wix site and the chat widget is live

<Card title="Follow the full Integration Guide" icon="book" href="/widget/wix/integration">
  Step-by-step instructions for embedding the Widget Builder into your Wix website
</Card>

***

## Try Live Demo

Experience the CometChat Widget Builder in action:

<CardGroup>
  <Card title="Launch Live Demo" icon="play" href="https://preview.cometchat.com/" />
</CardGroup>

<Frame>
  <iframe title="YouTube video" />
</Frame>

***

## Need Help?

<CardGroup>
  <Card title="Developer Community" icon="users" href="https://community.cometchat.com/">
    Connect with other developers and get answers
  </Card>

  <Card title="Support Portal" icon="headset" href="https://help.cometchat.com/hc/en-us/requests/new">
    Contact our support team for assistance
  </Card>
</CardGroup>

***

## Related Resources

<CardGroup>
  <Card title="JavaScript Chat SDK" href="/sdk/javascript/overview">
    Learn more about the CometChat JavaScript SDK
  </Card>

  <Card title="HTML Widget" href="/widget/html/overview">
    Widget Builder for HTML websites
  </Card>

  <Card title="WordPress Widget" href="/widget/wordpress/overview">
    Widget Builder for WordPress websites
  </Card>

  <Card title="Squarespace Widget" href="/widget/squarespace/overview">
    Widget Builder for Squarespace websites
  </Card>
</CardGroup>


# Add CometChat Widget to WordPress via Plugin
Source: https://www.cometchat.com/docs/widget/wordpress/integration

Comprehensive guide to install, configure, and extend the new CometChat WordPress plugin.

## Before getting started

Go through the [Overview](https://app.cometchat.com/) to generate your Widget from the CometChat Dashboard.\
Ensure you have:

* A WordPress site (5.0+)
* PHP 7.2 or higher
* Your **App ID**, **Region**, and **REST API Key**

## Quick Steps to Embed CometChat Widget

<Steps>
  <Step title="Download the Plugin ZIP">
    1. Download the CometChat plugin from [here](https://kernl.us/api/v1/archive/688bbf1f5a0dc110ce1bfafe).
    2. Save the `cometchat-pro.zip` file to your computer.
  </Step>

  <Step title="Install & Activate the Plugin">
    1. In WordPress Admin, navigate to **Plugins → Add Plugin**.

    <img alt="Main dashboard interface" />

    2. Click **Upload Plugin**, choose `cometchat-pro.zip`, and click **Install Now**.

    <img alt="Main dashboard interface" />

    3. Once installed, click **Activate Plugin**.

    <img alt="Main dashboard interface" />
  </Step>

  <Step title="CometChat Credentials">
    To use **CometChat UI Kit**, you first need to register on the **CometChat Dashboard**.

    After registering, create a **new app** and retrieve your **authentication details**:

    1. Navigate to **Application**, then select the **Credentials** section.

    2. Note down the following:

       * **App ID**
       * **Region**
       * **REST API Key** (from **Credentials → REST API Keys**)
  </Step>

  <Step title="Configure Plugin Settings">
    1. In WordPress Admin, go to **Settings → CometChat** (or click **Settings** on the CometChat row under **Plugins**).
    2. Fill in:
       * **App ID** and **App Region** — from **Dashboard → App → Credentials**.
       * **API Version** — select **3**. Leaving this unset falls back to the legacy v2 API and user creation will fail.
       * **REST API Key** — from **Dashboard → App → Credentials → REST API Keys**. This is the REST API key, not the Auth Key.
    3. Click **Update Settings**.

    <Note>
      **How users are authenticated:** The plugin renders the chat widget on your site's frontend only for **logged-in WordPress users** — it is gated by WordPress's `is_user_logged_in()`. For each logged-in visitor, the plugin automatically maps the WordPress user to a CometChat user whose **UID is the WordPress numeric user ID** and signs them in with a securely generated auth token; you do **not** configure a fixed user UID in the plugin. Logged-out visitors don't see the widget — the shortcode renders the literal text *"Please login to use this feature."* instead. Where the widget appears (inline vs. floating) is set per placement by the shortcode's `docked` attribute, shown below.
    </Note>
  </Step>

  <Step title="Embed Widget Inline (Embedded Mode)">
    1. Edit any Page/Post, add a **Shortcode** block, and insert:
       ```text theme={null}
       [cometchat 
         width="600px"                      <!-- Widget width (Required) -->
         height="600px"                     <!-- Widget height (Required) -->
         docked="false"                     <!-- true = floating bubble, false = embedded (Required) -->
         variant-id="default-variant"       <!-- Optional | Variant ID -->
         chat-type="user"                   <!-- Optional | user / group -->
         default-chat-id="uid_or_guid"      <!-- Optional | UID or GUID to open by default -->
       ]
       ```
    2. Publish or update the Page/Post.
  </Step>

  <Step title="Docked Widget (Floating Mode)">
    1. Edit any Page/Post (or site-wide), add a **Shortcode** block, and insert:
       ```text theme={null}
       [cometchat 
         width="400px"                      
         height="800px"                     
         docked="true"                      <!-- true = floating bubble, false = embedded (Required) -->
         variant-id="default-variant"       <!-- Optional | Variant ID -->
         docked-alignment="right"           <!-- Optional | left / right (only applies if docked=true) -->
         chat-type="user"                   <!-- Optional | user / group -->
         default-chat-id="uid_or_guid"      <!-- Optional | UID or GUID to open by default -->
       ]
       ```
    2. Publish or update to see the widget docked on the chosen side.
  </Step>

  <Step title="Show the Docked Widget on Every Page">
    In **Settings → CometChat**, paste your docked shortcode (`docked="true"`) into the **"Load CometChat on all pages/sitewide?"** field and click **Update Settings**. The plugin then renders the widget in the footer of every page for logged-in WordPress users.

    <Note>
      For logged-out visitors, a sitewide shortcode prints *"Please login to use this feature."* on every page. Leave the field blank or hide `#cometchat` via CSS if that isn't wanted.
    </Note>
  </Step>
</Steps>

***

## Advanced JavaScript APIs

Once the widget is loaded, interact with it via the global `CometChatApp` object:

### Open a chat or start a call

Use these helpers when you want the widget to jump straight to a person/group or begin a call. Drop the snippet inside your custom script and replace `UID`/`GUID` with real IDs from your CometChat app.

```js theme={null} theme={null} theme={null}
// Open chat with a specific person
CometChatApp.chatWithUser("UID");

// Open chat with a specific group
CometChatApp.chatWithGroup("GUID");

// Start a call with a person or a group
CometChatApp.callUser("UID");
CometChatApp.callGroup("GUID");

// Toggle extra UI bits
CometChatApp.showGroupActionMessages(true); // Show join/leave messages
CometChatApp.showDockedUnreadCount(true);   // Show unread badge on docked bubble
```

### Listen for widget events

Run your own code when something happens inside the widget—new message, docked bubble opened, or someone switching chats. Keep the event names as shown; just change what happens inside each arrow function.

```js theme={null} theme={null} theme={null}
// Fire when a new message arrives
CometChatApp.uiEvent("onMessageReceived", (message) => {
  console.log("New message:", message);
});

// Fire when the docked bubble opens or closes
CometChatApp.uiEvent("onOpenChat", () => console.log("Chat opened"));
CometChatApp.uiEvent("onCloseChat", () => console.log("Chat closed"));

// Fire when the user switches between conversations
CometChatApp.uiEvent("onActiveChatChanged", (chat) => {
  console.log("Now viewing:", chat);
});
```

### Change the widget language

The widget auto-detects the browser language, but you can force it to any supported locale. Run the helper once after the widget loads and swap in the language code you need.

```js theme={null} theme={null} theme={null}
CometChatApp.localize("en-US"); // Example: force English (United States)
```

**Popular codes**

| Language                 | Code    |
| ------------------------ | ------- |
| English (United States)  | `en-US` |
| English (United Kingdom) | `en-GB` |
| Dutch                    | `nl`    |
| French                   | `fr`    |
| German                   | `de`    |
| Hindi                    | `hi`    |
| Italian                  | `it`    |
| Japanese                 | `ja`    |
| Korean                   | `ko`    |
| Portuguese               | `pt`    |
| Russian                  | `ru`    |
| Spanish                  | `es`    |
| Turkish                  | `tr`    |
| Chinese (Simplified)     | `zh`    |
| Chinese (Traditional)    | `zh-TW` |
| Malay                    | `ms`    |
| Swedish                  | `sv`    |
| Lithuanian               | `lt`    |
| Hungarian                | `hu`    |

Need another locale? Use the same pattern with its code (for example `CometChatApp.localize("ko")` for Korean).

***

## Anonymous & guest access

Because the widget is gated by WordPress login, visitors who are **not** signed in to WordPress won't see it — the shortcode only renders for logged-in WordPress users.

* **Member sites:** no extra setup — your existing WordPress login is the gate, and the plugin authenticates each signed-in member automatically.
* **Guest / anonymous chat:** not supported by the WordPress plugin. If you need anonymous chat, use the [HTML/JS embed](/docs/widget/html/overview) with `mode: "guest"` on those pages instead of the plugin shortcode.

***

## Customize the widget with CSS

The Widget Builder includes a **Custom Code** tab where you can add **Custom CSS** (and Custom JS) that ships with your widget. Styling uses the same `--cometchat-*` CSS variables used across CometChat's UI Kits, so you can re-theme colors, typography, and spacing without editing the plugin.

Open it from the dashboard: **Chat & Messaging → Get Started / Integrate → No Code → WordPress → Widget Builder → Custom Code** tab.

Custom CSS added here is automatically scoped under the widget's root, so top-level selectors like `:root` or `body` won't match. Target **`.cometchat-root`** — which carries the `--cometchat-*` variables — instead.

Example — override the primary color and font:

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

Save and re-publish in the Widget Builder, then re-copy the embed code if your Variant ID changed.

***

## Troubleshooting

* **Plugin upload fails**: Ensure the ZIP is intact and WordPress has write permissions.
* **Settings not saving**: Temporarily disable caching/minification plugins.
* **Shortcode not working**: Verify the `[cometchat]` syntax and saved settings.
* **JavaScript errors**: Check browser console for missing `CometChatApp` or invalid parameters.

***

## Need Help?

Questions or issues? Contact [CometChat Support](https://www.cometchat.com/contact).


# CometChat Widget Builder For WordPress
Source: https://www.cometchat.com/docs/widget/wordpress/overview

CometChat Widget Builder for WordPress is a no-code solution for embedding a fully functional chat interface with plugin configuration.

It provides a ready-to-use chat widget backed by CometChat's real-time infrastructure — install the plugin, configure your credentials, and go live.

With CometChat Widget Builder, you can:

* Embed chat and calling into any WordPress website
* Customize themes, colors, and typography
* Toggle features on and off
* Go live with a WordPress plugin and shortcode

The widget connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling.

<Card title="Ready to add chat to your WordPress website?" icon="rocket" href="/widget/wordpress/integration">
  Go to the Integration Guide
</Card>

<Note>
  **Legacy Widget (v3):** If you previously used the legacy CometChat Widget (v3) on WordPress, the legacy widget section in the Dashboard is only visible for apps that had legacy widgets configured before the migration to Widget Builder. New apps will not see the legacy widget section. For migration guidance, see the [Migration Guide](/docs/articles/migration-guide).
</Note>

***

## Widget Builder Features

**No-Code Visual Configuration** — Widget Builder provides a visual configuration environment for designing your chat widget before embedding.

**Toggle-Based Feature Control** — Messaging and calling features can be controlled through configuration settings in the Widget Builder in dashboard.

**Ready-to-Embed Code** — After configuration, Widget Builder generates a code snippet you can use with the WordPress plugin to embed chat.

***

## How to Use Widget Builder

### 1. Design

Customize your chat widget using the visual Widget Builder:

* **Configure layout** — Toggle all the required features in the dashboard.
* **Toggle features** — Turn chat and calling features on and off from the builder interface.
* **Themes** — Select between system, light, and dark themes. Choose custom colors and typography.

<Frame>
  <img />
</Frame>

### 2. Get Embed Code

Once configured, get the embed code snippet for your widget.

1. Click on **Get Embed Code**
2. Note your app credentials (App ID, Region, REST API Key, Variant ID)
3. Copy the code snippet

### 3. Integrate

Install the CometChat plugin on your WordPress site and go live.

1. **Install the plugin** — Download and activate the CometChat WordPress plugin
2. **Configure credentials** — Set your App ID, Region, API Version, and REST API Key in the plugin settings
3. **User Authentication** — CometChat uses a UID (User ID) to identify each user. Authenticate users to enable chat functionality.
4. **Launch** — Use shortcodes or the plugin settings to display the chat widget on your site

<Card title="Follow the full Integration Guide" icon="book" href="/widget/wordpress/integration">
  Step-by-step instructions for embedding the Widget Builder into your WordPress website
</Card>

***

## Customization

The Widget Builder controls theme, colors, and typography with no code. For deeper control, open the Widget Builder's **Custom Code** tab and add your own **Custom CSS** (and Custom JS) using the `--cometchat-*` CSS variables — the same variables used across CometChat's UI Kits. See [Customize the widget with CSS](/docs/widget/wordpress/integration#customize-the-widget-with-css) in the Integration guide.

***

## Try Live Demo

Experience the CometChat Widget Builder in action:

<CardGroup>
  <Card title="Launch Live Demo" icon="play" href="https://preview.cometchat.com/" />
</CardGroup>

<Frame>
  <iframe title="YouTube video" />
</Frame>

***

## Need Help?

<CardGroup>
  <Card title="Developer Community" icon="users" href="https://community.cometchat.com/">
    Connect with other developers and get answers
  </Card>

  <Card title="Support Portal" icon="headset" href="https://help.cometchat.com/hc/en-us/requests/new">
    Contact our support team for assistance
  </Card>
</CardGroup>

***

## Related Resources

<CardGroup>
  <Card title="JavaScript Chat SDK" href="/sdk/javascript/overview">
    Learn more about the CometChat JavaScript SDK
  </Card>

  <Card title="HTML Widget" href="/widget/html/overview">
    Widget Builder for HTML websites
  </Card>

  <Card title="Shopify Widget" href="/widget/shopify/overview">
    Widget Builder for Shopify stores
  </Card>

  <Card title="Wix Widget" href="/widget/wix/overview">
    Widget Builder for Wix websites
  </Card>
</CardGroup>


# Customizing Your UI Kit Builder
Source: https://www.cometchat.com/docs/chat-builder/android/builder-customisations

Customize Android UI Kit Builder components with BuilderSettingsHelper, generated settings, themes, colors, and source edits.

The `CometChatBuilderSettings.kt` file handles basic feature toggles. For deeper customizations, modify component props using `BuilderSettingsHelper` or edit the source code directly.

***

## Understanding the Customization Architecture

The Android UI Kit Builder uses two main files for customization:

| File                          | Purpose                                                  | When to Modify                               |
| ----------------------------- | -------------------------------------------------------- | -------------------------------------------- |
| `CometChatBuilderSettings.kt` | Auto-generated feature flags and configuration constants | Functional changes (enable/disable features) |
| `themes.xml`                  | Theme styles, colors, and typography                     | UI/visual changes (colors, fonts, spacing)   |
| `BuilderSettingsHelper.kt`    | Utility class that applies settings to UI components     | Component-level customizations               |

<Info>
  `CometChatBuilderSettings.kt` is auto-generated by the Builder plugin from your `cometchat-builder-settings.json` file. You can modify the values directly in the Kotlin file, but changes will be overwritten if you rebuild with the plugin.
</Info>

***

## Using BuilderSettingsHelper

The `BuilderSettingsHelper` is a utility class that applies your Builder configuration to CometChat UI components. It reads values from `CometChatBuilderSettings` and configures component properties accordingly.

### How It Works

1. **Import the helper** into your Activity or Fragment
2. **Get a reference** to your CometChat UI component
3. **Call the appropriate method** to apply settings

```kotlin theme={null}
import com.yourpackage.BuilderSettingsHelper

// Apply settings to your components
BuilderSettingsHelper.applySettingsToMessageHeader(messageHeader)
BuilderSettingsHelper.applySettingsToMessageList(messageList)
BuilderSettingsHelper.applySettingsToMessageComposer(messageComposer)
```

***

## Component-Level Customizations

### MessageHeader

The `applySettingsToMessageHeader` method configures call buttons and user status visibility based on your Builder settings.

```kotlin theme={null}
import com.cometchat.chatuikit.messageheader.CometChatMessageHeader
import com.yourpackage.BuilderSettingsHelper

class MessagesActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        val messageHeader: CometChatMessageHeader = binding.messageHeader
        
        // Apply Builder settings
        BuilderSettingsHelper.applySettingsToMessageHeader(messageHeader)
    }
}
```

**Settings Applied:**

| Setting                                          | Property                    | Description                                 |
| ------------------------------------------------ | --------------------------- | ------------------------------------------- |
| `VoiceAndVideoCalling.ONEONONEVOICECALLING`      | `voiceCallButtonVisibility` | Shows/hides voice call button for 1:1 chats |
| `VoiceAndVideoCalling.ONEONONEVIDEOCALLING`      | `videoCallButtonVisibility` | Shows/hides video call button for 1:1 chats |
| `VoiceAndVideoCalling.GROUPVOICECONFERENCE`      | `voiceCallButtonVisibility` | Shows/hides voice call button for groups    |
| `VoiceAndVideoCalling.GROUPVIDEOCONFERENCE`      | `videoCallButtonVisibility` | Shows/hides video call button for groups    |
| `CoreMessagingExperience.USERANDFRIENDSPRESENCE` | `userStatusVisibility`      | Shows/hides online status indicator         |

***

### MessageList

The `applySettingsToMessageList` method configures message options, reactions, AI features, and more.

```kotlin theme={null}
import com.cometchat.chatuikit.messagelist.CometChatMessageList
import com.yourpackage.BuilderSettingsHelper

class MessagesActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        val messageList: CometChatMessageList = binding.messageList
        
        // Apply Builder settings
        BuilderSettingsHelper.applySettingsToMessageList(messageList)
    }
}
```

**Settings Applied:**

| Setting                                                         | Property                                         | Description                             |
| --------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------- |
| `CoreMessagingExperience.THREADCONVERSATIONANDREPLIES`          | `replyInThreadOptionVisibility`                  | Shows/hides reply in thread option      |
| `CoreMessagingExperience.EDITMESSAGE`                           | `editMessageOptionVisibility`                    | Shows/hides edit message option         |
| `CoreMessagingExperience.DELETEMESSAGE`                         | `deleteMessageOptionVisibility`                  | Shows/hides delete message option       |
| `CoreMessagingExperience.MESSAGEDELIVERYANDREADRECEIPTS`        | `receiptsVisibility`                             | Shows/hides read receipts               |
| `CoreMessagingExperience.QUOTEDREPLIES`                         | `isSwipeToReplyEnabled`, `replyOptionVisibility` | Enables swipe-to-reply and reply option |
| `DeeperUserEngagement.REACTIONS`                                | `messageReactionOptionVisibility`                | Shows/hides reaction option             |
| `DeeperUserEngagement.MESSAGETRANSLATION`                       | `translateMessageOptionVisibility`               | Shows/hides translate option            |
| `AiUserCopilot.CONVERSATIONSTARTER`                             | `isEnableConversationStarter`                    | Enables AI conversation starters        |
| `AiUserCopilot.SMARTREPLY`                                      | `isEnableSmartReplies`                           | Enables AI smart replies                |
| `PrivateMessagingWithinGroups.SENDPRIVATEMESSAGETOGROUPMEMBERS` | `messagePrivatelyOptionVisibility`               | Shows/hides message privately option    |

***

### MessageComposer

The `applySettingsToMessageComposer` method configures attachment options, typing indicators, mentions, and more.

```kotlin theme={null}
import com.cometchat.chatuikit.messagecomposer.CometChatMessageComposer
import com.yourpackage.BuilderSettingsHelper

class MessagesActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        val messageComposer: CometChatMessageComposer = binding.messageComposer
        
        // Apply Builder settings
        BuilderSettingsHelper.applySettingsToMessageComposer(messageComposer)
    }
}
```

**Settings Applied:**

| Setting                                        | Property                                                              | Description                        |
| ---------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------- |
| `CoreMessagingExperience.TYPINGINDICATOR`      | `disableTypingEvents()`                                               | Enables/disables typing indicators |
| `CoreMessagingExperience.PHOTOSSHARING`        | `cameraAttachmentOptionVisibility`, `imageAttachmentOptionVisibility` | Shows/hides photo attachments      |
| `CoreMessagingExperience.VIDEOSHARING`         | `videoAttachmentOptionVisibility`                                     | Shows/hides video attachments      |
| `CoreMessagingExperience.AUDIOSHARING`         | `audioAttachmentOptionVisibility`                                     | Shows/hides audio attachments      |
| `CoreMessagingExperience.FILESHARING`          | `fileAttachmentOptionVisibility`                                      | Shows/hides file attachments       |
| `DeeperUserEngagement.MENTIONS`                | `isDisableMentions`                                                   | Enables/disables @mentions         |
| `DeeperUserEngagement.MENTIONALL`              | `setDisableMentionAll()`                                              | Enables/disables @all mentions     |
| `DeeperUserEngagement.POLLS`                   | `pollAttachmentOptionVisibility`                                      | Shows/hides polls option           |
| `DeeperUserEngagement.COLLABORATIVEWHITEBOARD` | `collaborativeWhiteboardOptionVisibility`                             | Shows/hides whiteboard option      |
| `DeeperUserEngagement.COLLABORATIVEDOCUMENT`   | `collaborativeDocumentOptionVisibility`                               | Shows/hides document option        |
| `DeeperUserEngagement.VOICENOTES`              | `voiceNoteButtonVisibility`                                           | Shows/hides voice notes button     |
| `DeeperUserEngagement.STICKERS`                | `stickersButtonVisibility`                                            | Shows/hides stickers button        |

***

### Users

The `applySettingsToUsers` method configures user list display options.

```kotlin theme={null}
import com.cometchat.chatuikit.users.CometChatUsers
import com.yourpackage.BuilderSettingsHelper

class UsersActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        val users: CometChatUsers = binding.users
        
        // Apply Builder settings
        BuilderSettingsHelper.applySettingsToUsers(users)
    }
}
```

**Settings Applied:**

| Setting                                          | Property               | Description                         |
| ------------------------------------------------ | ---------------------- | ----------------------------------- |
| `CoreMessagingExperience.USERANDFRIENDSPRESENCE` | `userStatusVisibility` | Shows/hides online status indicator |

***

### CallLogs

The `applySettingsToCallLogs` method configures call log display and call buttons.

```kotlin theme={null}
import com.cometchat.chatuikit.calls.calllogs.CometChatCallLogs
import com.yourpackage.BuilderSettingsHelper

class CallsActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        val callLogs: CometChatCallLogs = binding.callLogs
        
        // Apply Builder settings
        BuilderSettingsHelper.applySettingsToCallLogs(callLogs)
    }
}
```

**Settings Applied:**

| Setting                                     | Property               | Description                 |
| ------------------------------------------- | ---------------------- | --------------------------- |
| `VoiceAndVideoCalling.ONEONONEVIDEOCALLING` | `itemVideoCallIcon`    | Shows/hides video call icon |
| `VoiceAndVideoCalling.ONEONONEVOICECALLING` | `itemIncomingCallIcon` | Shows/hides voice call icon |

***

### GroupMembers

The `applySettingToGroupMembers` method configures moderator controls and member display options.

```kotlin theme={null}
import com.cometchat.chatuikit.groupmembers.CometChatGroupMembers
import com.yourpackage.BuilderSettingsHelper

class GroupMembersActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        val groupMembers: CometChatGroupMembers = binding.groupMembers
        
        // Apply Builder settings
        BuilderSettingsHelper.applySettingToGroupMembers(groupMembers)
    }
}
```

**Settings Applied:**

| Setting                                          | Property                      | Description                         |
| ------------------------------------------------ | ----------------------------- | ----------------------------------- |
| `ModeratorControls.KICKUSERS`                    | `kickMemberOptionVisibility`  | Shows/hides kick member option      |
| `ModeratorControls.BANUSERS`                     | `banMemberOptionVisibility`   | Shows/hides ban member option       |
| `ModeratorControls.PROMOTEDEMOTEMEMBERS`         | `scopeChangeOptionVisibility` | Shows/hides promote/demote option   |
| `CoreMessagingExperience.USERANDFRIENDSPRESENCE` | `userStatusVisibility`        | Shows/hides online status indicator |

***

## Functional Changes via CometChatBuilderSettings

For functional changes (enabling/disabling features), you can directly access the `CometChatBuilderSettings` object:

```kotlin theme={null}
import com.cometchat.builder.CometChatBuilderSettings

// Check if a feature is enabled
if (CometChatBuilderSettings.ChatFeatures.CoreMessagingExperience.PHOTOSSHARING) {
    // Photo sharing is enabled
}

// Check AI features
if (CometChatBuilderSettings.ChatFeatures.AiUserCopilot.SMARTREPLY) {
    // Smart reply is enabled
}

// Check call features
if (CometChatBuilderSettings.CallFeatures.VoiceAndVideoCalling.ONEONONEVIDEOCALLING) {
    // 1:1 video calling is enabled
}

// Access layout settings
val tabs = CometChatBuilderSettings.Layout.TABS // List of enabled tabs
val chatType = CometChatBuilderSettings.Layout.CHATTYPE // "user" or "group"

// Access style settings
val brandColor = CometChatBuilderSettings.Style.Color.BRANDCOLOR
val theme = CometChatBuilderSettings.Style.THEME // "light", "dark", or "system"
```

### Modifying Feature Flags at Runtime

You can modify feature flags at runtime by directly setting the values:

```kotlin theme={null}
// Disable photo sharing at runtime
CometChatBuilderSettings.ChatFeatures.CoreMessagingExperience.PHOTOSSHARING = false

// Enable AI smart replies
CometChatBuilderSettings.ChatFeatures.AiUserCopilot.SMARTREPLY = true

// Then re-apply settings to your components
BuilderSettingsHelper.applySettingsToMessageComposer(messageComposer)
BuilderSettingsHelper.applySettingsToMessageList(messageList)
```

<Note>
  Runtime changes to `CometChatBuilderSettings` are not persisted. They will reset to the original values when the app restarts.
</Note>

***

## UI/Theme Changes via themes.xml

For visual customizations (colors, fonts, spacing), modify the `themes.xml` file in your `res/values` directory.

### Customizing Colors

```xml themes.xml theme={null}
<style name="CometChat.Builder.Theme" parent="CometChatTheme.DayNight">
    <!-- Brand color (primary accent) -->
    <item name="cometchatPrimaryColor">#6852D6</item>
    
    <!-- Text colors -->
    <item name="cometchatTextColorPrimary">#141414</item>
    <item name="cometchatTextColorSecondary">#727272</item>
    
    <!-- Background colors -->
    <item name="cometchatBackgroundColor1">#FFFFFF</item>
    <item name="cometchatBackgroundColor2">#F5F5F5</item>
</style>
```

### Customizing Typography

```xml themes.xml theme={null}
<style name="CometChat.Builder.Theme" parent="CometChatTheme.DayNight">
    <!-- Custom fonts -->
    <item name="cometchatFontBold">@font/your_font_bold</item>
    <item name="cometchatFontRegular">@font/your_font_regular</item>
    <item name="cometchatFontMedium">@font/your_font_medium</item>
</style>
```

### Pre-built Font Themes

The Builder includes pre-built font themes you can use:

```xml themes.xml theme={null}
<!-- Use Roboto (default) -->
<style name="YourAppTheme" parent="Builder.Theme.Roboto" />

<!-- Use Arial -->
<style name="YourAppTheme" parent="Builder.Theme.Arial" />

<!-- Use Inter -->
<style name="YourAppTheme" parent="Builder.Theme.Inter" />

<!-- Use Times New Roman -->
<style name="YourAppTheme" parent="Builder.Theme.TimesNewRoman" />
```

### Customizing Component Styles

You can customize individual component styles by overriding their style attributes:

```xml themes.xml theme={null}
<!-- Custom Message List Style -->
<style name="CustomCometChatMessageListStyle" parent="CometChatMessageListStyle">
    <item name="cometchatMessageListOutgoingMessageBubbleStyle">
        @style/CustomOutgoingMessageBubbleStyle
    </item>
</style>

<!-- Custom Outgoing Message Bubble -->
<style name="CustomOutgoingMessageBubbleStyle">
    <item name="cometchatMessageBubbleBackgroundColor">?attr/cometchatBackgroundColor4</item>
    <item name="cometchatMessageBubbleCornerRadius">@dimen/cometchat_radius_3</item>
</style>

<!-- Custom Message Composer Style -->
<style name="CustomMessageComposerStyle">
    <item name="cometchatMessageComposerComposeBoxStrokeWidth">@dimen/cometchat_1dp</item>
    <item name="cometchatMessageComposerComposeBoxCornerRadius">@dimen/cometchat_radius_2</item>
</style>
```

***

## Next Steps

<CardGroup>
  <Card title="UI Kit Builder Settings" href="/chat-builder/android/builder-settings">
    Understand all available feature toggles and configuration options.
  </Card>

  <Card title="Components Overview" href="/ui-kit/android/components-overview">
    Explore all available UI components and their customization options.
  </Card>

  <Card title="Theming" href="/ui-kit/android/theme-introduction">
    Deep dive into colors, typography, and advanced styling.
  </Card>

  <Card title="Directory Structure" href="/chat-builder/android/builder-dir-structure">
    Understand how the exported code is organized.
  </Card>
</CardGroup>


# Directory Structure
Source: https://www.cometchat.com/docs/chat-builder/android/builder-dir-structure

Overview of the CometChat UI Kit Builder directory layout for Android — understand where to find and customize components, settings, and styles.

The exported UI Kit Builder code lives in `chat-builder/src/main/java/com/cometchat/builder/`. This guide helps you navigate the structure so you know exactly where to make changes.

<Tree>
  <Folder name="chat-builder">
    <Folder name="src/main">
      <Folder name="java/com/cometchat/builder">
        <Folder name="data" description="Data models, enums, interfaces, repositories" />

        <Folder name="ui" description="UI components (activities, fragments, adapters)" />

        <Folder name="utils" description="Utility functions and helpers" />

        <Folder name="viewmodels" description="ViewModels for UI components" />

        <File name="AppCredentials.kt" />

        <File name="BuilderSettingsHelper.kt" />

        <File name="CometChatBuilderSettings.kt" />
      </Folder>

      <Folder name="res">
        <Folder name="drawable" description="Icons, shapes, and drawable resources" />

        <Folder name="font" description="Font files (TTF, OTF)" />

        <Folder name="layout" description="XML layout files" />

        <Folder name="menu" description="Menu resource files" />

        <Folder name="values" description="Strings, colors, themes" />

        <Folder name="values-<locale>" description="Localized string resources" />
      </Folder>
    </Folder>

    <File name="build.gradle.kts" />

    <File name="cometchat-builder-settings.json" />
  </Folder>
</Tree>

***

## Root Files

| File                          | Purpose                                                                |
| ----------------------------- | ---------------------------------------------------------------------- |
| `CometChatBuilderSettings.kt` | Auto-generated feature flags and configuration constants from Builder  |
| `BuilderSettingsHelper.kt`    | Utility class for applying Builder settings to CometChat UI components |
| `AppCredentials.kt`           | CometChat app credentials (APP\_ID, AUTH\_KEY, REGION)                 |

***

## Key Folders

### `data/`

Contains data layer components including enums, interfaces, and repositories.

<Tree>
  <Folder name="data">
    <Folder name="enums" description="Enum classes (e.g., GroupAction)" />

    <Folder name="interfaces" description="Callback interfaces (OnBackPress, OnItemClickListener)" />

    <Folder name="repository" description="Data repository classes" />
  </Folder>
</Tree>

### `ui/`

Contains all UI-related components organized by type.

<Tree>
  <Folder name="ui">
    <Folder name="activity" description="Activity classes (HomeActivity, MessagesActivity, LoginActivity)" />

    <Folder name="adapters" description="RecyclerView adapters (BannedMembersAdapter, SampleUsersAdapter)" />

    <Folder name="customviews" description="Custom view components (CometChatBannedMembers)" />

    <Folder name="fragments" description="Fragment classes (ChatsFragment, CallsFragment, UsersFragment)" />
  </Folder>
</Tree>

### `utils/`

Utility functions and application-level helpers.

<Tree>
  <Folder name="utils">
    <File name="AppConstants.kt" description="Application constants" />

    <File name="AppUtils.kt" description="General utility functions" />

    <File name="BuilderApplication.kt" description="Application class" />
  </Folder>
</Tree>

### `viewmodels/`

ViewModels for managing UI state and business logic.

<Tree>
  <Folder name="viewmodels">
    <File name="AppCredentialsViewModel.kt" />

    <File name="CallDetailsViewModel.kt" />

    <File name="GroupDetailsViewModel.kt" />

    <File name="LoginViewModel.kt" />

    <File name="MessagesViewModel.kt" />
  </Folder>
</Tree>

***

## res/ Folder Structure

### `layout/`

XML layout files for activities, fragments, and custom views.

<Tree>
  <Folder name="layout">
    <File name="builder_activity_home.xml" description="Main home screen layout" />

    <File name="builder_activity_messages.xml" description="Messages screen layout" />

    <File name="builder_activity_login.xml" description="Login screen layout" />

    <File name="builder_fragment_chats.xml" description="Chats tab fragment" />

    <File name="builder_fragment_calls.xml" description="Calls tab fragment" />

    <File name="builder_fragment_users.xml" description="Users tab fragment" />

    <File name="builder_fragment_groups.xml" description="Groups tab fragment" />
  </Folder>
</Tree>

### `values/`

Resource values including strings, colors, and themes.

<Tree>
  <Folder name="values">
    <File name="colors.xml" description="Color definitions" />

    <File name="strings.xml" description="String resources" />

    <File name="themes.xml" description="Theme definitions and styles" />
  </Folder>
</Tree>

### `font/`

Font resources for typography customization.

<Tree>
  <Folder name="font">
    <File name="inter_regular.otf" />

    <File name="inter_medium.otf" />

    <File name="inter_bold.otf" />

    <File name="roboto_regular.ttf" />

    <File name="roboto_medium.ttf" />

    <File name="roboto_bold.ttf" />
  </Folder>
</Tree>

### `drawable/`

Drawable resources including icons, shapes, and backgrounds.

<Tree>
  <Folder name="drawable">
    <File name="builder_ic_chats.xml" description="Chat icon" />

    <File name="builder_ic_calls.xml" description="Calls icon" />

    <File name="builder_ic_users.xml" description="Users icon" />

    <File name="builder_ic_bottom_bar_groups.xml" description="Groups icon" />

    <File name="builder_curved_button_drawable.xml" />
  </Folder>
</Tree>

***

## Quick Reference: Where to Customize

| What you want to change      | Where to look                                    |
| ---------------------------- | ------------------------------------------------ |
| Enable/disable features      | `CometChatBuilderSettings.kt`                    |
| Apply settings to components | `BuilderSettingsHelper.kt`                       |
| Theme colors & styles        | `res/values/themes.xml`, `res/values/colors.xml` |
| Typography & fonts           | `res/font/`                                      |
| Screen layouts               | `res/layout/`                                    |
| Text & translations          | `res/values/strings.xml`, `res/values-<locale>/` |
| Activity behavior            | `ui/activity/`                                   |
| Fragment behavior            | `ui/fragments/`                                  |
| App credentials              | `AppCredentials.kt`                              |

<Note>
  Prefer using `CometChatBuilderSettings.kt` for feature toggles and `themes.xml` for styling. For extensive changes, extend existing components instead of modifying core files directly.
</Note>

***

## Next Steps

<CardGroup>
  <Card title="UI Kit Builder Settings" href="/chat-builder/android/builder-settings">
    Configure feature toggles and behavior
  </Card>

  <Card title="Customizations" href="/chat-builder/android/builder-customisations">
    Modify component props, styling, and behavior
  </Card>

  <Card title="Theming" href="/ui-kit/android/theme-introduction">
    Customize colors, typography, and styling
  </Card>

  <Card title="Localization" href="/ui-kit/android/localize">
    Add multi-language support
  </Card>
</CardGroup>


# Customizing Your UI Kit Builder
Source: https://www.cometchat.com/docs/chat-builder/flutter/builder-customisations

Customize Flutter UI Kit Builder components with configuration JSON, BuilderSettingsHelper, themes, feature toggles, and props.

The `BuilderSettingsHelper` handles basic feature toggles. For deeper customizations, modify the configuration JSON, theme settings, or component props directly.

***

## Understanding the Customization Architecture

The Flutter UI Kit Builder uses these main files for customization:

| File                              | Purpose                                          | When to Modify                               |
| --------------------------------- | ------------------------------------------------ | -------------------------------------------- |
| `cometchat-builder-settings.json` | Feature flags and configuration constants        | Functional changes (enable/disable features) |
| `BuilderSettingsHelper`           | Utility class for loading and accessing settings | Runtime configuration access                 |
| `pubspec.yaml`                    | Font and asset declarations                      | Adding custom fonts or assets                |

<Info>
  The `cometchat-builder-settings.json` file is the source of truth for your Builder configuration. Update it and reload to apply changes.
</Info>

***

## Using BuilderSettingsHelper

The `BuilderSettingsHelper` provides access to your Builder configuration throughout your app.

### Loading Configuration

```dart theme={null}
import 'package:chat_builder/utils/builder_settings_helper.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Load settings from assets
  await BuilderSettingsHelper.loadFromAsset();
  
  runApp(const MyApp());
}
```

### Accessing Settings

```dart theme={null}
import 'package:chat_builder/utils/builder_settings_helper.dart';

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final settings = BuilderSettingsHelper.settings;
    
    // Access chat features
    final chatFeatures = settings.chatFeatures;
    final isPhotosEnabled = chatFeatures.coreMessagingExperience.photosSharing;
    
    // Access style settings
    final style = settings.style;
    final brandColor = style.color.brandColor;
    
    // Access layout settings
    final layout = settings.layout;
    final tabs = layout.tabs;
    
    return Container(/* ... */);
  }
}
```

***

## Theme Customization

### Applying Builder Theme to UI Kit

Apply the Builder configuration colors to your Flutter theme:

```dart theme={null}
import 'package:flutter/material.dart';
import 'package:chat_builder/utils/builder_settings_helper.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final style = BuilderSettingsHelper.settings.style;
    
    return MaterialApp(
      theme: ThemeData(
        primaryColor: Color(int.parse(style.color.brandColor.replaceFirst('#', '0xFF'))),
        colorScheme: ColorScheme.light(
          primary: Color(int.parse(style.color.brandColor.replaceFirst('#', '0xFF'))),
        ),
        textTheme: TextTheme(
          bodyLarge: TextStyle(
            color: Color(int.parse(style.color.primaryTextLight.replaceFirst('#', '0xFF'))),
          ),
          bodyMedium: TextStyle(
            color: Color(int.parse(style.color.secondaryTextLight.replaceFirst('#', '0xFF'))),
          ),
        ),
        fontFamily: style.typography.font,
      ),
      darkTheme: ThemeData.dark().copyWith(
        primaryColor: Color(int.parse(style.color.brandColor.replaceFirst('#', '0xFF'))),
        colorScheme: ColorScheme.dark(
          primary: Color(int.parse(style.color.brandColor.replaceFirst('#', '0xFF'))),
        ),
        textTheme: TextTheme(
          bodyLarge: TextStyle(
            color: Color(int.parse(style.color.primaryTextDark.replaceFirst('#', '0xFF'))),
          ),
          bodyMedium: TextStyle(
            color: Color(int.parse(style.color.secondaryTextDark.replaceFirst('#', '0xFF'))),
          ),
        ),
        fontFamily: style.typography.font,
      ),
      themeMode: _getThemeMode(style.theme),
      home: HomeScreen(),
    );
  }
  
  ThemeMode _getThemeMode(String theme) {
    switch (theme) {
      case 'light':
        return ThemeMode.light;
      case 'dark':
        return ThemeMode.dark;
      default:
        return ThemeMode.system;
    }
  }
}
```

### Custom Color Utilities

Create a utility class for working with Builder colors:

```dart theme={null}
import 'package:flutter/material.dart';
import 'package:chat_builder/utils/builder_settings_helper.dart';

class BuilderColors {
  static Color get brandColor {
    final hex = BuilderSettingsHelper.settings.style.color.brandColor;
    return _hexToColor(hex);
  }
  
  static Color get primaryTextLight {
    final hex = BuilderSettingsHelper.settings.style.color.primaryTextLight;
    return _hexToColor(hex);
  }
  
  static Color get primaryTextDark {
    final hex = BuilderSettingsHelper.settings.style.color.primaryTextDark;
    return _hexToColor(hex);
  }
  
  static Color get secondaryTextLight {
    final hex = BuilderSettingsHelper.settings.style.color.secondaryTextLight;
    return _hexToColor(hex);
  }
  
  static Color get secondaryTextDark {
    final hex = BuilderSettingsHelper.settings.style.color.secondaryTextDark;
    return _hexToColor(hex);
  }
  
  static Color _hexToColor(String hex) {
    return Color(int.parse(hex.replaceFirst('#', '0xFF')));
  }
}
```

***

## Custom Font Integration

### Step 1: Add Font Files

Add your custom font files to the `assets/fonts/` directory.

### Step 2: Update pubspec.yaml

Register your custom fonts:

```yaml theme={null}
flutter:
  fonts:
    - family: YourCustomFont
      fonts:
        - asset: assets/fonts/your_font_regular.ttf
        - asset: assets/fonts/your_font_medium.ttf
          weight: 500
        - asset: assets/fonts/your_font_bold.ttf
          weight: 700
```

### Step 3: Apply Custom Font

Update the configuration JSON or apply programmatically:

```dart theme={null}
// In your theme configuration
ThemeData(
  fontFamily: 'YourCustomFont',
  // ... other theme settings
)
```

***

## Component-Level Customizations

### Conditional Rendering Based on Features

Use the configuration to conditionally render UI elements:

```dart theme={null}
import 'package:chat_builder/utils/builder_settings_helper.dart';

class MessageComposer extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final chatFeatures = BuilderSettingsHelper.settings.chatFeatures;
    final core = chatFeatures.coreMessagingExperience;
    final engagement = chatFeatures.deeperUserEngagement;
    
    return Row(
      children: [
        // Always show text input
        Expanded(child: TextField()),
        
        // Conditionally show attachment options
        if (core.photosSharing)
          IconButton(
            icon: Icon(Icons.photo),
            onPressed: () => _attachPhoto(),
          ),
        
        if (core.fileSharing)
          IconButton(
            icon: Icon(Icons.attach_file),
            onPressed: () => _attachFile(),
          ),
        
        if (engagement.voiceNotes)
          IconButton(
            icon: Icon(Icons.mic),
            onPressed: () => _recordVoiceNote(),
          ),
        
        if (engagement.stickers)
          IconButton(
            icon: Icon(Icons.emoji_emotions),
            onPressed: () => _showStickers(),
          ),
      ],
    );
  }
}
```

### Customizing Message Options

Control which message options appear based on configuration:

```dart theme={null}
class MessageOptionsSheet extends StatelessWidget {
  final Message message;
  
  const MessageOptionsSheet({required this.message});
  
  @override
  Widget build(BuildContext context) {
    final chatFeatures = BuilderSettingsHelper.settings.chatFeatures;
    final core = chatFeatures.coreMessagingExperience;
    final engagement = chatFeatures.deeperUserEngagement;
    final moderator = chatFeatures.moderatorControls;
    
    return Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        if (core.quotedReplies)
          ListTile(
            leading: Icon(Icons.reply),
            title: Text('Reply'),
            onTap: () => _handleReply(),
          ),
        
        if (core.threadConversationAndReplies)
          ListTile(
            leading: Icon(Icons.forum),
            title: Text('Reply in Thread'),
            onTap: () => _handleThreadReply(),
          ),
        
        if (engagement.reactions)
          ListTile(
            leading: Icon(Icons.add_reaction),
            title: Text('React'),
            onTap: () => _handleReaction(),
          ),
        
        if (core.editMessage && _isOwnMessage())
          ListTile(
            leading: Icon(Icons.edit),
            title: Text('Edit'),
            onTap: () => _handleEdit(),
          ),
        
        if (core.deleteMessage && _isOwnMessage())
          ListTile(
            leading: Icon(Icons.delete),
            title: Text('Delete'),
            onTap: () => _handleDelete(),
          ),
        
        if (moderator.reportMessage)
          ListTile(
            leading: Icon(Icons.flag),
            title: Text('Report'),
            onTap: () => _handleReport(),
          ),
      ],
    );
  }
}
```

***

## Layout Customization

### Dynamic Tab Configuration

```dart theme={null}
import 'package:chat_builder/utils/builder_settings_helper.dart';

class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final layout = BuilderSettingsHelper.settings.layout;
    
    if (!layout.withSideBar) {
      return SingleChatView();
    }
    
    final tabs = layout.tabs;
    
    return DefaultTabController(
      length: tabs.length,
      child: Scaffold(
        appBar: AppBar(
          bottom: TabBar(
            tabs: [
              if (tabs.contains('chats'))
                Tab(icon: Icon(Icons.chat), text: 'Chats'),
              if (tabs.contains('calls'))
                Tab(icon: Icon(Icons.call), text: 'Calls'),
              if (tabs.contains('users'))
                Tab(icon: Icon(Icons.people), text: 'Users'),
              if (tabs.contains('groups'))
                Tab(icon: Icon(Icons.group), text: 'Groups'),
            ],
          ),
        ),
        body: TabBarView(
          children: [
            if (tabs.contains('chats')) ChatsScreen(),
            if (tabs.contains('calls')) CallsScreen(),
            if (tabs.contains('users')) UsersScreen(),
            if (tabs.contains('groups')) GroupsScreen(),
          ],
        ),
      ),
    );
  }
}
```

***

## Call Features Customization

### Conditional Call Buttons

```dart theme={null}
class ChatHeader extends StatelessWidget {
  final bool isGroup;
  
  const ChatHeader({required this.isGroup});
  
  @override
  Widget build(BuildContext context) {
    final callFeatures = BuilderSettingsHelper.settings.callFeatures;
    final calling = callFeatures.voiceAndVideoCalling;
    
    return AppBar(
      actions: [
        if (isGroup) ...[
          if (calling.groupVoiceConference)
            IconButton(
              icon: Icon(Icons.call),
              onPressed: () => _startGroupVoiceCall(),
            ),
          if (calling.groupVideoConference)
            IconButton(
              icon: Icon(Icons.videocam),
              onPressed: () => _startGroupVideoCall(),
            ),
        ] else ...[
          if (calling.oneOnOneVoiceCalling)
            IconButton(
              icon: Icon(Icons.call),
              onPressed: () => _startVoiceCall(),
            ),
          if (calling.oneOnOneVideoCalling)
            IconButton(
              icon: Icon(Icons.videocam),
              onPressed: () => _startVideoCall(),
            ),
        ],
      ],
    );
  }
}
```

***

## Reloading Configuration

### Refresh Settings at Runtime

```dart theme={null}
import 'package:chat_builder/utils/builder_settings_helper.dart';

class SettingsScreen extends StatelessWidget {
  Future<void> _reloadConfiguration() async {
    // Reload from assets
    await BuilderSettingsHelper.loadFromAsset();
    
    // Trigger UI rebuild
    // Use a state management solution to notify listeners
  }
  
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: _reloadConfiguration,
      child: Text('Reload Configuration'),
    );
  }
}
```


# Directory Structure
Source: https://www.cometchat.com/docs/chat-builder/flutter/builder-dir-structure

Overview of the CometChat UI Kit Builder directory layout for Flutter — understand where to find and customize components, settings, and styles.

The UI Kit Builder for Flutter organizes code into a modular structure with the `chat_builder` package containing all Builder-specific code. This guide helps you navigate the structure so you know exactly where to make changes.

```
your_app/
├── lib/                           # Your app's Dart code
├── assets/
│   ├── fonts/                     # Font files (TTF, OTF)
│   ├── sample_app/                # Sample app assets
│   └── cometchat-builder-settings.json  # Builder configuration
├── chat_builder/
│   ├── lib/
│   │   ├── screens/               # UI screens
│   │   ├── utils/                 # Utilities and helpers
│   │   ├── widgets/               # Reusable widgets
│   │   └── chat_builder.dart      # Main entry point
│   └── pubspec.yaml               # Builder dependencies
├── ios/                           # iOS native code
├── android/                       # Android native code
└── pubspec.yaml                   # App dependencies
```

***

## Root Files

| File            | Purpose                                             |
| --------------- | --------------------------------------------------- |
| `pubspec.yaml`  | Project dependencies, assets, and font declarations |
| `lib/main.dart` | Main application entry point                        |

***

## Key Folders

### `chat_builder/`

The Builder module containing all UI Kit Builder functionality.

```
chat_builder/
├── lib/
│   ├── screens/           # UI screens (home, messages, login)
│   ├── utils/             # Utilities including BuilderSettingsHelper
│   ├── widgets/           # Reusable UI widgets
│   └── chat_builder.dart  # Main entry point with ChatBuilder class
└── pubspec.yaml           # Module dependencies
```

### `chat_builder/lib/utils/`

Utility classes and helpers.

```
utils/
├── builder_settings_helper.dart   # Loads and provides access to Builder settings
├── app_constants.dart             # CometChat credentials and constants
└── theme_helper.dart              # Theme utilities
```

| File                           | Purpose                                                       |
| ------------------------------ | ------------------------------------------------------------- |
| `builder_settings_helper.dart` | Loads configuration from JSON and provides access to settings |
| `app_constants.dart`           | CometChat APP\_ID, AUTH\_KEY, REGION                          |
| `theme_helper.dart`            | Helper functions for applying Builder theme                   |

### `chat_builder/lib/screens/`

UI screens for different features.

```
screens/
├── home/       # Home screen with tab navigation
├── messages/   # Chat and messaging screens
├── calls/      # Call logs and call screens
├── users/      # User list and profiles
├── groups/     # Group list and management
└── login/      # Authentication screens
```

### `chat_builder/lib/widgets/`

Reusable UI widgets.

```
widgets/
├── message_composer.dart      # Message input widget
├── message_list.dart          # Message list widget
├── user_avatar.dart           # User avatar widget
└── presence_indicator.dart    # Online status indicator
```

***

## Assets Directory

Static assets including configuration, fonts, and images.

```
assets/
├── fonts/
│   ├── arial_regular.ttf
│   ├── arial_medium.ttf
│   ├── arial_bold.ttf
│   ├── inter_regular.otf
│   ├── inter_medium.otf
│   ├── inter_bold.otf
│   ├── roboto_regular.ttf
│   ├── roboto_medium.ttf
│   ├── roboto_bold.ttf
│   ├── times_new_roman_regular.ttf
│   ├── times_new_roman_medium.otf
│   └── times_new_roman_bold.otf
├── sample_app/                        # Sample app specific assets
└── cometchat-builder-settings.json    # Builder configuration file
```

***

## Platform Directories

### `ios/`

iOS-specific native code and configuration.

```
ios/
├── Runner/
│   ├── AppDelegate.swift    # iOS app delegate
│   └── Info.plist           # iOS app configuration
└── Podfile                  # CocoaPods dependencies
```

### `android/`

Android-specific native code and configuration.

```
android/
├── app/
│   ├── src/main/
│   │   ├── AndroidManifest.xml   # Android app manifest
│   │   ├── kotlin/               # Native Android code
│   │   └── res/                  # Android resources
│   └── build.gradle.kts          # App-level Gradle config
├── build.gradle.kts              # Project-level Gradle config
└── settings.gradle.kts           # Gradle settings
```

***

## Quick Reference: Where to Customize

| What you want to change         | Where to look                                         |
| ------------------------------- | ----------------------------------------------------- |
| Enable/disable features         | `assets/cometchat-builder-settings.json`              |
| Access configuration at runtime | `chat_builder/lib/utils/builder_settings_helper.dart` |
| CometChat credentials           | `chat_builder/lib/utils/app_constants.dart`           |
| Theme colors & styles           | `lib/main.dart` (MaterialApp theme)                   |
| Custom fonts                    | `assets/fonts/`, `pubspec.yaml`                       |
| Chat UI screens                 | `chat_builder/lib/screens/messages/`                  |
| Call UI screens                 | `chat_builder/lib/screens/calls/`                     |
| User management UI              | `chat_builder/lib/screens/users/`                     |
| Group management UI             | `chat_builder/lib/screens/groups/`                    |
| Reusable widgets                | `chat_builder/lib/widgets/`                           |

<Note>
  Prefer using `cometchat-builder-settings.json` for feature toggles and the MaterialApp theme for styling. For extensive changes, create new widgets rather than modifying core files directly.
</Note>

***

## pubspec.yaml Configuration

Ensure your `pubspec.yaml` includes the Builder module and assets:

```yaml theme={null}
dependencies:
  flutter:
    sdk: flutter
  chat_builder:
    path: ./chat_builder

flutter:
  uses-material-design: true
  assets:
    - assets/
    - assets/sample_app/
  fonts:
    - family: arial
      fonts:
        - asset: assets/fonts/arial_regular.ttf
        - asset: assets/fonts/arial_medium.ttf
        - asset: assets/fonts/arial_bold.ttf
    - family: inter
      fonts:
        - asset: assets/fonts/inter_regular.otf
        - asset: assets/fonts/inter_medium.otf
        - asset: assets/fonts/inter_bold.otf
    - family: roboto
      fonts:
        - asset: assets/fonts/roboto_regular.ttf
        - asset: assets/fonts/roboto_medium.ttf
        - asset: assets/fonts/roboto_bold.ttf
    - family: times New Roman
      fonts:
        - asset: assets/fonts/times_new_roman_regular.ttf
        - asset: assets/fonts/times_new_roman_medium.otf
        - asset: assets/fonts/times_new_roman_bold.otf
```

***

## Next Steps

<CardGroup>
  <Card title="UI Kit Builder Settings" href="/chat-builder/flutter/builder-settings">
    Configure feature toggles and behavior.
  </Card>

  <Card title="Customizations" href="/chat-builder/flutter/builder-customisations">
    Modify component props, styling, and behavior.
  </Card>

  <Card title="Theming" href="/ui-kit/flutter/theme-introduction">
    Customize colors, typography, and styling.
  </Card>

  <Card title="Components" href="/ui-kit/flutter/components-overview">
    Explore available UI components.
  </Card>
</CardGroup>


# UI Kit Builder Settings
Source: https://www.cometchat.com/docs/chat-builder/flutter/builder-settings

Configure Flutter UI Kit Builder settings for messaging, AI helpers, calling, layout, theming, and JSON feature toggles.

The Builder configuration controls everything the Flutter UI Kit Builder renders—messaging, AI helpers, calls, layout, theming, and more. This configuration is loaded from the `cometchat-builder-settings.json` file via `BuilderSettingsHelper`.

<Info>
  **For developers customizing their chat UI**: The configuration JSON file contains all your feature toggles, layout settings, and styling configuration. Edit this file to enable/disable features like messaging, calls, AI copilot, and theming. See the [Integration Guide](/docs/chat-builder/flutter/integration) for setup.
</Info>

## Top-level Structure

The configuration JSON follows this structure:

```json theme={null}
{
  "builderId": "unique-builder-id",
  "settings": {
    "chatFeatures": {
      "coreMessagingExperience": { /* Boolean settings */ },
      "deeperUserEngagement": { /* Boolean settings */ },
      "aiUserCopilot": { /* Boolean settings */ },
      "userManagement": { /* Boolean settings */ },
      "groupManagement": { /* Boolean settings */ },
      "moderatorControls": { /* Boolean settings */ },
      "privateMessagingWithinGroups": { /* Boolean settings */ },
      "inAppSounds": { /* Boolean settings */ }
    },
    "callFeatures": {
      "voiceAndVideoCalling": { /* Boolean settings */ }
    },
    "layout": { /* Layout settings */ },
    "style": {
      "theme": "system",
      "color": { /* Color settings */ },
      "typography": { /* Typography settings */ }
    }
  }
}
```

***

<Tip>
  All boolean settings follow the same pattern: `true` enables the feature and shows its UI elements, `false` hides them completely.
</Tip>

## 1. Chat Features (`chatFeatures`)

### 1.1 Core Messaging Experience (`coreMessagingExperience`)

Essential messaging features: typing indicators, media sharing, message actions, and presence.

| Setting                          | Type    | What It Does                                                                        |
| -------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `typingIndicator`                | boolean | Shows "typing..." indicator when someone is composing a message                     |
| `threadConversationAndReplies`   | boolean | Enables threaded replies to specific messages, creating nested conversation threads |
| `photosSharing`                  | boolean | Allows users to share images from device or camera                                  |
| `videoSharing`                   | boolean | Allows users to share video files                                                   |
| `audioSharing`                   | boolean | Allows users to share audio files (mp3, wav, etc.)                                  |
| `fileSharing`                    | boolean | Allows users to share documents (PDF, DOC, etc.)                                    |
| `editMessage`                    | boolean | Lets users modify their sent messages; edited messages show "(edited)" label        |
| `deleteMessage`                  | boolean | Lets users remove their sent messages                                               |
| `messageDeliveryAndReadReceipts` | boolean | Shows delivery (✓) and read (✓✓) status indicators on messages                      |
| `userAndFriendsPresence`         | boolean | Shows online/offline status dot next to user avatars                                |
| `conversationAndAdvancedSearch`  | boolean | Enables search across messages, users, and conversations                            |
| `moderation`                     | boolean | Enables blocked message feedback for messages blocked by moderation rules           |
| `quotedReplies`                  | boolean | Lets users quote a message when replying, showing the original above their response |
| `markAsUnread`                   | boolean | Lets users mark a conversation as unread to revisit later                           |

<Tip>
  Empower users with a seamless chat experience—reply to specific messages with
  quoted replies, mark conversations as unread for later, and search across all
  chats instantly. Learn more about [Core Features](/docs/ui-kit/flutter/core-features).
</Tip>

### 1.2 Deeper User Engagement (`deeperUserEngagement`)

Interactive features: mentions, reactions, polls, voice notes, and collaborative tools.

| Setting                   | Type    | What It Does                                                                                |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `mentions`                | boolean | Lets users @mention specific people in a message to notify them                             |
| `mentionAll`              | boolean | Lets users type @all to notify every member in a group chat                                 |
| `reactions`               | boolean | Lets users add emoji reactions (👍 ❤️ 😂 etc.) to messages                                  |
| `messageTranslation`      | boolean | Translates messages to user's preferred language. Requires Dashboard setup                  |
| `polls`                   | boolean | Lets users create polls with multiple options for group voting. Requires Dashboard setup    |
| `collaborativeWhiteboard` | boolean | Opens a shared whiteboard for real-time drawing and collaboration. Requires Dashboard setup |
| `collaborativeDocument`   | boolean | Creates shared documents for real-time collaborative editing. Requires Dashboard setup      |
| `voiceNotes`              | boolean | Lets users record and send voice messages                                                   |
| `emojis`                  | boolean | Shows emoji picker in composer for browsing and inserting emojis                            |
| `stickers`                | boolean | Lets users send sticker images from available packs. Requires Dashboard setup               |
| `userInfo`                | boolean | Lets users tap on another user's avatar to view their profile                               |
| `groupInfo`               | boolean | Lets users tap on group header to view group details and member list                        |

<Tip>
  Configure these features based on your app's requirements. Learn more about
  [Extensions](/docs/ui-kit/flutter/extensions).
</Tip>

### 1.3 AI User Copilot (`aiUserCopilot`)

AI-powered features to help users start and navigate conversations.

| Setting               | Type    | What It Does                              |
| --------------------- | ------- | ----------------------------------------- |
| `conversationStarter` | boolean | Shows AI-suggested opening messages       |
| `conversationSummary` | boolean | Generates AI-powered conversation summary |
| `smartReply`          | boolean | Shows AI-suggested quick reply options    |

<Tip>
  AI User Copilot features require an OpenAI API key. Configure it in the [CometChat Dashboard](https://app.cometchat.com) under **AI > Settings**.
</Tip>

### 1.4 User Management (`userManagement`)

| Setting       | Type    | What It Does                        |
| ------------- | ------- | ----------------------------------- |
| `friendsOnly` | boolean | Restricts chat to friends list only |

### 1.5 Group Management (`groupManagement`)

| Setting              | Type    | What It Does                       |
| -------------------- | ------- | ---------------------------------- |
| `createGroup`        | boolean | Lets users create new groups       |
| `addMembersToGroups` | boolean | Lets admins invite users to groups |
| `joinLeaveGroup`     | boolean | Lets users join/leave groups       |
| `deleteGroup`        | boolean | Lets owners delete groups          |
| `viewGroupMembers`   | boolean | Shows member list in group info    |

### 1.6 Moderator Controls (`moderatorControls`)

| Setting                | Type    | What It Does                         |
| ---------------------- | ------- | ------------------------------------ |
| `reportMessage`        | boolean | Lets users flag messages for review  |
| `kickUsers`            | boolean | Lets admins remove users from groups |
| `banUsers`             | boolean | Lets admins permanently ban users    |
| `promoteDemoteMembers` | boolean | Lets owners change member roles      |

### 1.7 Private Messaging Within Groups (`privateMessagingWithinGroups`)

| Setting                            | Type    | What It Does                                  |
| ---------------------------------- | ------- | --------------------------------------------- |
| `sendPrivateMessageToGroupMembers` | boolean | Lets users start 1:1 chats with group members |

### 1.8 In-App Sounds (`inAppSounds`)

| Setting                | Type    | What It Does                      |
| ---------------------- | ------- | --------------------------------- |
| `incomingMessageSound` | boolean | Plays sound for new messages      |
| `outgoingMessageSound` | boolean | Plays sound when sending messages |

***

## 2. Call Features (`callFeatures`)

### 2.1 Voice and Video Calling (`voiceAndVideoCalling`)

| Setting                | Type    | What It Does                                                                |
| ---------------------- | ------- | --------------------------------------------------------------------------- |
| `oneOnOneVoiceCalling` | boolean | Shows phone icon in 1:1 chat header for starting voice calls                |
| `oneOnOneVideoCalling` | boolean | Shows video camera icon in 1:1 chat header for starting video calls         |
| `groupVideoConference` | boolean | Shows video camera icon in group chat header for starting group video calls |
| `groupVoiceConference` | boolean | Shows phone icon in group chat header for starting group voice calls        |

<Tip>
  Learn more about [Call Features](/docs/ui-kit/flutter/call-features).
</Tip>

***

## 3. Layout (`layout`)

| Setting       | Type      | What It Does                                                                                           |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `withSideBar` | boolean   | Shows navigation sidebar with tabs (Chats, Calls, Users, Groups)                                       |
| `tabs`        | string\[] | Array of tabs to show: `'chats'`, `'calls'`, `'users'`, `'groups'`                                     |
| `chatType`    | string    | Default conversation type on load: `'user'` for 1:1 chats, `'group'` for group chats, `'both'` for all |

<Tip>
  Set `withSideBar: false` for embedded chat widgets or single-conversation
  views where navigation isn't needed.
</Tip>

***

## 4. Style (`style`)

### 4.1 Theme

| Setting | Type   | What It Does                                                 |
| ------- | ------ | ------------------------------------------------------------ |
| `theme` | string | Controls light/dark mode: `'light'`, `'dark'`, or `'system'` |

### 4.2 Colors

| Setting              | Type   | What It Does                                     |
| -------------------- | ------ | ------------------------------------------------ |
| `brandColor`         | string | Primary accent color (hex). Example: `"#6852D6"` |
| `primaryTextLight`   | string | Main text color in light mode                    |
| `primaryTextDark`    | string | Main text color in dark mode                     |
| `secondaryTextLight` | string | Secondary text color in light mode               |
| `secondaryTextDark`  | string | Secondary text color in dark mode                |

### 4.3 Typography

| Setting | Type   | What It Does                                                          |
| ------- | ------ | --------------------------------------------------------------------- |
| `font`  | string | Font family: `'roboto'`, `'arial'`, `'inter'`, or `'times new roman'` |
| `size`  | string | Text size: `'default'`, `'compact'`, or `'comfortable'`               |

***

## Complete Settings Example

```json theme={null}
{
  "builderId": "your-builder-id",
  "settings": {
    "chatFeatures": {
      "coreMessagingExperience": {
        "typingIndicator": true,
        "threadConversationAndReplies": true,
        "photosSharing": true,
        "videoSharing": true,
        "audioSharing": true,
        "fileSharing": true,
        "editMessage": true,
        "deleteMessage": true,
        "messageDeliveryAndReadReceipts": true,
        "userAndFriendsPresence": true,
        "conversationAndAdvancedSearch": true,
        "moderation": true,
        "quotedReplies": false,
        "markAsUnread": false
      },
      "deeperUserEngagement": {
        "mentions": true,
        "mentionAll": true,
        "reactions": true,
        "messageTranslation": true,
        "polls": true,
        "collaborativeWhiteboard": true,
        "collaborativeDocument": true,
        "voiceNotes": true,
        "emojis": true,
        "stickers": true,
        "userInfo": true,
        "groupInfo": true
      },
      "aiUserCopilot": {
        "conversationStarter": false,
        "conversationSummary": false,
        "smartReply": false
      },
      "userManagement": {
        "friendsOnly": false
      },
      "groupManagement": {
        "createGroup": true,
        "addMembersToGroups": true,
        "joinLeaveGroup": true,
        "deleteGroup": true,
        "viewGroupMembers": true
      },
      "moderatorControls": {
        "kickUsers": true,
        "banUsers": true,
        "promoteDemoteMembers": true,
        "reportMessage": true
      },
      "privateMessagingWithinGroups": {
        "sendPrivateMessageToGroupMembers": true
      },
      "inAppSounds": {
        "incomingMessageSound": true,
        "outgoingMessageSound": true
      }
    },
    "callFeatures": {
      "voiceAndVideoCalling": {
        "oneOnOneVoiceCalling": true,
        "oneOnOneVideoCalling": true,
        "groupVideoConference": true,
        "groupVoiceConference": true
      }
    },
    "layout": {
      "withSideBar": true,
      "tabs": ["chats", "calls", "users", "groups"],
      "chatType": "both"
    },
    "style": {
      "theme": "system",
      "color": {
        "brandColor": "#6852D6",
        "primaryTextLight": "#141414",
        "primaryTextDark": "#FFFFFF",
        "secondaryTextLight": "#727272",
        "secondaryTextDark": "#989898"
      },
      "typography": {
        "font": "roboto",
        "size": "default"
      }
    }
  }
}
```

***

## Accessing Settings in Code

Use the `BuilderSettingsHelper` to access settings in your Flutter code:

```dart theme={null}
import 'package:chat_builder/utils/builder_settings_helper.dart';

// Access settings after loading
final settings = BuilderSettingsHelper.settings;

// Check if a feature is enabled
if (settings.chatFeatures.coreMessagingExperience.photosSharing) {
  // Enable photo sharing functionality
}

// Access style settings
final brandColor = settings.style.color.brandColor;
final theme = settings.style.theme;

// Access layout settings
final tabs = settings.layout.tabs;
final withSideBar = settings.layout.withSideBar;
```

***

## Dashboard Feature Requirements

Some features require additional configuration in the [CometChat Dashboard](https://app.cometchat.com):

<Note>
  **AI Copilot Features** (Conversation Starter, Conversation Summary, Smart Reply)

  * Requires an OpenAI API key configured in the Dashboard under **AI > Settings**
</Note>

<Note>
  **Stickers, Polls, Collaborative Tools, Message Translation**

  * Requires the respective extensions to be enabled in the Dashboard under **Extensions**
</Note>

<Note>
  **Moderation**

  * Requires moderation rules to be configured in the Dashboard under **Moderation > Rules**
</Note>


# UI Kit Builder Integration
Source: https://www.cometchat.com/docs/chat-builder/flutter/integration

Integrate CometChat UI Kit Builder into Flutter apps with exported assets, app keys, dependencies, and platform setup.

UI Kit Builder streamlines integrating CometChat's Flutter UI Kit into your cross-platform app. Design the experience visually, export platform-ready assets, and connect them to your Flutter project with just a few steps.

<Frame>
  <img />
</Frame>

***

## Prerequisites

Before running this project, make sure you have:

* **Flutter SDK** (stable channel) with Dart 3+
* **macOS, Windows, or Linux** with Flutter tooling (Android Studio, VS Code, or IntelliJ)
* **For iOS builds**: Xcode, CocoaPods, and an iOS 13+ simulator or device
* **For Android builds**: Android Studio and an Android 5.0 (API 21)+ emulator or device
* **Internet connection** (required for CometChat services)

***

## Platform Requirements

### iOS

Update your `Podfile` and set the iOS platform to 13.0 or higher:

```ruby theme={null}
platform :ios, '13.0'
```

### Android

Change the `ndkVersion` and `minSdk` in your `android/app/build.gradle.kts`:

```kotlin theme={null}
android {
    // Other Settings
    ndkVersion = "27.0.12077973"

    defaultConfig {
        // Other Settings
        minSdk = 24
    }
}
```

***

## Complete Integration Workflow

1. **Design Your Chat Experience** - Use the UI Kit Builder to customize layouts, features, and styling.
2. **Review and Export** - Review which features will be enabled in your Dashboard, toggle them on/off, and download the generated code package.
3. **Preview Customizations** - Optionally, preview the chat experience before integrating it into your project.
4. **Integration** - Integrate into your existing application using the Module Import method.
5. **Customize Further** - Explore advanced customization options to tailor the chat experience.

***

## Launch the UI Kit Builder

1. Log in to your [CometChat Dashboard](https://app.cometchat.com).
2. Select your application from the list.
3. Navigate to **Integrate** → **Flutter** → **Launch UI Kit Builder**.

***

## Integration with CometChat UI Kit Builder

Follow these steps to wire the Builder output into your existing Flutter app.

### Step 1: Download the Builder Package

Download the Chat Builder app from the CometChat Dashboard. Inside you will find a `chat_builder` module, assets, and helper utilities.

### Step 2: Add the Builder Module to Your Project

Copy the `chat_builder` project directory and paste it in your app's root directory (next to your `lib`, `ios`, and `android` folders).

### Step 3: Copy Builder Assets

Copy all the contents from the assets directory of the `chat_builder` and add it to your project assets:

* **Source:** `chat_builder/assets/`
* **Destination:** `assets/`

Keep the folder structure intact so fonts, JSON files, and images resolve correctly.

### Step 4: Update `pubspec.yaml`

Point to the local Builder module and register the assets and fonts supplied by the export:

```yaml theme={null}
dependencies:
  # other dependencies
  chat_builder:
    path: ./chat_builder

flutter:
  uses-material-design: true
  assets:
    - assets/
    - assets/sample_app/
  fonts:
    - family: arial
      fonts:
        - asset: assets/fonts/arial_regular.ttf
        - asset: assets/fonts/arial_medium.ttf
        - asset: assets/fonts/arial_bold.ttf
    - family: inter
      fonts:
        - asset: assets/fonts/inter_regular.otf
        - asset: assets/fonts/inter_medium.otf
        - asset: assets/fonts/inter_bold.otf
    - family: roboto
      fonts:
        - asset: assets/fonts/roboto_regular.ttf
        - asset: assets/fonts/roboto_medium.ttf
        - asset: assets/fonts/roboto_bold.ttf
    - family: times New Roman
      fonts:
        - asset: assets/fonts/times_new_roman_regular.ttf
        - asset: assets/fonts/times_new_roman_medium.otf
        - asset: assets/fonts/times_new_roman_bold.otf
```

<Note>
  Ensure indentation is consistent—Flutter's asset and font declarations are whitespace sensitive.
</Note>

### Step 5: Install Dependencies

Run the following commands at the root of your project:

```bash theme={null}
flutter pub get
cd ios && pod install
```

### Step 6: Initialize Builder Settings

In the main file of your project, add the following lines before `runApp()`:

```dart theme={null}
import 'package:flutter/widgets.dart';
import 'package:chat_builder/utils/builder_settings_helper.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await BuilderSettingsHelper.loadFromAsset();
  runApp(const MyApp());
}
```

This ensures generated constants, themes, and resources are ready when your widgets build.

### Step 7: Launch UI Kit Builder Screens

Use the `ChatBuilder` APIs to open preconfigured experiences.

**If CometChat is not initialized or user is not logged in:**

```dart theme={null}
import 'package:chat_builder/chat_builder.dart';

ChatBuilder.launchBuilder(context);
```

**If CometChat is initialized and user is logged in:**

Open Messages screen for a User:

```dart theme={null}
ChatBuilder.launchMessages(
  context: context,
  user: user, // instance of CometChatUser
);
```

Open Messages screen for a Group:

```dart theme={null}
ChatBuilder.launchMessages(
  context: context,
  group: group, // instance of CometChatGroup
);
```

### Step 8: Refresh Settings After Updates

Whenever you export a new Builder configuration, replace the generated JSON, fonts, and assets in your project, then rerun `flutter pub get` to pick up changes.

***

## Enable Features in CometChat Dashboard

If your app needs any of these features, enable them from your [Dashboard](https://app.cometchat.com):

* Stickers
* Polls
* Collaborative whiteboard
* Collaborative document
* Message translation
* AI User Copilot: Conversation starter, Conversation summary, Smart reply

**How to enable:**

<Frame>
  <img />
</Frame>

1. Log in to the Dashboard.
2. Select your app.
3. Navigate to **Chat → Features**.
4. Toggle ON the required features and Save.

***

## Important Guidelines for Changes

<Note>
  **Functional Changes:**
  For enabling or disabling features and adjusting configurations, update the `BuilderSettingsHelper` or modify the configuration JSON. This controls all feature flags and configuration constants.
</Note>

<Note>
  **UI and Theme-related Changes:**
  For any updates related to UI, such as colors, fonts, and styles, modify the theme configuration in the Builder or update the `pubspec.yaml` font definitions.
</Note>

***

## Troubleshooting

### Builder Package Not Found

* Confirm the `chat_builder` directory path in `pubspec.yaml` is correct
* Ensure the module is at the root level of your project

### Assets Missing at Runtime

* Verify the asset paths in `pubspec.yaml`
* Rerun `flutter pub get` after any changes

### iOS Build Issues

* Make sure you ran `pod install` inside the `ios` directory after adding the new dependency
* Check that the iOS platform version in `Podfile` is 13.0 or higher

### Undefined Symbols

* Reimport or regenerate the `BuilderSettingsHelper` if package paths changed
* Clean and rebuild: `flutter clean && flutter pub get`

***

## Next Steps

<CardGroup>
  <Card title="Builder Settings" href="/chat-builder/flutter/builder-settings">
    Understand the settings file and feature toggles.
  </Card>

  <Card title="Customizations" href="/chat-builder/flutter/builder-customisations">
    Adjust component props, behavior, and UI elements.
  </Card>

  <Card title="Directory Structure" href="/chat-builder/flutter/builder-dir-structure">
    See how the exported code is organized.
  </Card>

  <Card title="UI Kit Theme" href="/ui-kit/flutter/theme-introduction">
    Customize colors, typography, and styling to match your brand.
  </Card>
</CardGroup>


# CometChat UI Kit Builder For Flutter
Source: https://www.cometchat.com/docs/chat-builder/flutter/overview

CometChat UI Kit Builder for Flutter provides a pre-built interface to integrate a reliable, fully-featured chat experience into new or existing apps.

It provides a set of prebuilt, production-ready messaging components backed by CometChat's real-time infrastructure.

With CometChat UI Kit Builder, you can:

* Configure chat and calling features
* Apply theming and layout options
* Export Flutter-ready code

The exported UI connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling.

## What You Can Configure

Toggle these features on or off directly in the UI Kit Builder. For a full reference of each setting, see [UI Kit Builder Settings](/docs/chat-builder/flutter/builder-settings).

### Chat Features

| Category                        | Includes                                                                                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Core Messaging Experience       | Typing indicators, threads, media sharing (photos, video, audio, files), edit & delete messages, read receipts, search, quoted replies, mark as unread |
| Deeper User Engagement          | Mentions, @all mentions, reactions, message translation, polls, collaborative whiteboard & document, voice notes, emojis, stickers, user & group info  |
| AI User Copilot                 | Conversation starters, conversation summaries, smart replies                                                                                           |
| User Management                 | Friends-only mode                                                                                                                                      |
| Group Management                | Create groups, add members, join/leave, delete groups, view members                                                                                    |
| Moderation                      | Content moderation, report messages, kick/ban users, promote/demote members                                                                            |
| Private Messaging Within Groups | Direct messages between group members                                                                                                                  |
| In-App Sounds                   | Incoming & outgoing message sounds                                                                                                                     |

### Call Features

| Category              | Includes                                                                             |
| --------------------- | ------------------------------------------------------------------------------------ |
| Voice & Video Calling | 1:1 voice calling, 1:1 video calling, group voice conference, group video conference |

### Layout

| Category | Includes                                |
| -------- | --------------------------------------- |
| Sidebar  | With Sidebar or Without Sidebar mode    |
| Tabs     | Conversations, Call Logs, Users, Groups |

### Theming

| Category   | Includes                                                    |
| ---------- | ----------------------------------------------------------- |
| Theme      | System, Light, or Dark mode                                 |
| Colors     | Brand color, primary & secondary text colors (light & dark) |
| Typography | Font family, text sizing (default, compact, comfortable)    |

***

## How to Use UI Kit Builder

### 1. Design

Configure your chat layout, toggle features, and pick a theme using the UI Kit Builder.

<Frame>
  <img />
</Frame>

### 2. Export

Click **Export Code** to generate a production-ready Flutter module based on your configuration.

### 3. Integrate

Drop the exported module into your Flutter project, add your CometChat credentials, and run the app. See the [Integration Guide](/docs/chat-builder/flutter/integration) for full steps.

***

## Try Live Demo

Experience the CometChat UI Kit Builder in action:

<CardGroup>
  <Card title="Launch Live Demo" icon="play" href="https://preview.cometchat.com/" />
</CardGroup>

***

## Next Steps

<CardGroup>
  <Card title="Integration" href="/chat-builder/flutter/integration">
    Step-by-step guide to integrate the UI Kit Builder.
  </Card>

  <Card title="Builder Settings" href="/chat-builder/flutter/builder-settings">
    Understand the settings file and feature toggles.
  </Card>

  <Card title="Customizations" href="/chat-builder/flutter/builder-customisations">
    Adjust component props, behavior, and UI elements.
  </Card>

  <Card title="Directory Structure" href="/chat-builder/flutter/builder-dir-structure">
    See how the exported code is organized.
  </Card>
</CardGroup>

***

## Helpful Resources

<CardGroup>
  <Card title="Flutter Sample App" href="https://github.com/cometchat/cometchat-uikit-flutter/tree/v5/sample_app">
    Try the fully featured Flutter sample for reference implementations.
  </Card>

  <Card title="UI Kit Source Code" href="https://github.com/cometchat/cometchat-uikit-flutter/tree/v5">
    Explore the complete Flutter UI Kit source code.
  </Card>

  <Card title="CometChat Dashboard" href="https://app.cometchat.com/">
    Configure features, manage users, and launch the UI Kit Builder.
  </Card>
</CardGroup>

***

## Need Help?

* Developer Community: [https://community.cometchat.com/](https://community.cometchat.com/)
* Support Portal: [https://help.cometchat.com/hc/en-us/requests/new](https://help.cometchat.com/hc/en-us/requests/new)


# Customizing Your UI Kit Builder
Source: https://www.cometchat.com/docs/chat-builder/ios/builder-customisations

Customize iOS UI Kit Builder components with CometChatBuilderSettings, themes, feature toggles, and UI behavior.

The `CometChatBuilderSettings` object handles feature toggles and styling configuration. For deeper customizations, you can access settings directly and apply them to CometChat UI components.

***

## Understanding the Customization Architecture

The iOS UI Kit Builder uses the following for customization:

| Component                  | Purpose                                          | When to Modify                               |
| -------------------------- | ------------------------------------------------ | -------------------------------------------- |
| `CometChatBuilderSettings` | Feature flags and configuration loaded from JSON | Functional changes (enable/disable features) |
| `CometChatTheme`           | Theme colors and styling                         | UI/visual changes (colors)                   |
| `CometChatTypography`      | Font family and text styling                     | Typography changes                           |

<Info>
  `CometChatBuilderSettings` is loaded from your `cometchat-builder-settings.json` file at app launch using `CometChatBuilderSettings.loadFromJSON()`.
</Info>

***

## Applying Theme Settings

Apply your Builder configuration to CometChat theme at app launch:

```swift theme={null}
import CometChatBuilder

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // Load JSON config
    CometChatBuilderSettings.loadFromJSON()

    // Apply brand color
    CometChatTheme.primaryColor = UIColor.dynamicColor(
        lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.brandColor),
        darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.brandColor)
    )
    
    // Apply text colors
    CometChatTheme.textColorPrimary = UIColor.dynamicColor(
        lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.primaryTextLight),
        darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.primaryTextDark)
    )
    
    CometChatTheme.textColorSecondary = UIColor.dynamicColor(
        lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.secondaryTextLight),
        darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.secondaryTextDark)
    )
    
    // Apply typography
    CometChatTypography.customFontFamilyName = CometChatBuilderSettings.shared.style.typography.font

    return true
}
```

***

## Accessing Feature Flags

You can access feature flags directly from `CometChatBuilderSettings.shared`:

### Chat Features

```swift theme={null}
import CometChatBuilder

// Core Messaging Experience
let typingEnabled = CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.typingIndicator
let threadsEnabled = CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.threadConversationAndReplies
let photosEnabled = CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.photosSharing

// Deeper User Engagement
let mentionsEnabled = CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.mentions
let reactionsEnabled = CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.reactions
let pollsEnabled = CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.polls

// AI User Copilot
let smartReplyEnabled = CometChatBuilderSettings.shared.chatFeatures.aiUserCopilot.smartReply
let conversationStarterEnabled = CometChatBuilderSettings.shared.chatFeatures.aiUserCopilot.conversationStarter

// Group Management
let createGroupEnabled = CometChatBuilderSettings.shared.chatFeatures.groupManagement.createGroup
let deleteGroupEnabled = CometChatBuilderSettings.shared.chatFeatures.groupManagement.deleteGroup

// Moderator Controls
let kickUsersEnabled = CometChatBuilderSettings.shared.chatFeatures.moderatorControls.kickUsers
let banUsersEnabled = CometChatBuilderSettings.shared.chatFeatures.moderatorControls.banUsers
```

### Call Features

```swift theme={null}
// Voice and Video Calling
let voiceCallEnabled = CometChatBuilderSettings.shared.callFeatures.voiceAndVideoCalling.oneOnOneVoiceCalling
let videoCallEnabled = CometChatBuilderSettings.shared.callFeatures.voiceAndVideoCalling.oneOnOneVideoCalling
let groupVideoEnabled = CometChatBuilderSettings.shared.callFeatures.voiceAndVideoCalling.groupVideoConference
let groupVoiceEnabled = CometChatBuilderSettings.shared.callFeatures.voiceAndVideoCalling.groupVoiceConference
```

### Layout Settings

```swift theme={null}
// Layout
let withSidebar = CometChatBuilderSettings.shared.layout.withSideBar
let tabs = CometChatBuilderSettings.shared.layout.tabs
let chatType = CometChatBuilderSettings.shared.layout.chatType
```

### Style Settings

```swift theme={null}
// Style
let theme = CometChatBuilderSettings.shared.style.theme
let brandColor = CometChatBuilderSettings.shared.style.color.brandColor
let font = CometChatBuilderSettings.shared.style.typography.font
let fontSize = CometChatBuilderSettings.shared.style.typography.size
```

***

## Conditional Feature Implementation

Use feature flags to conditionally show/hide UI elements:

```swift theme={null}
import CometChatBuilder

class MessagesViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Conditionally show voice call button
        if CometChatBuilderSettings.shared.callFeatures.voiceAndVideoCalling.oneOnOneVoiceCalling {
            setupVoiceCallButton()
        }
        
        // Conditionally show video call button
        if CometChatBuilderSettings.shared.callFeatures.voiceAndVideoCalling.oneOnOneVideoCalling {
            setupVideoCallButton()
        }
        
        // Conditionally enable reactions
        if CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.reactions {
            enableReactions()
        }
    }
}
```

***

## Customizing Colors Programmatically

You can customize colors beyond the JSON configuration:

```swift theme={null}
import CometChatUIKitSwift

// Override primary color
CometChatTheme.primaryColor = UIColor.systemBlue

// Override text colors
CometChatTheme.textColorPrimary = UIColor.dynamicColor(
    lightModeColor: .black,
    darkModeColor: .white
)

CometChatTheme.textColorSecondary = UIColor.dynamicColor(
    lightModeColor: .gray,
    darkModeColor: .lightGray
)

// Override background colors
CometChatTheme.backgroundColor01 = UIColor.dynamicColor(
    lightModeColor: .white,
    darkModeColor: .black
)
```

***

## Customizing Typography

Customize fonts and text styling:

```swift theme={null}
import CometChatUIKitSwift

// Set custom font family
CometChatTypography.customFontFamilyName = "Helvetica"

// Or use system fonts
CometChatTypography.customFontFamilyName = nil // Uses system default
```

***

## Component-Level Customizations

### Message List Configuration

```swift theme={null}
import CometChatUIKitSwift

let messageListConfiguration = MessageListConfiguration()

// Configure based on Builder settings
if CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.threadConversationAndReplies {
    messageListConfiguration.showThreadReplies = true
}

if CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.reactions {
    messageListConfiguration.showReactions = true
}

let messagesVC = CometChatMessages()
messagesVC.set(messageListConfiguration: messageListConfiguration)
```

### Message Composer Configuration

```swift theme={null}
import CometChatUIKitSwift

let composerConfiguration = MessageComposerConfiguration()

// Configure attachments based on Builder settings
composerConfiguration.hideAttachmentButton = !(
    CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.photosSharing ||
    CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.videoSharing ||
    CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.fileSharing
)

if CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.voiceNotes {
    composerConfiguration.hideVoiceRecording = false
}

let messagesVC = CometChatMessages()
messagesVC.set(messageComposerConfiguration: composerConfiguration)
```

***

## Modifying the JSON Configuration

To change feature settings, edit your `cometchat-builder-settings.json` file:

```json theme={null}
{
  "settings": {
    "chatFeatures": {
      "coreMessagingExperience": {
        "typingIndicator": true,
        "photosSharing": false,  // Disable photo sharing
        "videoSharing": false    // Disable video sharing
      },
      "deeperUserEngagement": {
        "reactions": true,
        "polls": false           // Disable polls
      }
    },
    "style": {
      "theme": "dark",           // Force dark mode
      "color": {
        "brandColor": "#FF5733"  // Custom brand color
      }
    }
  }
}
```

<Note>
  Changes to the JSON file require rebuilding the app to take effect.
</Note>

***

## Next Steps

<CardGroup>
  <Card title="UI Kit Builder Settings" href="/chat-builder/ios/builder-settings">
    Understand all available feature toggles and configuration options.
  </Card>

  <Card title="Components Overview" href="/ui-kit/ios/overview">
    Explore all available UI components and their customization options.
  </Card>

  <Card title="Theming" href="/ui-kit/ios/theme-introduction">
    Deep dive into colors, typography, and advanced styling.
  </Card>

  <Card title="Directory Structure" href="/chat-builder/ios/builder-dir-structure">
    Understand how the exported code is organized.
  </Card>
</CardGroup>


# Directory Structure
Source: https://www.cometchat.com/docs/chat-builder/ios/builder-dir-structure

Overview of the CometChat UI Kit Builder directory layout for iOS — understand where to find and customize components, settings, and styles.

The exported UI Kit Builder code is organized in a standard iOS project structure. This guide helps you navigate the structure so you know exactly where to make changes.

<Tree>
  <File name="BuilderApp">
    <File name="AppDelegate.swift" description="App lifecycle and CometChat initialization" />

    <File name="SceneDelegate.swift" description="Scene lifecycle management" />

    <File name="AppConstants.swift" description="App constants and credentials" />

    <File name="FrameworkManager.swift" description="Framework initialization helper" />

    <File name="cometchat-builder-settings.json" description="Builder configuration file" />

    <File name="Info.plist" description="App configuration" />

    <Folder name="Assets.xcassets" description="Images, icons, and color assets" />

    <Folder name="Base.lproj" description="Storyboards and launch screen" />

    <Folder name="Helper" description="Utility classes and extensions" />

    <Folder name="View Controllers" description="UI view controllers">
      <Folder name="CometChat Components" description="CometChat UI component wrappers" />

      <Folder name="LoginVC" description="Login and authentication views" />
    </Folder>
  </File>
</Tree>

***

## Root Files

| File                              | Purpose                                                               |
| --------------------------------- | --------------------------------------------------------------------- |
| `AppDelegate.swift`               | App lifecycle, CometChat initialization, and Builder settings loading |
| `SceneDelegate.swift`             | Scene lifecycle management for iOS 13+                                |
| `AppConstants.swift`              | CometChat credentials (APP\_ID, AUTH\_KEY, REGION)                    |
| `FrameworkManager.swift`          | Helper for initializing CometChat framework                           |
| `cometchat-builder-settings.json` | Builder configuration with feature flags, layout, and styling         |

***

## Key Folders

### `Assets.xcassets/`

Contains all image and color assets for the app.

<Tree>
  <Folder name="Assets.xcassets">
    <Folder name="AccentColor.colorset" description="App accent color" />

    <Folder name="AppIcon.appiconset" description="App icons for all sizes" />

    <Folder name="cometchat-logo.imageset" description="CometChat logo assets" />

    <Folder name="emptyChatState.imageset" description="Empty state illustrations" />
  </Folder>
</Tree>

### `Base.lproj/`

Contains storyboards and localization base files.

<Tree>
  <Folder name="Base.lproj">
    <File name="LaunchScreen.storyboard" description="App launch screen" />
  </Folder>
</Tree>

### `Helper/`

Utility classes and Swift extensions.

<Tree>
  <Folder name="Helper">
    <File name="CustomTextFiled.swift" description="Custom text field component" />

    <File name="Extentions.swift" description="Swift extensions (UIColor, etc.)" />
  </Folder>
</Tree>

### `View Controllers/`

All view controllers organized by feature.

<Tree>
  <Folder name="View Controllers">
    <File name="HomeScreenViewController.swift" description="Main home screen" />

    <File name="SplitScreenViewController.swift" description="Split view for iPad" />

    <Folder name="CometChat Components" description="CometChat UI wrappers">
      <File name="MessagesVC.swift" description="Messages screen" />

      <File name="ThreadedMessagesVC.swift" description="Threaded messages" />

      <File name="CreateConversations.swift" description="New conversation" />

      <Folder name="Add Members" description="Add members to group" />

      <Folder name="Banned Members" description="Banned members list" />

      <Folder name="Call Log Details" description="Call log details" />

      <Folder name="DetailsPage" description="User/Group details" />

      <Folder name="Group Component" description="Group-related views" />

      <Folder name="Transfer ownership" description="Transfer group ownership" />
    </Folder>

    <Folder name="LoginVC" description="Login screens">
      <File name="LoginWithUidVC.swift" description="UID login" />

      <File name="ChangeAppCredentialsVC.swift" description="Change credentials" />

      <File name="SampleUserCVCell.swift" description="Sample user cell" />
    </Folder>
  </Folder>
</Tree>

***

## Configuration Files

### `cometchat-builder-settings.json`

The main configuration file containing all Builder settings:

```json theme={null}
{
  "builderId": "your-builder-id",
  "settings": {
    "chatFeatures": { ... },
    "callFeatures": { ... },
    "layout": { ... },
    "style": { ... }
  }
}
```

### `AppConstants.swift`

Contains CometChat credentials:

```swift theme={null}
struct AppConstants {
    static let APP_ID = "YOUR_APP_ID"
    static let AUTH_KEY = "YOUR_AUTH_KEY"
    static let REGION = "YOUR_REGION"
}
```

***

## Quick Reference: Where to Customize

| What you want to change  | Where to look                                            |
| ------------------------ | -------------------------------------------------------- |
| Enable/disable features  | `cometchat-builder-settings.json`                        |
| CometChat credentials    | `AppConstants.swift`                                     |
| Theme colors & styles    | `cometchat-builder-settings.json` → `style` section      |
| App icons                | `Assets.xcassets/AppIcon.appiconset/`                    |
| Launch screen            | `Base.lproj/LaunchScreen.storyboard`                     |
| Messages screen behavior | `View Controllers/CometChat Components/MessagesVC.swift` |
| Login flow               | `View Controllers/LoginVC/`                              |
| Home screen layout       | `View Controllers/HomeScreenViewController.swift`        |
| Custom UI extensions     | `Helper/Extentions.swift`                                |

<Note>
  Prefer using `cometchat-builder-settings.json` for feature toggles and styling. For extensive changes, extend existing view controllers instead of modifying core files directly.
</Note>

***

## CometChat Components

The `CometChat Components` folder contains wrappers around CometChat UI Kit components:

| Component           | File                        | Purpose                    |
| ------------------- | --------------------------- | -------------------------- |
| Messages            | `MessagesVC.swift`          | Main messaging interface   |
| Threaded Messages   | `ThreadedMessagesVC.swift`  | Thread view for replies    |
| Create Conversation | `CreateConversations.swift` | Start new conversations    |
| Add Members         | `Add Members/`              | Add users to groups        |
| Banned Members      | `Banned Members/`           | View/manage banned users   |
| Call Log Details    | `Call Log Details/`         | Call history details       |
| Details Page        | `DetailsPage/`              | User/Group profile details |
| Group Component     | `Group Component/`          | Group management views     |
| Transfer Ownership  | `Transfer ownership/`       | Transfer group ownership   |

***

## Next Steps

<CardGroup>
  <Card title="UI Kit Builder Settings" href="/chat-builder/ios/builder-settings">
    Configure feature toggles and behavior
  </Card>

  <Card title="Customizations" href="/chat-builder/ios/builder-customisations">
    Modify component props, styling, and behavior
  </Card>

  <Card title="Theming" href="/ui-kit/ios/theme-introduction">
    Customize colors, typography, and styling
  </Card>

  <Card title="Components Overview" href="/ui-kit/ios/overview">
    Explore all available UI components
  </Card>
</CardGroup>


# UI Kit Builder Settings
Source: https://www.cometchat.com/docs/chat-builder/ios/builder-settings

Configure iOS UI Kit Builder settings for messaging, AI helpers, calling, layout, theming, and Swift configuration.

The `CometChatBuilderSettings` object controls everything the iOS UI Kit Builder renders—messaging, AI helpers, calls, layout, theming, and more. This object is loaded from your `cometchat-builder-settings.json` configuration file.

<Info>
  **For developers customizing their chat UI**: Edit `cometchat-builder-settings.json` to enable/disable features like messaging, calls, AI copilot, and theming. See the [Integration Guide](/docs/chat-builder/ios/integration) for setup.
</Info>

## Top-level Structure

The `CometChatBuilderSettings` object in Swift follows this structure:

```swift theme={null}
CometChatBuilderSettings.shared.chatFeatures
CometChatBuilderSettings.shared.callFeatures
CometChatBuilderSettings.shared.layout
CometChatBuilderSettings.shared.style
```

***

<Tip>
  All boolean settings follow the same pattern: `true` enables the feature and shows its UI elements, `false` hides them completely.
</Tip>

## 1. Chat Features (`chatFeatures`)

### 1.1 Core Messaging Experience (`coreMessagingExperience`)

Essential messaging features: typing indicators, media sharing, message actions, and presence.

| Setting                                                               | Type    | What It Does                                                                        |
| --------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| Typing indicator (`typingIndicator`)                                  | boolean | Shows "typing..." indicator when someone is composing a message                     |
| Thread conversation & replies (`threadConversationAndReplies`)        | boolean | Enables threaded replies to specific messages, creating nested conversation threads |
| Photos sharing (`photosSharing`)                                      | boolean | Allows users to share images from device or camera                                  |
| Video sharing (`videoSharing`)                                        | boolean | Allows users to share video files                                                   |
| Audio sharing (`audioSharing`)                                        | boolean | Allows users to share audio files (mp3, wav, etc.)                                  |
| File sharing (`fileSharing`)                                          | boolean | Allows users to share documents (PDF, DOC, etc.)                                    |
| Edit messages (`editMessage`)                                         | boolean | Lets users modify their sent messages; edited messages show "(edited)" label        |
| Delete messages (`deleteMessage`)                                     | boolean | Lets users remove their sent messages                                               |
| Message delivery and read receipts (`messageDeliveryAndReadReceipts`) | boolean | Shows delivery (✓) and read (✓✓) status indicators on messages                      |
| User & friends presence (`userAndFriendsPresence`)                    | boolean | Shows online/offline status dot next to user avatars                                |
| Conversation and Advanced Search (`conversationAndAdvancedSearch`)    | boolean | Enables search across messages, users, and conversations                            |
| Moderation (`moderation`)                                             | boolean | Enables blocked message feedback for messages blocked by moderation rules           |
| Quoted Replies (`quotedReplies`)                                      | boolean | Lets users quote a message when replying, showing the original above their response |
| Mark as Unread (`markAsUnread`)                                       | boolean | Lets users mark a conversation as unread to revisit later                           |

### 1.2 Deeper User Engagement (`deeperUserEngagement`)

Interactive features: mentions, reactions, polls, voice notes, and collaborative tools.

| Setting                                              | Type    | What It Does                                                                                |
| ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| Mentions (`mentions`)                                | boolean | Lets users @mention specific people in a message to notify them                             |
| Mention All (`mentionAll`)                           | boolean | Lets users type @all to notify every member in a group chat                                 |
| Reactions (`reactions`)                              | boolean | Lets users add emoji reactions (👍 ❤️ 😂 etc.) to messages                                  |
| Message Translation (`messageTranslation`)           | boolean | Translates messages to user's preferred language. Requires Dashboard setup                  |
| Polls (`polls`)                                      | boolean | Lets users create polls with multiple options for group voting. Requires Dashboard setup    |
| Collaborative Whiteboard (`collaborativeWhiteboard`) | boolean | Opens a shared whiteboard for real-time drawing and collaboration. Requires Dashboard setup |
| Collaborative Document (`collaborativeDocument`)     | boolean | Creates shared documents for real-time collaborative editing. Requires Dashboard setup      |
| Voice Notes (`voiceNotes`)                           | boolean | Lets users record and send voice messages                                                   |
| Emojis (`emojis`)                                    | boolean | Shows emoji picker in composer for browsing and inserting emojis                            |
| Stickers (`stickers`)                                | boolean | Lets users send sticker images from available packs. Requires Dashboard setup               |
| User Info (`userInfo`)                               | boolean | Lets users tap on another user's avatar to view their profile                               |
| Group Info (`groupInfo`)                             | boolean | Lets users tap on group header to view group details and member list                        |

### 1.3 AI User Copilot (`aiUserCopilot`)

AI-powered features to help users start and navigate conversations.

| Setting                                      | Type    | What It Does                                                                                  |
| -------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| Conversation Starter (`conversationStarter`) | boolean | Shows AI-suggested opening messages when starting a new chat. Requires OpenAI API key         |
| Conversation Summary (`conversationSummary`) | boolean | Generates an AI-powered summary of the conversation. Requires OpenAI API key                  |
| Smart Reply (`smartReply`)                   | boolean | Shows AI-suggested quick reply options based on conversation context. Requires OpenAI API key |

<Tip>
  AI User Copilot features require an OpenAI API key. Configure it in the [CometChat Dashboard](https://app.cometchat.com) under **AI > Settings**.
</Tip>

### 1.4 User Management (`userManagement`)

| Setting                      | Type    | What It Does                                                      |
| ---------------------------- | ------- | ----------------------------------------------------------------- |
| Friends Only (`friendsOnly`) | boolean | Restricts chat to friends list only; Users tab shows only friends |

### 1.5 Group Management (`groupManagement`)

Control what users can do with groups.

| Setting                                      | Type    | What It Does                                                      |
| -------------------------------------------- | ------- | ----------------------------------------------------------------- |
| Create Group (`createGroup`)                 | boolean | Lets users create new public or private groups                    |
| Add Members to Groups (`addMembersToGroups`) | boolean | Lets group admins/owners invite users to join the group           |
| Join/Leave Group (`joinLeaveGroup`)          | boolean | Lets users join public groups and leave groups they're in         |
| Delete Group (`deleteGroup`)                 | boolean | Lets group owners permanently delete a group and all its messages |
| View Group Members (`viewGroupMembers`)      | boolean | Shows member list in group info                                   |

### 1.6 Moderator Controls (`moderatorControls`)

Admin tools for managing group members and content.

| Setting                                         | Type    | What It Does                                                           |
| ----------------------------------------------- | ------- | ---------------------------------------------------------------------- |
| Report Message (`reportMessage`)                | boolean | Lets users flag messages for moderator review in Dashboard             |
| Kick Users (`kickUsers`)                        | boolean | Lets admins/moderators remove a user from a group (they can rejoin)    |
| Ban Users (`banUsers`)                          | boolean | Lets admins/moderators permanently remove a user and prevent rejoining |
| Promote/Demote Members (`promoteDemoteMembers`) | boolean | Lets group owners change member roles (member, moderator, admin)       |

### 1.7 Private Messaging Within Groups (`privateMessagingWithinGroups`)

Allow direct messages between group members.

| Setting                                                                    | Type    | What It Does                                                       |
| -------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| Send Private Message to Group Members (`sendPrivateMessageToGroupMembers`) | boolean | Lets users start a 1:1 chat with a group member from their profile |

### 1.8 In-App Sounds (`inAppSounds`)

Control sound notifications for incoming and outgoing messages.

| Setting                                         | Type    | What It Does                                 |
| ----------------------------------------------- | ------- | -------------------------------------------- |
| Incoming Message Sound (`incomingMessageSound`) | boolean | Plays a sound when a new message is received |
| Outgoing Message Sound (`outgoingMessageSound`) | boolean | Plays a sound when a message is sent         |

***

## 2. Call Features (`callFeatures`)

### 2.1 Voice and Video Calling (`voiceAndVideoCalling`)

Enable voice and video calling capabilities.

| Setting                                         | Type    | What It Does                                                                |
| ----------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| 1:1 Voice Calling (`oneOnOneVoiceCalling`)      | boolean | Shows phone icon in 1:1 chat header for starting voice calls                |
| 1:1 Video Calling (`oneOnOneVideoCalling`)      | boolean | Shows video camera icon in 1:1 chat header for starting video calls         |
| Group Video Conference (`groupVideoConference`) | boolean | Shows video camera icon in group chat header for starting group video calls |
| Group Voice Conference (`groupVoiceConference`) | boolean | Shows phone icon in group chat header for starting group voice calls        |

***

## 3. Layout (`layout`)

Control the overall UI structure and navigation.

| Setting                      | Type      | What It Does                                                                         |
| ---------------------------- | --------- | ------------------------------------------------------------------------------------ |
| With Sidebar (`withSideBar`) | boolean   | Shows navigation bar with tabs (Chats, Calls, Users, Groups)                         |
| Tabs (`tabs`)                | string\[] | Array of tabs to show: `'chats'`, `'calls'`, `'users'`, `'groups'`                   |
| Chat Type (`chatType`)       | string    | Default conversation type on load: `'user'` for 1:1 chats, `'group'` for group chats |

***

## 4. Style (`style`)

Customize colors, fonts, and theme appearance.

### 4.1 Theme

| Setting         | Type   | What It Does                                                                             |
| --------------- | ------ | ---------------------------------------------------------------------------------------- |
| Theme (`theme`) | string | Controls light/dark mode: `'light'`, `'dark'`, or `'system'` (matches device preference) |

### 4.2 Colors

| Setting                                     | Type   | What It Does                                                                             |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| Brand Color (`brandColor`)                  | string | Primary accent color (hex) for buttons, links, active states. Example: `"#6852D6"`       |
| Primary Text Light (`primaryTextLight`)     | string | Main text color in light mode (hex). Example: `"#141414"`                                |
| Primary Text Dark (`primaryTextDark`)       | string | Main text color in dark mode (hex). Example: `"#FFFFFF"`                                 |
| Secondary Text Light (`secondaryTextLight`) | string | Secondary text color in light mode (hex) for timestamps, subtitles. Example: `"#727272"` |
| Secondary Text Dark (`secondaryTextDark`)   | string | Secondary text color in dark mode (hex) for timestamps, subtitles. Example: `"#989898"`  |

### 4.3 Typography

| Setting       | Type   | What It Does                                                          |
| ------------- | ------ | --------------------------------------------------------------------- |
| Font (`font`) | string | Font family: `'roboto'`, `'arial'`, `'inter'`, or `'times new roman'` |
| Size (`size`) | string | Text size and spacing: `'default'`, `'compact'`, or `'comfortable'`   |

***

## Settings Overview

Below is the complete settings structure with default values. Update these in your `cometchat-builder-settings.json` file to customize your chat experience.

```json theme={null}
{
  "builderId": "your-builder-id",
  "settings": {
    "chatFeatures": {
      "coreMessagingExperience": {
        "typingIndicator": true,
        "threadConversationAndReplies": true,
        "photosSharing": true,
        "videoSharing": true,
        "audioSharing": true,
        "fileSharing": true,
        "editMessage": true,
        "deleteMessage": true,
        "messageDeliveryAndReadReceipts": true,
        "userAndFriendsPresence": true,
        "conversationAndAdvancedSearch": true,
        "moderation": true,
        "quotedReplies": false,
        "markAsUnread": false
      },
      "deeperUserEngagement": {
        "mentions": true,
        "mentionAll": true,
        "reactions": true,
        "messageTranslation": true,
        "polls": true,
        "collaborativeWhiteboard": true,
        "collaborativeDocument": true,
        "voiceNotes": true,
        "emojis": true,
        "stickers": true,
        "userInfo": true,
        "groupInfo": true
      },
      "aiUserCopilot": {
        "conversationStarter": false,
        "conversationSummary": false,
        "smartReply": false
      },
      "userManagement": {
        "friendsOnly": false
      },
      "groupManagement": {
        "createGroup": true,
        "addMembersToGroups": true,
        "joinLeaveGroup": true,
        "deleteGroup": true,
        "viewGroupMembers": true
      },
      "moderatorControls": {
        "kickUsers": true,
        "banUsers": true,
        "promoteDemoteMembers": true,
        "reportMessage": true
      },
      "privateMessagingWithinGroups": {
        "sendPrivateMessageToGroupMembers": true
      },
      "inAppSounds": {
        "incomingMessageSound": true,
        "outgoingMessageSound": true
      }
    },
    "callFeatures": {
      "voiceAndVideoCalling": {
        "oneOnOneVoiceCalling": true,
        "oneOnOneVideoCalling": true,
        "groupVideoConference": true,
        "groupVoiceConference": true
      }
    },
    "layout": {
      "withSideBar": true,
      "tabs": ["chats", "calls", "users", "groups"],
      "chatType": "user"
    },
    "style": {
      "theme": "system",
      "color": {
        "brandColor": "#6852D6",
        "primaryTextLight": "#141414",
        "primaryTextDark": "#FFFFFF",
        "secondaryTextLight": "#727272",
        "secondaryTextDark": "#989898"
      },
      "typography": {
        "font": "roboto",
        "size": "default"
      }
    }
  }
}
```

***

## Dashboard Feature Requirements

Some features require additional configuration in the [CometChat Dashboard](https://app.cometchat.com) before they can be used:

<Note>
  **AI Copilot Features** (Conversation Starter, Conversation Summary, Smart Reply)

  * Requires an OpenAI API key configured in the Dashboard under **AI > Settings**
</Note>

<Note>
  **Stickers**

  * Requires sticker packs to be configured in the Dashboard under **Chat & Messaging > Stickers**
</Note>

<Note>
  **Polls**

  * Requires the Polls extension to be enabled in the Dashboard under **Extensions > Polls**
</Note>

<Note>
  **Collaborative Whiteboard & Document**

  * Requires the respective extensions to be enabled in the Dashboard under **Extensions**
</Note>

<Note>
  **Message Translation**

  * Requires the Message Translation extension to be enabled in the Dashboard under **Extensions > Message Translation**
</Note>

***

## Next Steps

<CardGroup>
  <Card title="Directory Structure" href="/chat-builder/ios/builder-dir-structure">
    Understand the organization of the builder components and generated code.
  </Card>

  <Card title="Customizations" href="/chat-builder/ios/builder-customisations">
    Modify component props, styling, and behavior for deeper customization.
  </Card>
</CardGroup>


# UI Kit Builder Integration
Source: https://www.cometchat.com/docs/chat-builder/ios/integration

Step-by-step guide to integrating CometChat's UI Kit Builder into your iOS application using UI Kit Builder configuration.

This guide demonstrates how to integrate the **CometChat UI Kit Builder** configuration system into your iOS application. The configuration can be loaded into your app using a local JSON file.

<Frame>
  <img />
</Frame>

***

## Prerequisites

Before running this project on iOS, make sure you have:

* **Xcode** (latest version recommended)
* **macOS device** with macOS 12.0 or above
* **iOS Device or Simulator** with iOS 13.0 or above
* **CocoaPods** (latest version installed)
* **Internet connection** (required for CometChat services)

***

## Complete Integration Workflow

1. **Download the Project** - Download the project zip from the CometChat Dashboard and extract it.
2. **Install Dependencies** - Install CocoaPods dependencies.
3. **Configure Settings** - Load UI Kit Builder settings from JSON file.
4. **Build & Run** - Build and run the project in Xcode.

***

## Launch the UI Kit Builder

1. Log in to your [CometChat Dashboard](https://app.cometchat.com).
2. Select your application from the list.
3. Navigate to **Chat & Messaging** → **Get Started**.
4. Navigate to **Integrate** → **iOS** → **Launch UI Kit Builder**.

***

## Integration Options

Choose one of the following integration methods based on your needs:

| Option                                   | Best For                                                       | Complexity |
| ---------------------------------------- | -------------------------------------------------------------- | ---------- |
| **Run Sample App**                       | Quick preview and testing of Builder configurations            | Easy       |
| **Integrate Config Store** (Recommended) | Production apps where you want full control over customization | Medium     |

***

## Option 1: Run the Sample App

### Setup

### Step 1: Download and Extract Project

Download the project zip from the CometChat Dashboard and extract it.

### Step 2: Navigate to Project Folder

```bash theme={null}
cd <project-folder>
```

### Step 3: Open Xcode Project

Open the `.xcodeproj` file once to let Xcode configure the project.

### Step 4: Install Dependencies

Install dependencies using CocoaPods:

```bash theme={null}
pod install
```

### Step 5: Open Workspace

Open the `.xcworkspace` file instead of `.xcodeproj` from now on:

```bash theme={null}
open <ProjectName>.xcworkspace
```

### Step 6: Build & Run

Build and run the project in Xcode.

***

## Option 2: Integrate Builder Configuration into Your iOS App

This method gives you full control over customization and is recommended for production apps.

### Installation (CometChatBuilder)

### CocoaPods

Add to your `Podfile`:

```ruby theme={null}
pod 'CometChatBuilder'
```

Then run:

```bash theme={null}
pod install
```

### Swift Package Manager (SPM)

1. Open your Xcode project.
2. Go to **File → Add Packages**.
3. Enter the URL of your Git repository (or local path) where `CometChatBuilder` code is hosted.
4. Select the `CometChatBuilder` package and add it to your app target.

***

## Load Settings from JSON

Use this method if you are shipping a `.json` configuration file with your app.

### Step 1: Add Your JSON File

Place your `cometchat-builder-settings.json` inside your app target and make sure:

* It's added to your target membership.

### Step 2: Load Settings at Launch

```swift theme={null}
import CometChatBuilder

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // This automatically loads JSON config
    CometChatBuilderSettings.loadFromJSON()

    CometChatTheme.primaryColor = UIColor.dynamicColor(
        lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.brandColor),
        darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.brandColor)
    )
    
    CometChatTheme.textColorPrimary = UIColor.dynamicColor(
        lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.primaryTextLight),
        darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.primaryTextDark)
    )
    
    CometChatTheme.textColorSecondary = UIColor.dynamicColor(
        lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.secondaryTextLight),
        darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.secondaryTextDark)
    )
    
    CometChatTypography.customFontFamilyName = CometChatBuilderSettings.shared.style.typography.font

    return true
}
```

***

## Important Guidelines for Changes

<Note>
  **Functional Changes:**
  For enabling or disabling features and adjusting configurations, update the `cometchat-builder-settings.json` file. This controls all feature flags and configuration constants.
</Note>

<Note>
  **UI and Theme-related Changes:**
  For any updates related to UI, such as colors, fonts, and styles, modify the `CometChatTheme` and `CometChatTypography` properties in your AppDelegate.
</Note>

***

## Enable Features in CometChat Dashboard

If your app needs any of these features, enable them from your [Dashboard](https://app.cometchat.com):

* Stickers
* Polls
* Collaborative whiteboard
* Collaborative document
* Message translation
* AI User Copilot: Conversation starter, Conversation summary, Smart reply

**How to enable:**

<Frame>
  <img />
</Frame>

1. Log in to the Dashboard.
2. Select your app.
3. Navigate to **Chat → Features**.
4. Toggle ON the required features and Save.

***

## What You Can Configure

Toggle these features on or off directly in the UI Kit Builder. For a full reference of each setting, see [UI Kit Builder Settings](/docs/chat-builder/ios/builder-settings).

### Chat Features

| Category                        | Includes                                                                                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Core Messaging Experience       | Typing indicators, threads, media sharing (photos, video, audio, files), edit & delete messages, read receipts, search, quoted replies, mark as unread |
| Deeper User Engagement          | Mentions, @all mentions, reactions, message translation, polls, collaborative whiteboard & document, voice notes, emojis, stickers, user & group info  |
| AI User Copilot                 | Conversation starters, conversation summaries, smart replies                                                                                           |
| User Management                 | Friends-only mode                                                                                                                                      |
| Group Management                | Create groups, add members, join/leave, delete groups, view members                                                                                    |
| Moderation                      | Content moderation, report messages, kick/ban users, promote/demote members                                                                            |
| Private Messaging Within Groups | Direct messages between group members                                                                                                                  |
| In-App Sounds                   | Incoming & outgoing message sounds                                                                                                                     |

### Call Features

| Category              | Includes                                                                             |
| --------------------- | ------------------------------------------------------------------------------------ |
| Voice & Video Calling | 1:1 voice calling, 1:1 video calling, group voice conference, group video conference |

### Layout

| Category | Includes                                |
| -------- | --------------------------------------- |
| Sidebar  | With Sidebar or Without Sidebar mode    |
| Tabs     | Conversations, Call Logs, Users, Groups |

### Theming

| Category   | Includes                                                    |
| ---------- | ----------------------------------------------------------- |
| Theme      | System, Light, or Dark mode                                 |
| Colors     | Brand color, primary & secondary text colors (light & dark) |
| Typography | Font family, text sizing (default, compact, comfortable)    |

***

## Troubleshooting

### JSON File Not Found

* Ensure your `cometchat-builder-settings.json` is added to the app bundle.
* Confirm the file is included in your app target's Target Membership.

### Network Errors

* Network errors will fallback to user alerts.
* Ensure you have an active internet connection.

### SPM Resource Issues

* For SPM: make sure resources (images) are in `CometChatBuilder.bundle`.
* Confirm package resources are available to your target.

### QR Code Issues

* Ensure your QR code is valid and generated from the official builder.
* Confirm active network connectivity.

***

## Next Steps

<CardGroup>
  <Card title="Builder Settings" href="/chat-builder/ios/builder-settings">
    Understand the settings file and feature toggles.
  </Card>

  <Card title="Customizations" href="/chat-builder/ios/builder-customisations">
    Adjust component props, behavior, and UI elements.
  </Card>

  <Card title="Directory Structure" href="/chat-builder/ios/builder-dir-structure">
    See how the exported code is organized.
  </Card>

  <Card title="UI Kit Theme" href="/ui-kit/ios/theme-introduction">
    Customize colors, typography, and styling to match your brand.
  </Card>
</CardGroup>


# CometChat UI Kit Builder For iOS
Source: https://www.cometchat.com/docs/chat-builder/ios/overview

CometChat UI Kit Builder for iOS provides a pre-built interface to integrate a reliable, fully-featured chat experience.

The CometChat iOS UI Kit provides a pre-built user interface that developers can use to quickly integrate a reliable & fully-featured chat experience into an existing or new iOS app using **UI Kit Builder** configuration.

<Frame>
  <img />
</Frame>

***

## What is UI Kit Builder?

UI Kit Builder is CometChat's configuration system that allows you to customize chat features, UI components, and styling through a simple JSON configuration file. The configuration can be loaded into your app using a local JSON file.

***

## Builder Settings Categories

Your Builder configuration supports the following categories:

| Category                  | Description                             |
| ------------------------- | --------------------------------------- |
| Core Messaging Experience | Typing, media sharing, replies, etc.    |
| Deeper User Engagement    | Reactions, mentions, translation, polls |
| AI User Copilot           | Smart replies, summaries, starters      |
| Group Management          | Create/delete group, add members        |
| Moderator Controls        | Ban/kick/promote members                |
| Voice & Video Calling     | 1:1 and group calling support           |
| Layout & Styling          | Theme, typography, layout mode          |

***

## Try Live Demo

Experience the CometChat UI Kit Builder in action:

<CardGroup>
  <Card title="Launch Live Demo" icon="play" href="https://preview.cometchat.com/" />
</CardGroup>

***

## Next Steps

<CardGroup>
  <Card title="Integration Guide" icon="code" href="/chat-builder/ios/integration">
    Step-by-step instructions to integrate the UI Kit Builder into your iOS project.
  </Card>

  <Card title="Builder Settings" icon="sliders" href="/chat-builder/ios/builder-settings">
    Complete reference of all configuration options available in CometChatBuilderSettings.
  </Card>

  <Card title="Customizations" icon="paintbrush" href="/chat-builder/ios/builder-customisations">
    Learn how to customize components and styling.
  </Card>

  <Card title="Directory Structure" icon="folder-tree" href="/chat-builder/ios/builder-dir-structure">
    Understand the organization of the exported Builder code.
  </Card>
</CardGroup>

***

## Helpful Resources

<CardGroup>
  <Card title="iOS Builder App" href="https://apps.apple.com/in/app/cometchat-builder/id6740586011">
    Experience the power of CometChat UI Kit with this interactive app
  </Card>

  <Card title="UI Kit Source Code" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5">
    Explore the complete iOS UI Kit source code
  </Card>

  <Card title="Figma Design File" href="https://www.figma.com/community/file/1444325479486807899/cometchat-ui-kit-for-ios">
    UI design resources for customization and prototyping
  </Card>

  <Card title="Create Support Ticket" href="https://help.cometchat.com/hc/en-us/requests/new">
    Get assistance from our support team with any questions or issues
  </Card>
</CardGroup>


# Customizing Your UI Kit Builder
Source: https://www.cometchat.com/docs/chat-builder/react-native/builder-customisations

Customize CometChat UI Kit Builder components — modify props, styling, and behavior for React Native.

The `config.json` file handles basic feature toggles. For deeper customizations, modify the Zustand store, theme configuration, or component props directly.

***

## Understanding the Customization Architecture

The React Native UI Kit Builder uses these main files for customization:

| File          | Purpose                                   | When to Modify                               |
| ------------- | ----------------------------------------- | -------------------------------------------- |
| `config.json` | Feature flags and configuration constants | Functional changes (enable/disable features) |
| `store.ts`    | Zustand store for state management        | Runtime configuration updates                |
| Theme object  | Colors, typography, and styling           | UI/visual changes                            |

<Info>
  The `config.json` file is the source of truth for your Builder configuration. You can update it manually or by scanning a QR code with new settings.
</Info>

***

## Using the Configuration Store

The Zustand store manages your Builder configuration at runtime. Access it anywhere in your app to read or update settings.

### Reading Configuration

```tsx theme={null}
import { useConfig } from './src/config/store';

const MyComponent = () => {
  // Access entire settings object
  const settings = useConfig((state) => state.settings);
  
  // Access specific feature category
  const chatFeatures = useConfig((state) => state.settings.chatFeatures);
  
  // Access style configuration
  const styleConfig = useConfig((state) => state.settings.style);
  
  return (/* ... */);
};
```

### Updating Configuration at Runtime

```tsx theme={null}
import { useConfigStore } from './src/config/store';

// Update a specific setting
const updateFeature = () => {
  const store = useConfigStore.getState();
  store.updateSettings({
    ...store.settings,
    chatFeatures: {
      ...store.settings.chatFeatures,
      coreMessagingExperience: {
        ...store.settings.chatFeatures.coreMessagingExperience,
        photosSharing: false,
      },
    },
  });
};
```

<Note>
  Runtime changes to the store are not persisted by default. Use AsyncStorage to save and restore configurations.
</Note>

***

## Theme Customization

### Applying Builder Theme to UI Kit

The Builder configuration includes style settings that should be applied to the CometChat UI Kit theme:

```tsx theme={null}
import React from 'react';
import { CometChatThemeProvider } from '@cometchat/chat-uikit-react-native';
import { useConfig } from './src/config/store';

const App = () => {
  const styleConfig = useConfig((state) => state.settings.style);

  const theme = {
    light: {
      color: {
        primary: styleConfig.color.brandColor,
        textPrimary: styleConfig.color.primaryTextLight,
        textSecondary: styleConfig.color.secondaryTextLight,
        background: '#FFFFFF',
        border: '#E8E8E8',
      },
      typography: {
        fontFamily: getFontFamily(styleConfig.typography.font),
      },
    },
    dark: {
      color: {
        primary: styleConfig.color.brandColor,
        textPrimary: styleConfig.color.primaryTextDark,
        textSecondary: styleConfig.color.secondaryTextDark,
        background: '#141414',
        border: '#3D3D3D',
      },
      typography: {
        fontFamily: getFontFamily(styleConfig.typography.font),
      },
    },
  };

  return (
    <CometChatThemeProvider theme={theme}>
      {/* Your app components */}
    </CometChatThemeProvider>
  );
};
```

### Custom Color Palette

Override the default colors by modifying the theme object:

```tsx theme={null}
const customTheme = {
  light: {
    color: {
      primary: '#FF6B6B',        // Custom brand color
      textPrimary: '#2D3436',    // Custom primary text
      textSecondary: '#636E72',  // Custom secondary text
      success: '#00B894',        // Success state
      error: '#D63031',          // Error state
      warning: '#FDCB6E',        // Warning state
    },
  },
  dark: {
    color: {
      primary: '#FF6B6B',
      textPrimary: '#DFE6E9',
      textSecondary: '#B2BEC3',
      success: '#00B894',
      error: '#FF7675',
      warning: '#FFEAA7',
    },
  },
};
```

***

## Custom Font Integration

### Step 1: Add Font Files

Add your custom font files to the appropriate platform directories:

* **iOS:** `ios/<App>/Resources/Fonts/`
* **Android:** `android/app/src/main/assets/fonts/`

### Step 2: Link Fonts (React Native CLI)

For React Native CLI projects, create or update `react-native.config.js`:

```js theme={null}
module.exports = {
  assets: ['./assets/fonts'],
};
```

Then run:

```bash theme={null}
npx react-native-asset
```

### Step 3: Map Font Family

Create a font mapping utility:

```tsx theme={null}
import { Platform } from 'react-native';

const FONT_MAP = {
  'roboto': {
    regular: Platform.OS === 'ios' ? 'Roboto-Regular' : 'roboto_regular',
    medium: Platform.OS === 'ios' ? 'Roboto-Medium' : 'roboto_medium',
    bold: Platform.OS === 'ios' ? 'Roboto-Bold' : 'roboto_bold',
  },
  'inter': {
    regular: Platform.OS === 'ios' ? 'Inter-Regular' : 'inter_regular',
    medium: Platform.OS === 'ios' ? 'Inter-Medium' : 'inter_medium',
    bold: Platform.OS === 'ios' ? 'Inter-Bold' : 'inter_bold',
  },
  'your-custom-font': {
    regular: Platform.OS === 'ios' ? 'YourFont-Regular' : 'your_font_regular',
    medium: Platform.OS === 'ios' ? 'YourFont-Medium' : 'your_font_medium',
    bold: Platform.OS === 'ios' ? 'YourFont-Bold' : 'your_font_bold',
  },
};

export const getFontFamily = (fontName: string) => {
  return FONT_MAP[fontName] || FONT_MAP['roboto'];
};
```

***

## Component-Level Customizations

### Conditional Rendering Based on Features

Use the configuration store to conditionally render UI elements:

```tsx theme={null}
import { useConfig } from './src/config/store';

const MessageComposer = () => {
  const chatFeatures = useConfig((state) => state.settings.chatFeatures);
  const { coreMessagingExperience, deeperUserEngagement } = chatFeatures;

  return (
    <View>
      {/* Always show text input */}
      <TextInput placeholder="Type a message..." />
      
      {/* Conditionally show attachment options */}
      {coreMessagingExperience.photosSharing && (
        <PhotoAttachmentButton />
      )}
      
      {coreMessagingExperience.fileSharing && (
        <FileAttachmentButton />
      )}
      
      {deeperUserEngagement.voiceNotes && (
        <VoiceNoteButton />
      )}
      
      {deeperUserEngagement.stickers && (
        <StickerButton />
      )}
    </View>
  );
};
```

### Customizing Message Options

Control which message options appear based on configuration:

```tsx theme={null}
const MessageOptions = ({ message }) => {
  const chatFeatures = useConfig((state) => state.settings.chatFeatures);
  const { coreMessagingExperience, deeperUserEngagement, moderatorControls } = chatFeatures;

  const options = [];

  if (coreMessagingExperience.quotedReplies) {
    options.push({ label: 'Reply', action: 'reply' });
  }

  if (coreMessagingExperience.threadConversationAndReplies) {
    options.push({ label: 'Reply in Thread', action: 'thread' });
  }

  if (deeperUserEngagement.reactions) {
    options.push({ label: 'React', action: 'react' });
  }

  if (coreMessagingExperience.editMessage && message.sender.uid === currentUser.uid) {
    options.push({ label: 'Edit', action: 'edit' });
  }

  if (coreMessagingExperience.deleteMessage && message.sender.uid === currentUser.uid) {
    options.push({ label: 'Delete', action: 'delete' });
  }

  if (moderatorControls.reportMessage) {
    options.push({ label: 'Report', action: 'report' });
  }

  return <OptionsMenu options={options} />;
};
```

***

## Persisting Configuration

### Save Configuration to AsyncStorage

```tsx theme={null}
import AsyncStorage from '@react-native-async-storage/async-storage';
import { useConfigStore } from './src/config/store';

const CONFIG_KEY = '@cometchat_builder_config';

export const saveConfig = async () => {
  try {
    const config = useConfigStore.getState();
    await AsyncStorage.setItem(CONFIG_KEY, JSON.stringify(config));
  } catch (error) {
    console.error('Failed to save config:', error);
  }
};

export const loadConfig = async () => {
  try {
    const savedConfig = await AsyncStorage.getItem(CONFIG_KEY);
    if (savedConfig) {
      const parsed = JSON.parse(savedConfig);
      useConfigStore.getState().updateConfig(parsed);
    }
  } catch (error) {
    console.error('Failed to load config:', error);
  }
};
```

### Auto-save on Configuration Changes

```tsx theme={null}
import { useEffect } from 'react';
import { useConfigStore } from './src/config/store';

const ConfigPersistence = () => {
  const config = useConfigStore((state) => state);

  useEffect(() => {
    // Debounce saves to avoid excessive writes
    const timeoutId = setTimeout(() => {
      saveConfig();
    }, 1000);

    return () => clearTimeout(timeoutId);
  }, [config]);

  return null;
};
```

***

## Layout Customization

### Dynamic Tab Configuration

```tsx theme={null}
import { useConfig } from './src/config/store';

const TabNavigator = () => {
  const layout = useConfig((state) => state.settings.layout);
  const { tabs, withSideBar } = layout;

  if (!withSideBar) {
    return <SingleChatView />;
  }

  return (
    <Tab.Navigator>
      {tabs.includes('chats') && (
        <Tab.Screen name="Chats" component={ChatsScreen} />
      )}
      {tabs.includes('calls') && (
        <Tab.Screen name="Calls" component={CallsScreen} />
      )}
      {tabs.includes('users') && (
        <Tab.Screen name="Users" component={UsersScreen} />
      )}
      {tabs.includes('groups') && (
        <Tab.Screen name="Groups" component={GroupsScreen} />
      )}
    </Tab.Navigator>
  );
};
```


# Directory Structure
Source: https://www.cometchat.com/docs/chat-builder/react-native/builder-dir-structure

Overview of the CometChat UI Kit Builder directory layout for React Native — understand where to find and customize components, settings, and styles.

The UI Kit Builder for React Native organizes code into logical directories for components, configuration, navigation, and utilities. This guide helps you navigate the structure so you know exactly where to make changes.

```
src/
├── components/
│   ├── conversations/     # Chat and messaging components
│   ├── calls/             # Voice/video calling components
│   ├── groups/            # Group management components
│   ├── users/             # User management components
│   └── login/             # Authentication components
├── config/
│   ├── store.ts           # Zustand store for configuration
│   └── config.json        # Default configuration template
├── navigation/            # App navigation setup
├── utils/                 # Helper utilities and constants
└── assets/                # Icons, images, and fonts
```

***

## Root Files

| File              | Purpose                                                |
| ----------------- | ------------------------------------------------------ |
| `App.tsx`         | Main application entry point with theme provider setup |
| `package.json`    | Project dependencies and npm scripts                   |
| `metro.config.js` | Metro bundler configuration                            |
| `babel.config.js` | Babel transpiler configuration                         |

***

## Key Folders

### `config/`

Configuration management for the Builder settings.

```
config/
├── store.ts      # Zustand store managing Builder settings state
└── config.json   # Default configuration with all feature toggles
```

| File          | Purpose                                                                                 |
| ------------- | --------------------------------------------------------------------------------------- |
| `store.ts`    | Zustand store that manages Builder settings, provides hooks for accessing configuration |
| `config.json` | Default configuration template with all feature flags, layout, and style settings       |

### `components/`

Each component folder contains the main component file and associated hooks. These are the building blocks of your chat UI.

```
components/
├── conversations/     # Conversation list, message threads, chat UI
├── calls/             # Call screens, call logs, call controls
├── groups/            # Group list, group details, member management
├── users/             # User list, user profiles, presence indicators
└── login/             # Login screen, authentication flow
```

### `navigation/`

Navigation configuration using React Navigation.

```
navigation/
├── AppNavigator.tsx   # Main navigation stack
├── TabNavigator.tsx   # Bottom tab navigation
└── types.ts           # Navigation type definitions
```

### `utils/`

Utility functions and application constants.

```
utils/
├── AppConstants.tsx   # CometChat credentials (APP_ID, AUTH_KEY, REGION)
└── helpers.ts         # General utility functions
```

### `assets/`

Static assets including icons, images, and fonts.

```
assets/
├── icons/             # App icons and UI icons
├── images/            # Illustrations and backgrounds
└── fonts/             # Custom font files
```

***

## Platform Directories

### `ios/`

iOS-specific native code and configuration.

```
ios/
├── YourApp/
│   ├── AppDelegate.mm     # iOS app delegate
│   ├── Info.plist         # iOS app configuration
│   └── Resources/
│       └── Fonts/         # iOS font files
└── Podfile                # CocoaPods dependencies
```

### `android/`

Android-specific native code and configuration.

```
android/
├── app/
│   ├── src/main/
│   │   ├── AndroidManifest.xml   # Android app manifest
│   │   ├── assets/
│   │   │   └── fonts/            # Android font files
│   │   ├── java/                 # Native Android code
│   │   └── res/                  # Android resources
│   └── build.gradle              # App-level Gradle config
├── build.gradle                  # Project-level Gradle config
└── settings.gradle               # Gradle settings
```

***

## Quick Reference: Where to Customize

| What you want to change         | Where to look                                  |
| ------------------------------- | ---------------------------------------------- |
| Enable/disable features         | `src/config/config.json`                       |
| Access configuration at runtime | `src/config/store.ts`                          |
| CometChat credentials           | `src/utils/AppConstants.tsx`                   |
| Theme colors & styles           | `App.tsx` (theme provider)                     |
| Custom fonts                    | `src/assets/fonts/`, platform font directories |
| Navigation structure            | `src/navigation/`                              |
| Chat UI components              | `src/components/conversations/`                |
| Call UI components              | `src/components/calls/`                        |
| User management UI              | `src/components/users/`                        |
| Group management UI             | `src/components/groups/`                       |

<Note>
  Prefer using `config.json` for feature toggles and the theme provider in `App.tsx` for styling. For extensive changes, create new components rather than modifying core files directly.
</Note>

***

## Next Steps

<CardGroup>
  <Card title="UI Kit Builder Settings" href="/chat-builder/react-native/builder-settings">
    Configure feature toggles and behavior.
  </Card>

  <Card title="Customizations" href="/chat-builder/react-native/builder-customisations">
    Modify component props, styling, and behavior.
  </Card>

  <Card title="Theming" href="/ui-kit/react-native/theme">
    Customize colors, typography, and styling.
  </Card>

  <Card title="Components" href="/ui-kit/react-native/components-overview">
    Explore available UI components.
  </Card>
</CardGroup>


# UI Kit Builder Settings
Source: https://www.cometchat.com/docs/chat-builder/react-native/builder-settings

Comprehensive reference for all Builder configuration options in the React Native UI Kit Builder.

The Builder configuration controls everything the React Native UI Kit Builder renders—messaging, AI helpers, calls, layout, theming, and more. This configuration is stored in `config.json` and managed through the Zustand store.

<Info>
  **For developers customizing their chat UI**: The `config.json` file contains all your feature toggles, layout settings, and styling configuration. Edit this file or use the QR code scanner to update settings dynamically. See the [Integration Guide](/docs/chat-builder/react-native/integration) for setup.
</Info>

## Top-level Structure

The configuration JSON follows this structure:

```json theme={null}
{
  "builderId": "unique-builder-id",
  "settings": {
    "chatFeatures": {
      "coreMessagingExperience": { /* Boolean settings */ },
      "deeperUserEngagement": { /* Boolean settings */ },
      "aiUserCopilot": { /* Boolean settings */ },
      "userManagement": { /* Boolean settings */ },
      "groupManagement": { /* Boolean settings */ },
      "moderatorControls": { /* Boolean settings */ },
      "privateMessagingWithinGroups": { /* Boolean settings */ },
      "inAppSounds": { /* Boolean settings */ }
    },
    "callFeatures": {
      "voiceAndVideoCalling": { /* Boolean settings */ }
    },
    "layout": { /* Layout settings */ },
    "style": {
      "theme": "system",
      "color": { /* Color settings */ },
      "typography": { /* Typography settings */ }
    }
  }
}
```

***

<Tip>
  All boolean settings follow the same pattern: `true` enables the feature and shows its UI elements, `false` hides them completely.
</Tip>

## 1. Chat Features (`chatFeatures`)

### 1.1 Core Messaging Experience (`coreMessagingExperience`)

Essential messaging features: typing indicators, media sharing, message actions, and presence.

| Setting                          | Type    | What It Does                                                                        |
| -------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `typingIndicator`                | boolean | Shows "typing..." indicator when someone is composing a message                     |
| `threadConversationAndReplies`   | boolean | Enables threaded replies to specific messages, creating nested conversation threads |
| `photosSharing`                  | boolean | Allows users to share images from device or camera                                  |
| `videoSharing`                   | boolean | Allows users to share video files                                                   |
| `audioSharing`                   | boolean | Allows users to share audio files (mp3, wav, etc.)                                  |
| `fileSharing`                    | boolean | Allows users to share documents (PDF, DOC, etc.)                                    |
| `editMessage`                    | boolean | Lets users modify their sent messages; edited messages show "(edited)" label        |
| `deleteMessage`                  | boolean | Lets users remove their sent messages                                               |
| `messageDeliveryAndReadReceipts` | boolean | Shows delivery (✓) and read (✓✓) status indicators on messages                      |
| `userAndFriendsPresence`         | boolean | Shows online/offline status dot next to user avatars                                |
| `conversationAndAdvancedSearch`  | boolean | Enables search across messages, users, and conversations                            |
| `moderation`                     | boolean | Enables blocked message feedback for messages blocked by moderation rules           |
| `quotedReplies`                  | boolean | Lets users quote a message when replying, showing the original above their response |
| `markAsUnread`                   | boolean | Lets users mark a conversation as unread to revisit later                           |

<Tip>
  Empower users with a seamless chat experience—reply to specific messages with
  quoted replies, mark conversations as unread for later, and search across all
  chats instantly. Learn more about [Core Features](/docs/ui-kit/react-native/core-features).
</Tip>

### 1.2 Deeper User Engagement (`deeperUserEngagement`)

Interactive features: mentions, reactions, polls, voice notes, and collaborative tools.

| Setting                   | Type    | What It Does                                                                                |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `mentions`                | boolean | Lets users @mention specific people in a message to notify them                             |
| `mentionAll`              | boolean | Lets users type @all to notify every member in a group chat                                 |
| `reactions`               | boolean | Lets users add emoji reactions (👍 ❤️ 😂 etc.) to messages                                  |
| `messageTranslation`      | boolean | Translates messages to user's preferred language. Requires Dashboard setup                  |
| `polls`                   | boolean | Lets users create polls with multiple options for group voting. Requires Dashboard setup    |
| `collaborativeWhiteboard` | boolean | Opens a shared whiteboard for real-time drawing and collaboration. Requires Dashboard setup |
| `collaborativeDocument`   | boolean | Creates shared documents for real-time collaborative editing. Requires Dashboard setup      |
| `voiceNotes`              | boolean | Lets users record and send voice messages                                                   |
| `emojis`                  | boolean | Shows emoji picker in composer for browsing and inserting emojis                            |
| `stickers`                | boolean | Lets users send sticker images from available packs. Requires Dashboard setup               |
| `userInfo`                | boolean | Lets users tap on another user's avatar to view their profile                               |
| `groupInfo`               | boolean | Lets users tap on group header to view group details and member list                        |

<Tip>
  Configure these features based on your app's requirements. Learn more about
  [Extensions](/docs/ui-kit/react-native/extensions).
</Tip>

### 1.3 AI User Copilot (`aiUserCopilot`)

AI-powered features to help users start and navigate conversations.

| Setting               | Type    | What It Does                              |
| --------------------- | ------- | ----------------------------------------- |
| `conversationStarter` | boolean | Shows AI-suggested opening messages       |
| `conversationSummary` | boolean | Generates AI-powered conversation summary |
| `smartReply`          | boolean | Shows AI-suggested quick reply options    |

<Tip>
  AI User Copilot features require an OpenAI API key. Configure it in the [CometChat Dashboard](https://app.cometchat.com) under **AI > Settings**.
</Tip>

### 1.4 User Management (`userManagement`)

| Setting       | Type    | What It Does                        |
| ------------- | ------- | ----------------------------------- |
| `friendsOnly` | boolean | Restricts chat to friends list only |

### 1.5 Group Management (`groupManagement`)

| Setting              | Type    | What It Does                       |
| -------------------- | ------- | ---------------------------------- |
| `createGroup`        | boolean | Lets users create new groups       |
| `addMembersToGroups` | boolean | Lets admins invite users to groups |
| `joinLeaveGroup`     | boolean | Lets users join/leave groups       |
| `deleteGroup`        | boolean | Lets owners delete groups          |
| `viewGroupMembers`   | boolean | Shows member list in group info    |

### 1.6 Moderator Controls (`moderatorControls`)

| Setting                | Type    | What It Does                         |
| ---------------------- | ------- | ------------------------------------ |
| `reportMessage`        | boolean | Lets users flag messages for review  |
| `kickUsers`            | boolean | Lets admins remove users from groups |
| `banUsers`             | boolean | Lets admins permanently ban users    |
| `promoteDemoteMembers` | boolean | Lets owners change member roles      |

### 1.7 Private Messaging Within Groups (`privateMessagingWithinGroups`)

| Setting                            | Type    | What It Does                                  |
| ---------------------------------- | ------- | --------------------------------------------- |
| `sendPrivateMessageToGroupMembers` | boolean | Lets users start 1:1 chats with group members |

### 1.8 In-App Sounds (`inAppSounds`)

| Setting                | Type    | What It Does                      |
| ---------------------- | ------- | --------------------------------- |
| `incomingMessageSound` | boolean | Plays sound for new messages      |
| `outgoingMessageSound` | boolean | Plays sound when sending messages |

***

## 2. Call Features (`callFeatures`)

### 2.1 Voice and Video Calling (`voiceAndVideoCalling`)

| Setting                | Type    | What It Does                                                                |
| ---------------------- | ------- | --------------------------------------------------------------------------- |
| `oneOnOneVoiceCalling` | boolean | Shows phone icon in 1:1 chat header for starting voice calls                |
| `oneOnOneVideoCalling` | boolean | Shows video camera icon in 1:1 chat header for starting video calls         |
| `groupVideoConference` | boolean | Shows video camera icon in group chat header for starting group video calls |
| `groupVoiceConference` | boolean | Shows phone icon in group chat header for starting group voice calls        |

<Tip>
  Learn more about [Call Features](/docs/ui-kit/react-native/call-features).
</Tip>

***

## 3. Layout (`layout`)

| Setting       | Type      | What It Does                                                                                           |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `withSideBar` | boolean   | Shows navigation sidebar with tabs (Chats, Calls, Users, Groups)                                       |
| `tabs`        | string\[] | Array of tabs to show: `'chats'`, `'calls'`, `'users'`, `'groups'`                                     |
| `chatType`    | string    | Default conversation type on load: `'user'` for 1:1 chats, `'group'` for group chats, `'both'` for all |

<Tip>
  Set `withSideBar: false` for embedded chat widgets or single-conversation
  views where navigation isn't needed.
</Tip>

***

## 4. Style (`style`)

### 4.1 Theme

| Setting | Type   | What It Does                                                 |
| ------- | ------ | ------------------------------------------------------------ |
| `theme` | string | Controls light/dark mode: `'light'`, `'dark'`, or `'system'` |

### 4.2 Colors

| Setting              | Type   | What It Does                                     |
| -------------------- | ------ | ------------------------------------------------ |
| `brandColor`         | string | Primary accent color (hex). Example: `"#6852D6"` |
| `primaryTextLight`   | string | Main text color in light mode                    |
| `primaryTextDark`    | string | Main text color in dark mode                     |
| `secondaryTextLight` | string | Secondary text color in light mode               |
| `secondaryTextDark`  | string | Secondary text color in dark mode                |

### 4.3 Typography

| Setting | Type   | What It Does                                                          |
| ------- | ------ | --------------------------------------------------------------------- |
| `font`  | string | Font family: `'roboto'`, `'arial'`, `'inter'`, or `'times new roman'` |
| `size`  | string | Text size: `'default'`, `'compact'`, or `'comfortable'`               |

***

## Complete Settings Example

```json theme={null}
{
  "builderId": "your-builder-id",
  "settings": {
    "chatFeatures": {
      "coreMessagingExperience": {
        "typingIndicator": true,
        "threadConversationAndReplies": true,
        "photosSharing": true,
        "videoSharing": true,
        "audioSharing": true,
        "fileSharing": true,
        "editMessage": true,
        "deleteMessage": true,
        "messageDeliveryAndReadReceipts": true,
        "userAndFriendsPresence": true,
        "conversationAndAdvancedSearch": true,
        "moderation": true,
        "quotedReplies": false,
        "markAsUnread": false
      },
      "deeperUserEngagement": {
        "mentions": true,
        "mentionAll": true,
        "reactions": true,
        "messageTranslation": true,
        "polls": true,
        "collaborativeWhiteboard": true,
        "collaborativeDocument": true,
        "voiceNotes": true,
        "emojis": true,
        "stickers": true,
        "userInfo": true,
        "groupInfo": true
      },
      "aiUserCopilot": {
        "conversationStarter": false,
        "conversationSummary": false,
        "smartReply": false
      },
      "userManagement": {
        "friendsOnly": false
      },
      "groupManagement": {
        "createGroup": true,
        "addMembersToGroups": true,
        "joinLeaveGroup": true,
        "deleteGroup": true,
        "viewGroupMembers": true
      },
      "moderatorControls": {
        "kickUsers": true,
        "banUsers": true,
        "promoteDemoteMembers": true,
        "reportMessage": true
      },
      "privateMessagingWithinGroups": {
        "sendPrivateMessageToGroupMembers": true
      },
      "inAppSounds": {
        "incomingMessageSound": true,
        "outgoingMessageSound": true
      }
    },
    "callFeatures": {
      "voiceAndVideoCalling": {
        "oneOnOneVoiceCalling": true,
        "oneOnOneVideoCalling": true,
        "groupVideoConference": true,
        "groupVoiceConference": true
      }
    },
    "layout": {
      "withSideBar": true,
      "tabs": ["chats", "calls", "users", "groups"],
      "chatType": "both"
    },
    "style": {
      "theme": "system",
      "color": {
        "brandColor": "#6852D6",
        "primaryTextLight": "#141414",
        "primaryTextDark": "#FFFFFF",
        "secondaryTextLight": "#727272",
        "secondaryTextDark": "#989898"
      },
      "typography": {
        "font": "roboto",
        "size": "default"
      }
    }
  }
}
```

***

## Accessing Settings in Code

Use the Zustand store to access settings in your React Native components:

```tsx theme={null}
import { useConfig } from './src/config/store';

const MyComponent = () => {
  // Access style settings
  const styleConfig = useConfig((state) => state.settings.style);
  
  // Access chat features
  const chatFeatures = useConfig((state) => state.settings.chatFeatures);
  
  // Check if a feature is enabled
  if (chatFeatures.coreMessagingExperience.photosSharing) {
    // Enable photo sharing functionality
  }
  
  // Access layout settings
  const layout = useConfig((state) => state.settings.layout);
  const tabs = layout.tabs;
  
  return (/* ... */);
};
```

***

## Dashboard Feature Requirements

Some features require additional configuration in the [CometChat Dashboard](https://app.cometchat.com):

<Note>
  **AI Copilot Features** (Conversation Starter, Conversation Summary, Smart Reply)

  * Requires an OpenAI API key configured in the Dashboard under **AI > Settings**
</Note>

<Note>
  **Stickers, Polls, Collaborative Tools, Message Translation**

  * Requires the respective extensions to be enabled in the Dashboard under **Extensions**
</Note>

<Note>
  **Moderation**

  * Requires moderation rules to be configured in the Dashboard under **Moderation > Rules**
</Note>


# UI Kit Builder Integration
Source: https://www.cometchat.com/docs/chat-builder/react-native/integration

Step-by-step guide to integrating CometChat's UI Kit Builder into your React Native application.

UI Kit Builder for React Native streamlines how you configure CometChat's React Native UI Kit. Build themes, toggles, and layouts visually, export the settings JSON, and keep your production app synced by reading the same configuration at runtime.

<Frame>
  <img />
</Frame>

***

## Prerequisites

Before getting started, make sure you have:

* **Node.js** 18 or higher
* **React Native** 0.77+ (CLI or Expo bare workflow)
* **iOS tooling**: macOS with Xcode 14+, CocoaPods, iOS 12+ simulator/device
* **Android tooling**: Android Studio with SDK 33+, Android 5.0+ device/emulator
* **Internet connection** (required for CometChat services)
* An active CometChat app (App ID, Auth Key, and Region)

***

## Complete Integration Workflow

1. **Design Your Chat Experience** - Use the UI Kit Builder to customize layouts, features, and styling.
2. **Review and Export** - Review which features will be enabled in your Dashboard, toggle them on/off, and download the generated code package.
3. **Preview Customizations** - Optionally, preview the chat experience before integrating it into your project.
4. **Integration** - Integrate into your existing application using either the Sample App or Configuration Store method.
5. **Customize Further** - Explore advanced customization options to tailor the chat experience.

***

## Launch the UI Kit Builder

1. Log in to your [CometChat Dashboard](https://app.cometchat.com).
2. Select your application from the list.
3. Navigate to **Integrate** → **React Native** → **Launch UI Kit Builder**.

***

## Integration Options

Choose one of the following integration methods based on your needs:

| Option                                   | Best For                                                       | Complexity |
| ---------------------------------------- | -------------------------------------------------------------- | ---------- |
| **Run Sample App**                       | Quick preview and testing of Builder configurations            | Easy       |
| **Integrate Config Store** (Recommended) | Production apps where you want full control over customization | Medium     |

***

## Option 1: Run the CometChat UIKit Builder Sample App

### Step 1: Download & Install

```bash theme={null}
git clone https://github.com/cometchat-team/uikit-builder-app-react-native.git
cd uikit-builder-app-react-native
npm install
```

### Step 2: iOS Dependencies

```bash theme={null}
cd ios
pod install
cd ..
```

### Step 3: Configure CometChat Credentials

Edit `src/utils/AppConstants.tsx`:

```ts theme={null}
export const AppConstants = {
  appId: 'YOUR_APP_ID',
  authKey: 'YOUR_AUTH_KEY',
  region: 'YOUR_REGION',
};
```

### Step 4: Run the Builder Sample

```bash theme={null}
# Start Metro
npm start

# Launch iOS or Android
npm run ios
npm run android
```

With the sample running you can scan QR codes, import JSON, and preview Builder-generated layouts before you copy them into another project.

***

## Option 2: Integrate Builder Configuration into Your React Native App

This method gives you full control over customization and is recommended for production apps.

### Step 1: Install Shared Dependencies

```bash theme={null}
npm install zustand @react-native-async-storage/async-storage
```

### Step 2: Copy Configuration Files

From the sample project, copy these essential files to your existing React Native project:

* **Source:** `src/config/store.ts` (Zustand store that manages Builder settings)
* **Source:** `src/config/config.json` (default configuration template)
* **Destination:** `yourProject/src/config/`

### Step 3: Wire the Builder Theme into UI Kit

```tsx theme={null}
import React from 'react';
import { CometChatThemeProvider } from '@cometchat/chat-uikit-react-native';
import { useConfig } from './src/config/store';

const App = () => {
  const styleConfig = useConfig((state) => state.settings.style);

  const theme = {
    light: {
      color: {
        primary: styleConfig.color.brandColor,
        textPrimary: styleConfig.color.primaryTextLight,
        textSecondary: styleConfig.color.secondaryTextLight,
      },
    },
    dark: {
      color: {
        primary: styleConfig.color.brandColor,
        textPrimary: styleConfig.color.primaryTextDark,
        textSecondary: styleConfig.color.secondaryTextDark,
      },
    },
  };

  return (
    <CometChatThemeProvider theme={theme}>
      {/* Existing app components */}
    </CometChatThemeProvider>
  );
};
```

Use the Zustand store everywhere you need runtime access to Builder settings (feature toggles, layout preferences, or styling).

### Step 4: Respect Feature Toggles in UI Kit Components

Access feature configurations from the store to control which features are enabled:

* Chat features (typing indicator, threads, mentions, reactions, etc.)
* Call features (1:1 voice, group video, lobby)
* Layout and discovery (tabs, sidebar, chat type)

These booleans live under `settings.chatFeatures`, `settings.callFeatures`, and `settings.layout` inside the Builder JSON, so you can decide which CometChat components to render or hide per experience.

***

## Important Guidelines for Changes

<Note>
  **Functional Changes:**
  For enabling or disabling features and adjusting configurations, update the `config.json` file or modify the Zustand store. This controls all feature flags and configuration constants.
</Note>

<Note>
  **UI and Theme-related Changes:**
  For any updates related to UI, such as colors, fonts, and styles, modify the theme object passed to `CometChatThemeProvider`.
</Note>

***

## Enable Features in CometChat Dashboard

If your app needs any of these features, enable them from your [Dashboard](https://app.cometchat.com):

* Stickers
* Polls
* Collaborative whiteboard
* Collaborative document
* Message translation
* AI User Copilot: Conversation starter, Conversation summary, Smart reply

**How to enable:**

<Frame>
  <img />
</Frame>

1. Log in to the Dashboard.
2. Select your app.
3. Navigate to **Chat → Features**.
4. Toggle ON the required features and Save.

***

## What You Can Configure

Toggle these features on or off directly in the UI Kit Builder. For a full reference of each setting, see [UI Kit Builder Settings](/docs/chat-builder/react-native/builder-settings).

### Chat Features

| Category                        | Includes                                                                                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Core Messaging Experience       | Typing indicators, threads, media sharing (photos, video, audio, files), edit & delete messages, read receipts, search, quoted replies, mark as unread |
| Deeper User Engagement          | Mentions, @all mentions, reactions, message translation, polls, collaborative whiteboard & document, voice notes, emojis, stickers, user & group info  |
| AI User Copilot                 | Conversation starters, conversation summaries, smart replies                                                                                           |
| User Management                 | Friends-only mode                                                                                                                                      |
| Group Management                | Create groups, add members, join/leave, delete groups, view members                                                                                    |
| Moderation                      | Content moderation, report messages, kick/ban users, promote/demote members                                                                            |
| Private Messaging Within Groups | Direct messages between group members                                                                                                                  |
| In-App Sounds                   | Incoming & outgoing message sounds                                                                                                                     |

### Call Features

| Category              | Includes                                                                             |
| --------------------- | ------------------------------------------------------------------------------------ |
| Voice & Video Calling | 1:1 voice calling, 1:1 video calling, group voice conference, group video conference |

### Layout

| Category | Includes                                |
| -------- | --------------------------------------- |
| Sidebar  | With Sidebar or Without Sidebar mode    |
| Tabs     | Conversations, Call Logs, Users, Groups |

### Theming

| Category   | Includes                                                    |
| ---------- | ----------------------------------------------------------- |
| Theme      | System, Light, or Dark mode                                 |
| Colors     | Brand color, primary & secondary text colors (light & dark) |
| Typography | Font family, text sizing (default, compact, comfortable)    |

***

## Troubleshooting

### Metro or Gradle Errors

* Ensure Node 18+, React Native 0.77+, and the correct Android/iOS toolchains are installed
* Clean and rebuild: `npm start --reset-cache`

### Plugin/Config Not Loading

* Verify `AppConstants.tsx` values are correct
* Check network connectivity when launching the Builder

### QR Code Parsing Issues

* Validate that the JSON matches the configuration schema
* Malformed objects will be ignored

### UI Kit Mismatches

* Confirm both the Builder sample and your production app use the same version of `@cometchat/chat-uikit-react-native`

***

## Next Steps

<CardGroup>
  <Card title="Builder Settings" href="/chat-builder/react-native/builder-settings">
    Understand the settings file and feature toggles.
  </Card>

  <Card title="Customizations" href="/chat-builder/react-native/builder-customisations">
    Adjust component props, behavior, and UI elements.
  </Card>

  <Card title="Directory Structure" href="/chat-builder/react-native/builder-dir-structure">
    See how the exported code is organized.
  </Card>

  <Card title="UI Kit Theme" href="/ui-kit/react-native/theme">
    Customize colors, typography, and styling to match your brand.
  </Card>
</CardGroup>


# CometChat UI Kit Builder For React Native
Source: https://www.cometchat.com/docs/chat-builder/react-native/overview

CometChat UI Kit Builder for React Native is a visual development tool that helps you design and configure chat experiences for React Native applications without building the interface from scratch.

It provides a set of prebuilt, production-ready messaging components backed by CometChat's real-time infrastructure.

With CometChat UI Kit Builder, you can:

* Configure chat and calling features
* Apply theming and layout options
* Export React Native-ready code via QR code scanning

The exported UI connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling.

## What You Can Configure

Toggle these features on or off directly in the UI Kit Builder. For a full reference of each setting, see [UI Kit Builder Settings](/docs/chat-builder/react-native/builder-settings).

### Chat Features

| Category                        | Includes                                                                                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Core Messaging Experience       | Typing indicators, threads, media sharing (photos, video, audio, files), edit & delete messages, read receipts, search, quoted replies, mark as unread |
| Deeper User Engagement          | Mentions, @all mentions, reactions, message translation, polls, collaborative whiteboard & document, voice notes, emojis, stickers, user & group info  |
| AI User Copilot                 | Conversation starters, conversation summaries, smart replies                                                                                           |
| User Management                 | Friends-only mode                                                                                                                                      |
| Group Management                | Create groups, add members, join/leave, delete groups, view members                                                                                    |
| Moderation                      | Content moderation, report messages, kick/ban users, promote/demote members                                                                            |
| Private Messaging Within Groups | Direct messages between group members                                                                                                                  |
| In-App Sounds                   | Incoming & outgoing message sounds                                                                                                                     |

### Call Features

| Category              | Includes                                                                             |
| --------------------- | ------------------------------------------------------------------------------------ |
| Voice & Video Calling | 1:1 voice calling, 1:1 video calling, group voice conference, group video conference |

### Layout

| Category | Includes                                |
| -------- | --------------------------------------- |
| Sidebar  | With Sidebar or Without Sidebar mode    |
| Tabs     | Conversations, Call Logs, Users, Groups |

### Theming

| Category   | Includes                                                    |
| ---------- | ----------------------------------------------------------- |
| Theme      | System, Light, or Dark mode                                 |
| Colors     | Brand color, primary & secondary text colors (light & dark) |
| Typography | Font family, text sizing (default, compact, comfortable)    |

***

## How to Use UI Kit Builder

### 1. Design

Configure your chat layout, toggle features, and pick a theme using the UI Kit Builder.

<Frame>
  <img />
</Frame>

### 2. Export

Scan a QR code or export the configuration JSON to apply your settings to your React Native app.

### 3. Integrate

Drop the configuration into your React Native project, add your CometChat credentials, and run the app. See the [Integration Guide](/docs/chat-builder/react-native/integration) for full steps.

***

## Try It Locally

<CardGroup>
  <Card title="React Native Builder Source" icon="github" href="https://github.com/cometchat-team/uikit-builder-app-react-native">
    Clone the sample, run it on iOS/Android, and experiment with QR-based configurations.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup>
  <Card title="Integration" href="/chat-builder/react-native/integration">
    Step-by-step guide to integrate the UI Kit Builder.
  </Card>

  <Card title="Builder Settings" href="/chat-builder/react-native/builder-settings">
    Understand the settings file and feature toggles.
  </Card>

  <Card title="Customizations" href="/chat-builder/react-native/builder-customisations">
    Adjust component props, behavior, and UI elements.
  </Card>

  <Card title="Directory Structure" href="/chat-builder/react-native/builder-dir-structure">
    See how the exported code is organized.
  </Card>
</CardGroup>

***

## Helpful Resources

<CardGroup>
  <Card title="React Native UI Kit Docs" href="https://www.cometchat.com/docs/ui-kit/react-native/5.0/getting-started">
    Official UI Kit documentation with component APIs, theming, and guides.
  </Card>

  <Card title="Support Portal" href="https://help.cometchat.com/hc/en-us/requests/new">
    Reach CometChat support for troubleshooting and production issues.
  </Card>

  <Card title="Community & Issues" href="https://github.com/cometchat-team/uikit-builder-app-react-native/issues">
    File bugs, request features, or learn from community fixes.
  </Card>
</CardGroup>

***

## Need Help?

* Developer Community: [https://community.cometchat.com/](https://community.cometchat.com/)
* Dashboard & Live Support: [https://app.cometchat.com](https://app.cometchat.com)
* UI Kit questions: [https://www.cometchat.com/docs/ui-kit/react-native/5.0/getting-started](https://www.cometchat.com/docs/ui-kit/react-native/5.0/getting-started)


# Smart Chat Features
Source: https://www.cometchat.com/docs/ui-kit/react/ai-features

AI-powered features in CometChat's React UI Kit: Conversation Starter, Smart Replies, and Conversation Summary.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                                                                                                                                                                                    |
  | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Package        | `@cometchat/chat-uikit-react`                                                                                                                                                                                                                                                                                            |
  | Required setup | Wrap app in `CometChatProvider` with valid credentials + AI features enabled in [CometChat Dashboard](/docs/fundamentals/ai-user-copilot/overview)                                                                                                                                                                            |
  | AI features    | Conversation Starter, Smart Replies, Conversation Summary                                                                                                                                                                                                                                                                |
  | Key components | `CometChatMessageList` → [Message List](/docs/ui-kit/react/components/message-list) (Conversation Starter), `CometChatMessageComposer` → [Message Composer](/docs/ui-kit/react/components/message-composer) (Smart Replies, Summary), `CometChatAIAssistantChat` → [AI Assistant Chat](/docs/ui-kit/react/components/ai-assistant-chat) |
  | Activation     | Enable each AI feature from the CometChat Dashboard — UI Kit auto-integrates them, no additional code required                                                                                                                                                                                                           |
</Accordion>

## Overview

CometChat AI features enhance user interaction by providing contextual suggestions and summaries. Each feature is activated from the Dashboard and auto-integrates into UI Kit components.

## Smart Chat Features

### Conversation Starter

Displays AI-generated opening lines when a user starts a new chat. See [Conversation Starter](/docs/fundamentals/ai-user-copilot/conversation-starter).

Auto-integrates into [MessageList](/docs/ui-kit/react/components/message-list) when activated.

<Frame>
  <img />
</Frame>

### Smart Replies

AI-generated response suggestions based on conversation context. See [Smart Replies](/docs/fundamentals/ai-user-copilot/smart-replies).

Auto-integrates into the Action Sheet of [MessageComposer](/docs/ui-kit/react/components/message-composer) when activated.

<Frame>
  <img />
</Frame>

### Conversation Summary

AI-generated recap of long conversations. See [Conversation Summary](/docs/fundamentals/ai-user-copilot/conversation-summary).

Auto-integrates into the Action Sheet of [MessageComposer](/docs/ui-kit/react/components/message-composer) when activated.

<Frame>
  <img />
</Frame>

## Next Steps

<CardGroup>
  <Card title="AI Assistant Chat" icon="robot" href="/ui-kit/react/components/ai-assistant-chat">
    AI-powered assistant component
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/react/components/message-list">
    Customize the message list where AI features appear
  </Card>

  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/react/components/message-composer">
    Customize the composer with Smart Replies and Summary
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/react/core-features">
    Core chat features like messaging and reactions
  </Card>
</CardGroup>


# Conversation List + Message View
Source: https://www.cometchat.com/docs/ui-kit/react/astro-conversation

Build a two-panel conversation list + message view layout in Astro with CometChat UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                  |
  | ------------ | ------------------------------------------------------------------------------------------------------ |
  | Package      | `@cometchat/chat-uikit-react`                                                                          |
  | Framework    | Astro                                                                                                  |
  | Components   | `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Two-panel — conversation list (left) + message view (right)                                            |
  | Prerequisite | Complete [Astro Integration](/docs/ui-kit/react/integration-astro) first                                    |
  | SSR          | React island with `client:only="react"` directive                                                      |
  | Pattern      | WhatsApp Web, Slack, Microsoft Teams                                                                   |
</Accordion>

This guide builds a two-panel chat layout — conversation list on the left, messages on the right. Users click a conversation to open it.

This assumes you've already completed [Astro Integration](/docs/ui-kit/react/integration-astro) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three sections working together:

1. **Sidebar (conversation list)** — shows all active conversations (users and groups)
2. **Message view** — displays chat messages for the selected conversation in real time
3. **Message composer** — text input with support for media, emojis, and reactions

***

## Full Code

Create a React island component with the chat UI, then render it in an Astro page with `client:only="react"`.

```tsx title="src/components/ConversationChat.tsx" theme={null}
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
  CometChatProvider,
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

export default function ConversationChat() {
  const [ready, setReady] = useState(false);
  const [selectedUser, setSelectedUser] = useState<CometChat.User | undefined>(undefined);
  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group | undefined>(undefined);

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      setReady(true);
    });
  }, []);

  if (!ready) return <div>Loading chat...</div>;

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setSelectedUser(entity as CometChat.User);
      setSelectedGroup(undefined);
    } else {
      setSelectedGroup(entity as CometChat.Group);
      setSelectedUser(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div style={{
        display: "flex",
        height: "100vh",
        width: "100%",
      }}>
        <div style={{
          width: 360,
          height: "100%",
          borderRight: "1px solid #eee",
          overflow: "hidden",
          display: "flex",
          flexDirection: "column",
        }}>
          <CometChatConversations onItemClick={handleConversationClick} />
        </div>

        {selectedUser || selectedGroup ? (
          <div style={{
            flex: 1,
            height: "100%",
            display: "flex",
            flexDirection: "column",
          }}>
            <CometChatMessageHeader user={selectedUser} group={selectedGroup} />
            <CometChatMessageList user={selectedUser} group={selectedGroup} />
            <CometChatMessageComposer user={selectedUser} group={selectedGroup} />
          </div>
        ) : (
          <div style={{
            flex: 1,
            display: "flex",
            justifyContent: "center",
            alignItems: "center",
            background: "#f5f5f5",
            color: "#727272",
            font: "400 14px Roboto, sans-serif",
          }}>
            Select a conversation to start chatting
          </div>
        )}
      </div>
    </CometChatProvider>
  );
}
```

```astro title="src/pages/chat.astro" theme={null}
---
import ConversationChat from '../components/ConversationChat.tsx';
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Chat</title>
  </head>
  <body style="margin: 0;">
    <ConversationChat client:only="react" />
  </body>
</html>
```

***

## How It Works

1. **`client:only="react"`** tells Astro to skip server-rendering and hydrate the component entirely on the client. This is required because CometChat uses browser APIs.
2. **React island** — the CometChat UI lives in a self-contained React component. Astro handles the page shell, React handles the interactive chat.
3. **CometChatProvider** wraps the entire tree — it supplies theme, locale, and event context to all CometChat components.
4. **CometChatConversations** renders the sidebar list. When a user clicks a conversation, `onItemClick` fires with the `Conversation` object.
5. **handleConversationClick** extracts the `User` or `Group` from the conversation and stores it in state.
6. **Message components** (`MessageHeader`, `MessageList`, `MessageComposer`) receive either `user` or `group` as a prop — never both at the same time.

***

## Run

```bash theme={null}
npm run dev
```

Open `http://localhost:4321/chat`. You should see the conversation list on the left. Click any conversation to load messages on the right.

***

## Next Steps

<CardGroup>
  <Card title="One-to-One / Group Chat" icon="message" href="/ui-kit/react/astro-one-to-one-chat">
    Single chat window without a sidebar
  </Card>

  <Card title="Tab-Based Chat" icon="table-columns" href="/ui-kit/react/astro-tab-based-chat">
    Tabbed navigation with Chats, Calls, Users
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and styles
  </Card>
</CardGroup>


# One-to-One / Group Chat
Source: https://www.cometchat.com/docs/ui-kit/react/astro-one-to-one-chat

Build a single chat window for one-to-one or group messaging in Astro with CometChat UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                        |
  | ------------ | ---------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react`                                                |
  | Framework    | Astro                                                                        |
  | Components   | `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Single chat window — no sidebar, no conversation list                        |
  | Prerequisite | Complete [Astro Integration](/docs/ui-kit/react/integration-astro) first          |
  | SSR          | React island with `client:only="react"` directive                            |
  | Pattern      | Support chat, embedded widgets, focused messaging                            |
</Accordion>

This guide builds a single chat window — no sidebar, no conversation list. Users go directly into a one-to-one or group chat. Good for support chat, embedded widgets, or any focused messaging experience.

This assumes you've already completed [Astro Integration](/docs/ui-kit/react/integration-astro) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three components stacked vertically:

1. **Chat header** — displays recipient name, avatar, online status, and optional call buttons
2. **Message list** — real-time chat history with scrolling
3. **Message composer** — text input with media, emojis, and reactions

***

## Full Code

Create a React island component with the chat UI, then render it in an Astro page with `client:only="react"`.

```tsx title="src/components/DirectChat.tsx" theme={null}
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
  CometChatProvider,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

const RECIPIENT_UID = "cometchat-uid-2"; // Replace with the UID you want to chat with

export default function DirectChat() {
  const [ready, setReady] = useState(false);
  const [chatUser, setChatUser] = useState<CometChat.User | undefined>(undefined);

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      const user = await CometChat.getUser(RECIPIENT_UID);
      setChatUser(user);
      setReady(true);
    });
  }, []);

  if (!ready || !chatUser) return <div>Loading chat...</div>;

  return (
    <CometChatProvider>
      <div style={{ display: "flex", flexDirection: "column", height: "100vh", width: "100%" }}>
        <CometChatMessageHeader user={chatUser} />
        <CometChatMessageList user={chatUser} />
        <CometChatMessageComposer user={chatUser} />
      </div>
    </CometChatProvider>
  );
}
```

```astro title="src/pages/chat.astro" theme={null}
---
import DirectChat from '../components/DirectChat.tsx';
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Chat</title>
  </head>
  <body style="margin: 0;">
    <DirectChat client:only="react" />
  </body>
</html>
```

Key points:

* `client:only="react"` ensures the component only runs in the browser — no server-side rendering.
* `CometChat.getUser(UID)` fetches the full user object from the SDK — you need a real user object, not a manually constructed one.
* Pass either `user` or `group` to the message components, never both.
* The `RECIPIENT_UID` should be a user that exists in your CometChat app. Use one of the pre-created test UIDs: `cometchat-uid-1` through `cometchat-uid-5`.

***

## Switching to Group Chat

To load a group chat instead of one-to-one, fetch a `Group` object and pass it to the message components:

```tsx title="src/components/DirectChat.tsx" theme={null}
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
  CometChatProvider,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

const GROUP_ID = "cometchat-guid-1"; // Replace with your Group ID

export default function DirectChat() {
  const [ready, setReady] = useState(false);
  const [chatGroup, setChatGroup] = useState<CometChat.Group | undefined>(undefined);

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      const group = await CometChat.getGroup(GROUP_ID);
      setChatGroup(group);
      setReady(true);
    });
  }, []);

  if (!ready || !chatGroup) return <div>Loading chat...</div>;

  return (
    <CometChatProvider>
      <div style={{ display: "flex", flexDirection: "column", height: "100vh", width: "100%" }}>
        <CometChatMessageHeader group={chatGroup} />
        <CometChatMessageList group={chatGroup} />
        <CometChatMessageComposer group={chatGroup} />
      </div>
    </CometChatProvider>
  );
}
```

The only difference: use `CometChat.getGroup(GUID)` instead of `CometChat.getUser(UID)`, and pass `group` instead of `user`.

***

## Run

```bash theme={null}
npm run dev
```

Open `http://localhost:4321/chat`. You should see the chat window load with the conversation for the UID or GUID you set.

***

## Next Steps

<CardGroup>
  <Card title="Conversation List + Messages" icon="comments" href="/ui-kit/react/astro-conversation">
    Two-panel layout with a sidebar
  </Card>

  <Card title="Tab-Based Chat" icon="table-columns" href="/ui-kit/react/astro-tab-based-chat">
    Tabbed navigation with Chats, Calls, Users
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>
</CardGroup>


# Tab-Based Chat
Source: https://www.cometchat.com/docs/ui-kit/react/astro-tab-based-chat

Build a tab-based chat interface with Chat, Call Logs, and Users tabs in Astro.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                                                         |
  | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react`                                                                                                                 |
  | Framework    | Astro                                                                                                                                         |
  | Components   | `CometChatConversations`, `CometChatCallLogs`, `CometChatUsers`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Tabbed sidebar (Chat, Calls, Users) + message view                                                                                            |
  | Prerequisite | Complete [Astro Integration](/docs/ui-kit/react/integration-astro) first                                                                           |
  | SSR          | React island with `client:only="react"` directive                                                                                             |
  | Pattern      | Full-featured messaging app with multiple sections                                                                                            |
</Accordion>

This guide builds a tabbed messaging UI — Chat, Calls, and Users tabs in the sidebar, with a message view on the right. Good for full-featured apps that need more than just conversations.

This assumes you've already completed [Astro Integration](/docs/ui-kit/react/integration-astro) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three sections working together:

1. **Tab bar** — switches between Chat, Calls, and Users
2. **Sidebar** — renders the list for the active tab
3. **Message view** — header + messages + composer for the selected item

***

## Full Code

Create a React island component with the tabbed UI, then render it in an Astro page with `client:only="react"`.

```tsx title="src/components/TabbedChat.tsx" theme={null}
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
  CometChatProvider,
  CometChatConversations,
  CometChatUsers,
  CometChatCallLogs,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

type Tab = "chat" | "calls" | "users";

export default function TabbedChat() {
  const [ready, setReady] = useState(false);
  const [activeTab, setActiveTab] = useState<Tab>("chat");
  const [selectedUser, setSelectedUser] = useState<CometChat.User | undefined>(undefined);
  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group | undefined>(undefined);

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      setReady(true);
    });
  }, []);

  if (!ready) return <div>Loading chat...</div>;

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setSelectedUser(entity as CometChat.User);
      setSelectedGroup(undefined);
    } else {
      setSelectedGroup(entity as CometChat.Group);
      setSelectedUser(undefined);
    }
  };

  const handleUserClick = (user: CometChat.User) => {
    setSelectedUser(user);
    setSelectedGroup(undefined);
  };

  const handleCallClick = (call: any) => {
    const initiator = call.getInitiator();
    const receiver = call.getReceiver();

    // Determine the other party in the call
    if (receiver instanceof CometChat.User) {
      setSelectedUser(receiver);
      setSelectedGroup(undefined);
    } else if (receiver instanceof CometChat.Group) {
      setSelectedUser(undefined);
      setSelectedGroup(receiver);
    } else if (initiator instanceof CometChat.User) {
      setSelectedUser(initiator);
      setSelectedGroup(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div style={{ display: "flex", height: "100vh", width: "100%" }}>
        <div style={{
          width: 360,
          height: "100%",
          display: "flex",
          flexDirection: "column",
          borderRight: "1px solid #eee",
        }}>
          <div style={{
            display: "flex",
            borderBottom: "1px solid #eee",
            background: "#fff",
          }}>
            <button
              style={{
                flex: 1,
                padding: "12px 0",
                border: "none",
                background: "none",
                cursor: "pointer",
                fontWeight: 500,
                fontSize: 14,
                color: activeTab === "chat" ? "#6851d6" : "#727272",
                borderBottom: activeTab === "chat" ? "2px solid #6851d6" : "2px solid transparent",
              }}
              onClick={() => setActiveTab("chat")}
            >
              Chats
            </button>
            <button
              style={{
                flex: 1,
                padding: "12px 0",
                border: "none",
                background: "none",
                cursor: "pointer",
                fontWeight: 500,
                fontSize: 14,
                color: activeTab === "calls" ? "#6851d6" : "#727272",
                borderBottom: activeTab === "calls" ? "2px solid #6851d6" : "2px solid transparent",
              }}
              onClick={() => setActiveTab("calls")}
            >
              Calls
            </button>
            <button
              style={{
                flex: 1,
                padding: "12px 0",
                border: "none",
                background: "none",
                cursor: "pointer",
                fontWeight: 500,
                fontSize: 14,
                color: activeTab === "users" ? "#6851d6" : "#727272",
                borderBottom: activeTab === "users" ? "2px solid #6851d6" : "2px solid transparent",
              }}
              onClick={() => setActiveTab("users")}
            >
              Users
            </button>
          </div>

          <div style={{ flex: 1, overflow: "hidden", display: "flex", flexDirection: "column" }}>
            {activeTab === "chat" && (
              <CometChatConversations onItemClick={handleConversationClick} />
            )}
            {activeTab === "calls" && (
              <CometChatCallLogs onItemClick={handleCallClick} />
            )}
            {activeTab === "users" && (
              <CometChatUsers onItemClick={handleUserClick} />
            )}
          </div>
        </div>

        {selectedUser || selectedGroup ? (
          <div style={{ flex: 1, height: "100%", display: "flex", flexDirection: "column" }}>
            <CometChatMessageHeader user={selectedUser} group={selectedGroup} />
            <CometChatMessageList user={selectedUser} group={selectedGroup} />
            <CometChatMessageComposer user={selectedUser} group={selectedGroup} />
          </div>
        ) : (
          <div style={{
            flex: 1,
            display: "flex",
            justifyContent: "center",
            alignItems: "center",
            background: "#f5f5f5",
            color: "#727272",
            font: "400 14px Roboto, sans-serif",
          }}>
            Select a conversation to start chatting
          </div>
        )}
      </div>
    </CometChatProvider>
  );
}
```

```astro title="src/pages/chat.astro" theme={null}
---
import TabbedChat from '../components/TabbedChat.tsx';
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Chat</title>
  </head>
  <body style="margin: 0;">
    <TabbedChat client:only="react" />
  </body>
</html>
```

***

## How It Works

1. **`client:only="react"`** tells Astro to skip server-rendering and hydrate the component entirely on the client. This is required because CometChat uses browser APIs.
2. **React island** — the CometChat UI lives in a self-contained React component. Astro handles the page shell, React handles the interactive chat.
3. **Tab state** — `activeTab` controls which list component renders in the sidebar.
4. **Conditional rendering** — only the active tab's component mounts. Switching tabs unmounts the previous list and mounts the new one.
5. **Unified selection** — all three tabs feed into the same `selectedUser` / `selectedGroup` state. Clicking any item (conversation, call log, or user) updates the message panel.
6. **Call log handling** — when a call log is clicked, the receiver (user or group) is extracted and passed to the message components.

***

## Adding More Tabs

To add a Groups tab, import `CometChatGroups` and add another tab button + conditional render:

```tsx theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react";

// Add to Tab type:
type Tab = "chat" | "calls" | "users" | "groups";

// Add button in the tab bar:
<button
  style={{
    flex: 1,
    padding: "12px 0",
    border: "none",
    background: "none",
    cursor: "pointer",
    fontWeight: 500,
    fontSize: 14,
    color: activeTab === "groups" ? "#6851d6" : "#727272",
    borderBottom: activeTab === "groups" ? "2px solid #6851d6" : "2px solid transparent",
  }}
  onClick={() => setActiveTab("groups")}
>
  Groups
</button>

// Add in the sidebar list:
{activeTab === "groups" && (
  <CometChatGroups
    onItemClick={(group: CometChat.Group) => {
      setSelectedGroup(group);
      setSelectedUser(undefined);
    }}
  />
)}
```

You can follow the same pattern for any additional tabs (Settings, Contacts, etc.).

***

## Run

```bash theme={null}
npm run dev
```

Open `http://localhost:4321/chat`. You should see the tab bar at the top of the sidebar. Switch between Chats, Calls, and Users — clicking any item loads the message view on the right.

***

## Next Steps

<CardGroup>
  <Card title="Conversation List + Messages" icon="comments" href="/ui-kit/react/astro-conversation">
    Two-panel layout without tabs
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and styles
  </Card>
</CardGroup>


# Call
Source: https://www.cometchat.com/docs/ui-kit/react/call-features

Overview of CometChat React UI Kit calling features, including incoming calls, outgoing calls, call logs, and call components.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                                                                                                                                                                                                                                                     |
  | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Packages         | `@cometchat/chat-uikit-react` + `@cometchat/calls-sdk-javascript` (`npm install @cometchat/calls-sdk-javascript`)                                                                                                                                                                                                                                         |
  | Required setup   | Call `.setCallingEnabled(true)` on `UIKitSettingsBuilder` during init — Calls SDK must also be installed                                                                                                                                                                                                                                                  |
  | Call features    | Incoming Call, Outgoing Call, Call Logs, Call Buttons (in Message Header)                                                                                                                                                                                                                                                                                 |
  | Key components   | `CometChatMessageHeader` → [Message Header](/docs/ui-kit/react/components/message-header) (includes call buttons), `CometChatIncomingCall` → [Incoming Call](/docs/ui-kit/react/components/incoming-call), `CometChatOutgoingCall` → [Outgoing Call](/docs/ui-kit/react/components/outgoing-call), `CometChatCallLogs` → [Call Logs](/docs/ui-kit/react/components/call-logs) |
  | Enabling         | Set `.setCallingEnabled(true)` on `UIKitSettingsBuilder` to activate call UI components                                                                                                                                                                                                                                                                   |
  | CSS class prefix | `.cometchat-`                                                                                                                                                                                                                                                                                                                                             |
</Accordion>

## Overview

CometChat Calls integrates 1:1 and group audio/video calling into the React UI Kit. Install the Calls SDK and enable calling via `.setCallingEnabled(true)` on `UIKitSettingsBuilder` to activate call components.

<Note>
  Ensure you have called `CometChatUIKit.init()` with `.setCallingEnabled(true)` and `CometChatUIKit.login()` before rendering. See [React.js Integration](/docs/ui-kit/react/integration-react).
</Note>

## Integration

Install the Calls SDK and enable calling:

```bash lines theme={null}
npm install @cometchat/calls-sdk-javascript
```

Then set `.setCallingEnabled(true)` on your `UIKitSettingsBuilder`:

```tsx theme={null}
const settings = new UIKitSettingsBuilder()
  .setAppId("YOUR_APP_ID")
  .setRegion("YOUR_REGION")
  .setAuthKey("YOUR_AUTH_KEY")
  .setCallingEnabled(true)
  .build();

await CometChatUIKit.init(settings);
await CometChatUIKit.login("cometchat-uid-1");
```

Call buttons render inside [MessageHeader](/docs/ui-kit/react/components/message-header) when calling is enabled.

<Frame>
  <img />
</Frame>

## Features

### Incoming Call

The [Incoming Call](/docs/ui-kit/react/components/incoming-call) component displays a call screen when a call is received, showing caller info with accept/reject options.

<Frame>
  <img />
</Frame>

### Outgoing Call

The [Outgoing Call](/docs/ui-kit/react/components/outgoing-call) component displays an outgoing call screen with recipient info and call status. Transitions to the ongoing call screen when the receiver accepts.

<Frame>
  <img />
</Frame>

### Call Logs

The [Call Logs](/docs/ui-kit/react/components/call-logs) component displays call history — caller, time, and duration.

<Frame>
  <img />
</Frame>

## Next Steps

<CardGroup>
  <Card title="Message Header" icon="phone-flip" href="/ui-kit/react/components/message-header">
    Message header with integrated call buttons
  </Card>

  <Card title="Incoming Call" icon="phone-arrow-down-left" href="/ui-kit/react/components/incoming-call">
    Incoming call notifications and UI
  </Card>

  <Card title="Call Logs" icon="clock-rotate-left" href="/ui-kit/react/components/call-logs">
    Call history and details
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/react/core-features">
    Core chat features
  </Card>
</CardGroup>


# Calling Integration
Source: https://www.cometchat.com/docs/ui-kit/react/calling-integration

Step-by-step guide to integrate voice and video calling into your React app using CometChat UI Kit v7.

## Goal

By the end of this guide you will have voice and video calling working in your React app — including the `CometChatCallButtons` component, incoming call notifications, and outgoing call screens.

## Prerequisites

* A working CometChat React UI Kit v7 setup (completed the [Integration Guide](/docs/ui-kit/react/integration-react))
* `CometChatUIKit.init()` and `login()` completed before rendering
* A CometChat plan that includes calling features enabled in your [dashboard](https://app.cometchat.com)

## Step 1: Install the Calls SDK

The calling feature requires the optional `@cometchat/calls-sdk-javascript` peer dependency:

<CodeGroup>
  ```bash npm theme={null}
  npm install @cometchat/calls-sdk-javascript
  ```

  ```bash yarn theme={null}
  yarn add @cometchat/calls-sdk-javascript
  ```

  ```bash pnpm theme={null}
  pnpm add @cometchat/calls-sdk-javascript
  ```
</CodeGroup>

This package provides the WebRTC layer for voice and video calls. It is loaded lazily by the UI Kit — no additional bundle cost until calling is actually used.

## Step 2: Enable Calling in UIKitSettingsBuilder

Set `.setCallingEnabled(true)` on your `UIKitSettingsBuilder` during initialization:

```tsx title="src/main.tsx" theme={null}
import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";

const settings = new UIKitSettingsBuilder()
  .setAppId("YOUR_APP_ID")
  .setRegion("YOUR_REGION")
  .setAuthKey("YOUR_AUTH_KEY")
  .subscribePresenceForAllUsers()
  .setCallingEnabled(true)
  .build();

CometChatUIKit.init(settings).then(async () => {
  await CometChatUIKit.login("cometchat-uid-1");
  // Render your app
});
```

When calling is enabled, the UI Kit:

* Registers the `CallingPlugin` for call-related message rendering
* Lazy-loads call components (`CometChatIncomingCall`, `CometChatOutgoingCall`, `CometChatOngoingCall`) only when needed
* Enables the `CometChatCallButtons` component to initiate calls

When calling is not enabled (the default), call components are not loaded and `CometChatCallButtons` renders nothing.

## Step 3: Configure call settings

The Calls SDK uses the same `appId` and `region` from your `UIKitSettings` — no separate configuration is needed. The UI Kit passes these credentials to the Calls SDK automatically when calling is enabled.

<Note>
  The `config` prop on `CometChatProvider` accepts a `CometChatGlobalConfig` object for UI/behavior flags (`hideReceipts`, `hideUserStatus`, `disableSoundForCalls`, `customSoundForCalls`, `callSettingsBuilder`). It does **not** take a separate calling app ID or region.
</Note>

## Step 4: Add Call Buttons via CometChatMessageHeader

`CometChatMessageHeader` automatically renders voice and video call buttons when calling is enabled. No extra configuration needed — just render the header with a `user` or `group`:

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

function ChatPanel({ user }: { user: CometChat.User }) {
  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
      <CometChatMessageHeader user={user} />
      <CometChatMessageList user={user} />
      <CometChatMessageComposer user={user} />
    </div>
  );
}
```

The header shows call buttons by default. To hide them, use `hideVoiceCallButton` or `hideVideoCallButton`:

```tsx theme={null}
<CometChatMessageHeader user={user} hideVoiceCallButton />
```

For group calls, pass the `group` prop instead:

```tsx theme={null}
<CometChatMessageHeader group={group} />
```

<Note>
  `CometChatMessageHeader` renders its call buttons automatically (via the `CometChatMessageHeader.CallButtons` sub-component) — you don't import or render that sub-component separately. If you need call buttons **outside** the header, use the standalone [`CometChatCallButtons`](/docs/ui-kit/react/components/call-buttons) component.
</Note>

## Step 5: Verify with a voice call

With the setup complete, test a voice call:

1. Open your app with two different users in separate browser tabs
2. Click the **voice call** button (phone icon) in the chat header
3. The caller sees the `CometChatOutgoingCall` screen with a "Calling..." indicator
4. The receiver sees the `CometChatIncomingCall` overlay with accept/reject buttons
5. Once accepted, both users enter the `CometChatOngoingCall` view with live audio

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

export default function App() {
  const [user, setUser] = useState<CometChat.User | null>(null);

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const conversationWith = conversation.getConversationWith();
    if (conversationWith instanceof CometChat.User) {
      setUser(conversationWith);
    }
  };

  return (
    <CometChatProvider>
      <div style={{ display: "flex", height: "100vh" }}>
        <div style={{ width: "360px", borderRight: "1px solid #eee" }}>
          <CometChatConversations onItemClick={handleConversationClick} />
        </div>
        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
          {user && (
            <>
              <CometChatMessageHeader user={user} />
              <CometChatMessageList user={user} />
              <CometChatMessageComposer user={user} />
            </>
          )}
        </div>
      </div>
    </CometChatProvider>
  );
}
```

## Step 6: Verify with a video call

Video calls work identically — click the **video call** button (camera icon) instead. The `CometChatOngoingCall` component renders a full video interface with:

* Local and remote video streams
* Mute/unmute audio toggle
* Camera on/off toggle
* End call button

No additional configuration is needed to switch between audio-only and video calls. The call type is determined by which button the user clicks.

## Step 7: Render CometChatIncomingCall

`CometChatIncomingCall` must be rendered in your app — it is NOT auto-rendered by the UI Kit. Place it at the root level of your authenticated layout so it can display the incoming call overlay from anywhere:

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

export default function App() {
  const [user, setUser] = useState<CometChat.User | null>(null);

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const conversationWith = conversation.getConversationWith();
    if (conversationWith instanceof CometChat.User) {
      setUser(conversationWith);
    }
  };

  return (
    <CometChatProvider>
      <div style={{ display: "flex", height: "100vh" }}>
        <div style={{ width: "360px", borderRight: "1px solid #eee" }}>
          <CometChatConversations onItemClick={handleConversationClick} />
        </div>
        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
          {user && (
            <>
              <CometChatMessageHeader user={user} />
              <CometChatMessageList user={user} />
              <CometChatMessageComposer user={user} />
            </>
          )}
        </div>
      </div>

      {/* Incoming call overlay — renders at root level, listens for call events */}
      <CometChatIncomingCall />
    </CometChatProvider>
  );
}
```

`CometChatIncomingCall` listens for incoming call events and displays an accept/reject overlay. When the user accepts, it transitions to the `CometChatOngoingCall` screen internally. You can customize its behavior with callbacks:

```tsx theme={null}
<CometChatIncomingCall
  onAccept={(call) => console.log("Call accepted:", call)}
  onDecline={(call) => console.log("Call declined:", call)}
/>
```

`CometChatOutgoingCall` is rendered automatically by the `CometChatCallButtons` component when the user initiates a call — you do not need to place it manually.

## Summary

| Step | Action                                                                      |
| ---- | --------------------------------------------------------------------------- |
| 1    | Install `@cometchat/calls-sdk-javascript`                                   |
| 2    | Set `.setCallingEnabled(true)` on `UIKitSettingsBuilder`                    |
| 3    | (Optional) Configure call behavior via `config` prop on `CometChatProvider` |
| 4    | Call buttons appear in `CometChatMessageHeader` automatically               |
| 5    | Test voice calls between two users                                          |
| 6    | Test video calls between two users                                          |
| 7    | (Optional) Customize incoming/outgoing call handlers                        |

## Next Steps

* [Message Header](/docs/ui-kit/react/components/message-header) — full props reference including call button visibility
* [Call Logs](/docs/ui-kit/react/components/call-logs) — display call history
* [CometChatProvider](/docs/ui-kit/react/cometchat-provider) — all provider configuration options


# Campaigns
Source: https://www.cometchat.com/docs/ui-kit/react/campaigns

Deliver targeted, rich notifications to users via an in-app notification feed powered by the CometChat Cards renderer.

CometChat Campaigns enables you to send rich, interactive notifications to users through an in-app notification feed. Each notification is rendered as a native card using the **CometChat Cards** library — supporting images, text, buttons, layouts, and interactive actions.

<Tip>
  **Design cards visually with [Card Builder](/docs/card-builder/overview).** Build your card layouts in the CometChat Dashboard and export the Card Schema JSON these notifications render — instead of writing it by hand.
</Tip>

<Note>
  Before proceeding, ensure you have completed the [UI Kit integration](/docs/ui-kit/react/integration-react) and the [Dashboard Setup](/docs/campaigns#setup-flow) for Campaigns.
</Note>

<Frame>
  <img />
</Frame>

***

## Overview

Campaigns delivers notifications as **Card Schema JSON** — a structured format that defines the visual layout of each notification card. The system consists of three layers:

1. **CometChat Chat SDK** — Fetches feed items, manages read/delivered state, provides real-time listeners, handles push notification tracking
2. **CometChat Cards Library** (`@cometchat/cards-react`) — Renders Card Schema JSON into native DOM elements
3. **CometChat UI Kit** — Provides the ready-to-use `CometChatNotificationFeed` component that wires everything together

### Architecture Flow

```
Dashboard / API → Campaign Created → Push + WebSocket Delivery
                                  ↓
                SDK: NotificationFeedRequestBuilder.fetchNext()
                                  ↓
                NotificationFeedItem.getContent() → Card Schema JSON
                                  ↓
                Cards Library: CometChatCardView
                                  ↓
                Native Rendered Card (images, text, buttons, layouts)
                                  ↓
                User clicks button → onAction callback → Your code handles it
```

***

## How Cards Work

Each `NotificationFeedItem` from the SDK contains a `content` field — an object holding the Card Schema JSON. This JSON is passed directly to the CometChat Cards renderer which produces a DOM element.

The Cards library is a **pure renderer**:

* **Input**: Card Schema JSON string + theme mode + optional action callback
* **Output**: Native DOM element hierarchy

It does not execute actions, manage message state, or call any SDK methods. When users click interactive elements (buttons, links), the library emits the action to your callback. You decide what happens — open a URL, navigate to a chat, make an API call, etc.

### Card Schema JSON Example

```json theme={null}
{
  "version": "1.0",
  "body": [
    {
      "type": "column",
      "backgroundColor": {
        "light": "transparent",
        "dark": "transparent"
      },
      "gap": 5,
      "items": [
        {
          "type": "text",
          "content": "📢 Announcement",
          "variant": "heading2",
          "id": "txt_99323141-2459-4e33-88d3-ca39c5fd2f50"
        },
        {
          "type": "text",
          "content": "Your announcement message here.",
          "variant": "body",
          "id": "txt_61a417bc-5e4a-4ba2-bfe7-b7bc64dbaf35"
        },
        {
          "type": "divider",
          "id": "div_80f5c7fb-fd10-41d1-8c2f-51498f0f62d0"
        },
        {
          "type": "button",
          "label": "Learn More",
          "backgroundColor": {
            "light": "transparent",
            "dark": "transparent"
          },
          "textColor": {
            "light": "#6C5CE7",
            "dark": "#6C5CE7"
          },
          "size": 40,
          "fontSize": 13,
          "borderRadius": 6,
          "padding": {
            "top": 0,
            "right": 16,
            "bottom": 0,
            "left": 16
          },
          "action": {
            "type": "openUrl",
            "url": ""
          },
          "id": "btn_9b87a3f1-b0c6-45b9-a4c2-e22ea590f17f"
        }
      ],
      "id": "col_98fed9bd-1a95-4cee-aa81-84a9016e41f2"
    }
  ],
  "fallbackText": "",
  "style": {
    "background": {
      "light": "#E8E8E8",
      "dark": "#E8E8E8"
    },
    "borderRadius": 16,
    "borderColor": {
      "light": "#DFE6E9",
      "dark": "#DFE6E9"
    },
    "padding": 12
  }
}
```

The schema supports **20 element types** (text, image, icon, avatar, badge, divider, spacer, chip, progressBar, codeBlock, markdown, row, column, grid, accordion, tabs, button, iconButton, link, table) and **9 action types** (openUrl, chatWithUser, chatWithGroup, sendMessage, copyToClipboard, downloadFile, initiateCall, apiCall, customCallback).

***

## How Cards Work in the UI Kit

The `CometChatNotificationFeed` component uses the **CometChat Cards** library internally to render each notification. Here's what happens under the hood:

1. The component fetches `NotificationFeedItem` objects from the SDK
2. For each item, it extracts the `content` field (Card Schema JSON)
3. It passes the JSON to `CometChatCardView` from `@cometchat/cards-react`
4. The Cards renderer produces native UI — text, images, buttons, layouts — directly from the JSON
5. When users click buttons/links inside a card, the action is emitted back to the component which handles navigation (open URL, navigate to chat, etc.)

You don't need to interact with the Cards library directly when using `CometChatNotificationFeed` — it's all wired up. But if you want to render cards outside the feed (e.g., a standalone card in a modal), you can use the Cards library directly. See the [SDK Campaigns documentation](/docs/sdk/javascript/campaigns#rendering-cards) for standalone usage.

***

## Handling Push Notifications for Campaigns

When a campaign push notification arrives via Web Push or FCM, you should:

1. **Report delivery** — Call `CometChat.markPushNotificationDelivered()` when the notification is received
2. **Report click** — Call `CometChat.markPushNotificationClicked()` when the user clicks the notification
3. **Deep link** — Use the announcement ID from the push payload to fetch the full item via `CometChat.getNotificationFeedItem(id)` and display it

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";

// When push notification is received (e.g., in service worker)
const pushNotification = new CometChat.PushNotification(pushPayloadData);
CometChat.markPushNotificationDelivered(pushNotification);

// When user clicks the notification
CometChat.markPushNotificationClicked(pushNotification);

// Navigate to feed or show specific item
const item = await CometChat.getNotificationFeedItem(pushNotification.getId());
```

See the [SDK Campaigns documentation](/docs/sdk/javascript/campaigns) for the complete push notification tracking API.

***

## Sending Campaigns

Before integrating the frontend, you need to set up channels, categories, templates, and campaigns in the CometChat Dashboard. Follow the [Dashboard Setup Guide](/docs/campaigns#setup-flow) for step-by-step instructions with screenshots.

***

## Using the UI Kit Component

The easiest way to add a notification feed to your app is the `CometChatNotificationFeed` component. It handles fetching, rendering, pagination, filtering, real-time updates, and engagement reporting out of the box.

```tsx theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";

function NotificationsScreen() {
  return (
    <CometChatNotificationFeed
      onItemClick={(item) => {
        // Handle item click
      }}
      onBackPress={() => {
        // Navigate back
      }}
    />
  );
}
```

See the full [CometChatNotificationFeed component documentation](/docs/ui-kit/react/components/notification-feed) for all configuration options, styling, and customization.

***

## Next Steps

<CardGroup>
  <Card title="SDK Campaigns API" icon="code" href="/sdk/javascript/campaigns">
    Full API reference for feed items, categories, engagement, and push tracking
  </Card>

  <Card title="CometChatNotificationFeed" icon="bell" href="/ui-kit/react/components/notification-feed">
    Ready-to-use component with filtering, real-time updates, and styling
  </Card>
</CardGroup>


# CometChatProvider
Source: https://www.cometchat.com/docs/ui-kit/react/cometchat-provider

The root provider that composes all internal contexts (plugin registry, theme, locale, global config, events) for the React UI Kit.

## Overview

Every CometChat component must be rendered inside a `<CometChatProvider>` which supplies theme, locale, plugin registry, global config, and real-time events to the component tree.

`CometChatProvider` does **not** handle SDK initialization or user login. You must call `CometChatUIKit.init()` and `CometChatUIKit.login()` (or `loginWithAuthToken()`) imperatively before mounting the provider.

***

## Setup Pattern

The setup is always the same: initialize, login, then render.

```tsx title="src/main.tsx" theme={null}
import ReactDOM from "react-dom/client";
import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";
import App from "./App";

const settings = new UIKitSettingsBuilder()
  .setAppId("YOUR_APP_ID")
  .setRegion("us")
  .setAuthKey("YOUR_AUTH_KEY")
  .subscribePresenceForAllUsers()
  .setCallingEnabled(true)
  .build();

CometChatUIKit.init(settings).then(async () => {
  await CometChatUIKit.login("cometchat-uid-1");
  ReactDOM.createRoot(document.getElementById("root")!).render(<App />);
});
```

```tsx title="src/App.tsx" theme={null}
import { CometChatProvider, CometChatConversations } from "@cometchat/chat-uikit-react";

function App() {
  return (
    <CometChatProvider>
      <CometChatConversations />
    </CometChatProvider>
  );
}

export default App;
```

For production, use `CometChatUIKit.loginWithAuthToken(token)` instead of `login(uid)`.

***

## Props

| Prop            | Type                                   | Required | Default   | Description                                                                        |
| --------------- | -------------------------------------- | -------- | --------- | ---------------------------------------------------------------------------------- |
| `plugins`       | `CometChatMessagePlugin[]`             | No       | —         | Additional custom plugins, merged with the defaults                                |
| `removePlugins` | `{ text: string; category: string }[]` | No       | —         | Plugins to exclude — including defaults. See [Removing Plugins](#removing-plugins) |
| `config`        | `CometChatGlobalConfig`                | No       | `{}`      | Global flags (`hideReceipts`, `hideUserStatus`, etc.)                              |
| `theme`         | `"light" \| "dark"`                    | No       | `"light"` | Active theme                                                                       |
| `locale`        | `string`                               | No       | `"en-us"` | Language code for localization                                                     |
| `children`      | `ReactNode`                            | Yes      | —         | Your app content                                                                   |

***

## With Custom Theme and Locale

```tsx theme={null}
<CometChatProvider theme="dark" locale="fr">
  <MyChatApp />
</CometChatProvider>
```

***

## With Additional Plugins

All default plugins (text, image, file, audio, video, AI, etc.) are always included. Pass your own custom plugins via the `plugins` prop:

```tsx theme={null}
import { CometChatProvider } from "@cometchat/chat-uikit-react";
import { MyCustomPlugin } from "./plugins/MyCustomPlugin";

<CometChatProvider plugins={[MyCustomPlugin]}>
  <MyChatApp />
</CometChatProvider>
```

***

## Removing Plugins

Use `removePlugins` to exclude plugins — **including defaults** — so their message types no longer render. Each entry matches a plugin by its message **type** (`text`) and **category** (`category`); a plugin is removed when its `messageTypes` includes the `text` value **and** its `messageCategories` includes the `category` value.

```tsx theme={null}
import { CometChatProvider } from "@cometchat/chat-uikit-react";

// Remove the Polls plugin — poll messages will no longer render
<CometChatProvider
  removePlugins={[{ text: "extension_poll", category: "custom" }]}
>
  <MyChatApp />
</CometChatProvider>
```

Pass multiple entries to remove several plugins at once:

```tsx theme={null}
<CometChatProvider
  removePlugins={[
    { text: "extension_poll", category: "custom" },
    { text: "extension_sticker", category: "custom" },
  ]}
>
  <MyChatApp />
</CometChatProvider>
```

<Note>
  The `text` field is the message **type** (e.g. `extension_poll`, `text`, `image`), not literal text. Look up a plugin's type and category in the [Plugins](/docs/ui-kit/react/plugins/overview#built-in-plugins) table.
</Note>

***

## With Global Config

```tsx theme={null}
<CometChatProvider config={{ hideReceipts: true, hideUserStatus: false }}>
  <MyChatApp />
</CometChatProvider>
```

***

## Accessing the Logged-In User

Inside your components (children of `CometChatProvider`), access the logged-in user via the `useLoggedInUser()` hook or `CometChatUIKit.getLoggedInUser()`:

```tsx theme={null}
import { useLoggedInUser } from "@cometchat/chat-uikit-react";

function MyComponent() {
  const loggedInUser = useLoggedInUser();

  if (!loggedInUser) return <div>Loading...</div>;

  return <div>Welcome, {loggedInUser.getName()}</div>;
}
```

***

## Internal Architecture

`CometChatProvider` composes these internal providers in order:

```
CometChatProvider
  └─ PluginRegistryContext     — plugin registry from CometChatUIKit
     └─ GlobalConfigProvider   — hideReceipts, hideUserStatus, etc.
        └─ ThemeProvider        — data-theme attribute + CSS variables
           └─ LocaleProvider   — localization translations
              └─ EventsProvider — SDK listeners + UI events
                 └─ {children}
```

***

## Next.js App Router

`CometChatProvider` uses browser APIs internally, so it must be placed inside a Client Component. Additionally, init and login must happen client-side.

```tsx title="app/providers.tsx" theme={null}
"use client";

import { useEffect, useState } from "react";
import { CometChatUIKit, UIKitSettingsBuilder, CometChatProvider } from "@cometchat/chat-uikit-react";

export function ChatProviders({ children }: { children: React.ReactNode }) {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId(process.env.NEXT_PUBLIC_COMETCHAT_APP_ID!)
      .setRegion(process.env.NEXT_PUBLIC_COMETCHAT_REGION!)
      .setAuthKey(process.env.NEXT_PUBLIC_COMETCHAT_AUTH_KEY!)
      .setCallingEnabled(true)
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.loginWithAuthToken(getAuthToken());
      setReady(true);
    });
  }, []);

  if (!ready) return null;

  return (
    <CometChatProvider>
      {children}
    </CometChatProvider>
  );
}
```

***

## Migration from v6

In v6, initialization was imperative — call `init()` then `login()`, then render. v7 works the same way:

```tsx title="v6 (before)" theme={null}
import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";

const settings = new UIKitSettingsBuilder()
  .setAppId("APP_ID")
  .setRegion("REGION")
  .setAuthKey("AUTH_KEY")
  .build();

await CometChatUIKit.init(settings);
await CometChatUIKit.login("USER_ID");
// Then render your app
```

```tsx title="v7 (after)" theme={null}
import { CometChatUIKit, UIKitSettingsBuilder, CometChatProvider } from "@cometchat/chat-uikit-react";

const settings = new UIKitSettingsBuilder()
  .setAppId("APP_ID")
  .setRegion("REGION")
  .setAuthKey("AUTH_KEY")
  .build();

await CometChatUIKit.init(settings);
await CometChatUIKit.login("USER_ID");

// Then render with CometChatProvider wrapping your components
function App() {
  return (
    <CometChatProvider>
      <MyChatApp />
    </CometChatProvider>
  );
}
```

Key differences:

* v7 uses `CometChatProvider` to supply React context (theme, locale, plugins, events)
* Init and login are still imperative — same as v6
* Default plugins are included automatically
* Theme and locale are props on the provider
* Real-time events are managed internally (no RxJS, no manual listener setup)


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

### Messages

| Component                     | Purpose                                                                   | Page                                                                |
| ----------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `CometChatMessageHeader`      | Toolbar with avatar, name, status, typing indicator, and call buttons     | [Message Header](/docs/ui-kit/react/components/message-header)           |
| `CometChatMessageList`        | Scrollable message feed with plugin-based bubble rendering                | [Message List](/docs/ui-kit/react/components/message-list)               |
| `CometChatMessageComposer`    | Rich text input with attachments, emoji, voice recording, and formatting  | [Message Composer](/docs/ui-kit/react/components/message-composer)       |
| `CometChatMessageBubble`      | Message bubble container with alignment, receipts, options, and reactions | [Message Bubble](/docs/ui-kit/react/components/message-bubble)           |
| `CometChatThreadHeader`       | Parent message bubble and reply count for threaded conversations          | [Thread Header](/docs/ui-kit/react/components/thread-header)             |
| `CometChatMessageInformation` | Message delivery and read receipt details panel                           | [Message Information](/docs/ui-kit/react/components/message-information) |
| `CometChatReactions`          | Reaction chips bar with reactor list popover                              | [Reactions](/docs/ui-kit/react/components/reactions)                     |
| `CometChatReactionList`       | Full reactor list with tabs and pagination                                | [Reaction List](/docs/ui-kit/react/components/reaction-list)             |
| `CometChatFlagMessageDialog`  | Modal dialog for reporting/flagging messages with reason selection        | [Flag Message Dialog](/docs/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](/docs/ui-kit/react/components/text-bubble)                                         |
| `CometChatImagesBubble`                  | `image`                          | Image grid with captions, batch grouping, and a fullscreen gallery            | [Image Bubble](/docs/ui-kit/react/components/image-bubble)                                       |
| `CometChatVideosBubble`                  | `video`                          | Video grid with poster thumbnails, duration, and a fullscreen viewer          | [Video Bubble](/docs/ui-kit/react/components/video-bubble)                                       |
| `CometChatAudiosBubble`                  | `audio`                          | Stacked audio player cards with seek, duration, and download                  | [Audio Bubble](/docs/ui-kit/react/components/audio-bubble)                                       |
| `CometChatVoiceNoteBubble`               | `audio` (`voice_note`)           | Waveform player for recorded voice notes                                      | [Voice Note Bubble](/docs/ui-kit/react/components/voice-note-bubble)                             |
| `CometChatFilesBubble`                   | `file`                           | Stacked file cards with type icons, size, and download                        | [File Bubble](/docs/ui-kit/react/components/file-bubble)                                         |
| `CometChatPollBubble`                    | `extension_poll`                 | Poll with options, voting, and results                                        | [Poll Bubble](/docs/ui-kit/react/components/poll-bubble)                                         |
| `CometChatStickerBubble`                 | `extension_sticker`              | Sticker image display                                                         | [Sticker Bubble](/docs/ui-kit/react/components/sticker-bubble)                                   |
| `CometChatCollaborativeDocumentBubble`   | `extension_document`             | Document collaboration link with join button                                  | [Collaborative Document Bubble](/docs/ui-kit/react/components/collaborative-document-bubble)     |
| `CometChatCollaborativeWhiteboardBubble` | `extension_whiteboard`           | Whiteboard collaboration link with join button                                | [Collaborative Whiteboard Bubble](/docs/ui-kit/react/components/collaborative-whiteboard-bubble) |
| `CometChatCardBubble`                    | `card` (category)                | Developer-defined card messages drawn by the `CometChatCardView` renderer     | [Card Bubble](/docs/ui-kit/react/components/card-bubble)                                         |
| `CometChatGroupActionBubble`             | `groupMember`                    | Group membership system messages (joined, left, kicked, banned, scope change) | [Group Action Bubble](/docs/ui-kit/react/components/group-action-bubble)                         |
| `CometChatCallActionBubble`              | `audio`, `video` (call category) | Call status system messages (missed, outgoing, incoming, ended)               | [Call Action Bubble](/docs/ui-kit/react/components/call-action-bubble)                           |
| `CometChatCallBubble`                    | `meeting` (custom)               | Direct call / meeting invitation bubble                                       | [Call Bubble](/docs/ui-kit/react/components/call-bubble)                                         |

### Calling

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

### Search and AI

| Component                  | Purpose                                                | Page                                                       |
| -------------------------- | ------------------------------------------------------ | ---------------------------------------------------------- |
| `CometChatSearch`          | Unified search across conversations and messages       | [Search](/docs/ui-kit/react/components/search)                  |
| `CometChatAIAssistantChat` | AI agent chat with streaming, suggestions, and history | [AI Assistant](/docs/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>
  <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>


# AI Assistant Chat
Source: https://www.cometchat.com/docs/ui-kit/react/components/ai-assistant-chat

AI agent chat interface with streaming responses, suggested messages, tool calling, and conversation history.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatAIAssistantChat",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatAIAssistantChat } from \"@cometchat/chat-uikit-react\";",
    "description": "AI agent chat interface with streaming responses, suggested messages, tool calling, and conversation history.",
    "cssRootClass": ".cometchat-ai-assistant-chat",
    "primaryOutput": {
      "prop": "onSendButtonClick",
      "type": "(message: CometChat.BaseMessage) => void"
    },
    "props": {
      "data": {
        "user": {
          "type": "CometChat.User",
          "default": "REQUIRED",
          "note": "The AI assistant user entity"
        },
        "streamingSpeed": {
          "type": "number",
          "default": 30,
          "note": "Milliseconds between text chunks during streaming"
        },
        "aiAssistantTools": {
          "type": "CometChatAIAssistantTools",
          "default": "undefined",
          "note": "Tool handlers for AI function calls"
        },
        "loadLastAgentConversation": {
          "type": "boolean",
          "default": false
        },
        "suggestedMessages": {
          "type": "string[]",
          "default": "[] (falls back to user metadata)"
        },
        "parentMessageId": {
          "type": "number",
          "default": "undefined",
          "note": "Load a specific conversation thread"
        }
      },
      "callbacks": {
        "onSendButtonClick": "(message: CometChat.BaseMessage) => void",
        "onBackButtonClicked": "() => void",
        "onCloseButtonClicked": "() => void",
        "onError": "((error: CometChat.CometChatException) => void) | null"
      },
      "visibility": {
        "hideSuggestedMessages": { "type": "boolean", "default": false },
        "hideChatHistory": { "type": "boolean", "default": false },
        "hideNewChat": { "type": "boolean", "default": false },
        "showBackButton": { "type": "boolean", "default": false },
        "showCloseButton": { "type": "boolean", "default": false }
      },
      "viewSlots": {
        "emptyChatImageView": "ReactNode",
        "emptyChatGreetingView": "ReactNode",
        "emptyChatIntroMessageView": "ReactNode",
        "emptyView": "ReactNode",
        "loadingView": "ReactNode",
        "errorView": "ReactNode",
        "headerItemView": "ReactNode",
        "headerTitleView": "ReactNode",
        "headerSubtitleView": "ReactNode",
        "headerLeadingView": "ReactNode",
        "headerTrailingView": "ReactNode",
        "headerAuxiliaryButtonView": "ReactNode"
      }
    },
    "events": [
      {
        "name": "ui:compose/text",
        "payload": "{ text }",
        "description": "Suggestion pill clicked (sets text in composer)"
      }
    ],
    "sdkListeners": [],
    "types": {
      "CometChatAIAssistantTools": "Class — maps tool function names to handler functions via constructor(actions: Record<string, (args: Record<string, unknown>) => void>)"
    }
  }
  ```
</Accordion>

## Overview

`CometChatAIAssistantChat` is an AI agent chat interface. It renders a full chat experience with streaming responses, suggested message pills, tool calling support, and a conversation history sidebar. Pass a `CometChat.User` representing the AI assistant and the component handles the rest — message threading, streaming display, and composer integration.

<Note>
  **1:1 and group conversations.** AI Agents work in both one-on-one and group conversations. In a 1:1 chat, the end user talks directly with the agent user. In a group, the agent participates as a member — its messages (including cards) are delivered and attributed like any other member's message. If the group contains only one user and one agent, the agent responds automatically. In groups with more than two members, the agent only responds when @mentioned.
</Note>

<Info>
  **Live Preview** — interact with the default AI assistant chat.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-ai-ai-assistant-chat--default)
</Info>

<iframe title="CometChat AI Assistant Chat — Default" />

The component handles:

* Streaming AI responses with configurable speed
* Suggested message pills (from props or user metadata)
* Tool calling via `aiAssistantTools`
* Conversation history sidebar
* New chat creation
* Custom header views

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";

function AIChat({ aiUser }: { aiUser: CometChat.User }) {
  return (
    <CometChatAIAssistantChat
      user={aiUser}
      onSendButtonClick={(message) => {
        console.log("Message sent:", message);
      }}
    />
  );
}
```

### With Tool Calling

```tsx theme={null}
import {
  CometChatAIAssistantChat,
  CometChatAIAssistantTools,
} from "@cometchat/chat-uikit-react";

function AIChat({ aiUser }: { aiUser: CometChat.User }) {
  const tools = new CometChatAIAssistantTools({
    getWeather: (args) => {
      console.log("Getting weather for:", args.location);
    },
    searchDocs: (args) => {
      console.log("Searching docs for:", args.query);
    },
  });

  return (
    <CometChatAIAssistantChat
      user={aiUser}
      aiAssistantTools={tools}
      suggestedMessages={["What's the weather?", "Search documentation"]}
    />
  );
}
```

### With Custom Header

```tsx theme={null}
import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";

function AIChat({ aiUser }: { aiUser: CometChat.User }) {
  return (
    <CometChatAIAssistantChat
      user={aiUser}
      showBackButton
      onBackButtonClicked={() => navigateBack()}
      headerTitleView={<span>My AI Assistant</span>}
      headerSubtitleView={<span>Always online</span>}
    />
  );
}
```

### Full Layout Example

```tsx theme={null}
import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";

function App() {
  const [aiUser, setAiUser] = useState<CometChat.User | null>(null);

  useEffect(() => {
    CometChat.getUser("ai-assistant-uid").then(setAiUser);
  }, []);

  if (!aiUser) return <div>Loading...</div>;

  return (
    <div style={{ height: "100vh" }}>
      <CometChatAIAssistantChat
        user={aiUser}
        loadLastAgentConversation
        suggestedMessages={[
          "How do I get started?",
          "What features are available?",
          "Help me with integration",
        ]}
        onSendButtonClick={(message) => {
          console.log("User sent:", message);
        }}
        onError={(error) => {
          console.error("AI Chat error:", error);
        }}
      />
    </div>
  );
}
```

***

## Actions and Events

### Callback Props

| Prop                   | Signature                                                 | Fires when              |
| ---------------------- | --------------------------------------------------------- | ----------------------- |
| `onSendButtonClick`    | `(message: CometChat.BaseMessage) => void`                | User sends a message    |
| `onBackButtonClicked`  | `() => void`                                              | Back button is clicked  |
| `onCloseButtonClicked` | `() => void`                                              | Close button is clicked |
| `onError`              | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs        |

### Events Emitted

UI events this component publishes:

| Event             | Payload    | Fires when                                      |
| ----------------- | ---------- | ----------------------------------------------- |
| `ui:compose/text` | `{ text }` | Suggestion pill clicked (sets text in composer) |

### Events Received

None.

### SDK Listeners (Automatic)

None directly — the component uses `CometChatMessageList` internally which handles SDK listeners for message updates. The AI streaming is handled via `CometChat.addAIAssistantListener`.

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatAIAssistantChat
  user={aiUser}
  emptyChatImageView={<MyBotAvatar />}
  emptyChatGreetingView={<h2>Hello! I'm your assistant.</h2>}
  emptyChatIntroMessageView={<p>Ask me anything about our product.</p>}
  headerItemView={<MyCustomHeader />}
  loadingView={<AILoadingSkeleton />}
  errorView={<AIErrorState />}
/>
```

| Slot                        | Signature   | Replaces                                       |
| --------------------------- | ----------- | ---------------------------------------------- |
| `emptyChatImageView`        | `ReactNode` | AI avatar/icon in empty state                  |
| `emptyChatGreetingView`     | `ReactNode` | Greeting message in empty state                |
| `emptyChatIntroMessageView` | `ReactNode` | Intro message in empty state                   |
| `emptyView`                 | `ReactNode` | Entire empty state (replaces default greeting) |
| `loadingView`               | `ReactNode` | Loading shimmer                                |
| `errorView`                 | `ReactNode` | Error state                                    |
| `headerItemView`            | `ReactNode` | Entire header (replaces default)               |
| `headerTitleView`           | `ReactNode` | Header title                                   |
| `headerSubtitleView`        | `ReactNode` | Header subtitle                                |
| `headerLeadingView`         | `ReactNode` | Header avatar area                             |
| `headerTrailingView`        | `ReactNode` | Header trailing section                        |
| `headerAuxiliaryButtonView` | `ReactNode` | Header auxiliary buttons (New Chat + History)  |

#### emptyChatImageView

<Frame>
  <img />
</Frame>

```tsx theme={null}
import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";

function AIAssistantCustomImage() {
  const [agent, setAgent] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("assistant_uid").then((u) => setAgent(u));
  }, []);

  if (!agent) return null;

  return (
    <CometChatAIAssistantChat
      user={agent}
      emptyChatImageView={<img src={"ICON_URL"} height={60} width={60} alt="" />}
    />
  );
}
```

#### emptyChatGreetingView

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { useState, useEffect } from "react";
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";

    function AIAssistantCustomGreeting() {
      const [agent, setAgent] = useState<CometChat.User>();

      useEffect(() => {
        CometChat.getUser("assistant_uid").then((u) => setAgent(u));
      }, []);

      if (!agent) return null;

      return (
        <CometChatAIAssistantChat
          user={agent}
          emptyChatGreetingView={
            <div className="cometchat-ai-assistant-chat__empty-chat-greeting">
              <span className="plan-name">Free Plan</span> .
              <span className="upgrade-button">Upgrade</span>
            </div>
          }
        />
      );
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-ai-assistant-chat__empty-chat-greeting {
      display: flex;
      padding: 8px 20px;
      justify-content: center;
      align-items: center;
      gap: 8px;
      border-radius: 6px;
      border: 1px solid #e8e8e8;
      background: #f5f5f5;
      width: fit-content;
      align-self: center;
    }

    .cometchat-ai-assistant-chat__empty-chat-greeting .upgrade-button {
      color: #6852d6;
    }
    ```
  </Tab>
</Tabs>

#### emptyChatIntroMessageView

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { useState, useEffect } from "react";
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";

    function AIAssistantCustomIntro() {
      const [agent, setAgent] = useState<CometChat.User>();

      useEffect(() => {
        CometChat.getUser("assistant_uid").then((u) => setAgent(u));
      }, []);

      if (!agent) return null;

      return (
        <CometChatAIAssistantChat
          user={agent}
          emptyChatIntroMessageView={
            <div className="cometchat-ai-assistant-chat__empty-chat-intro">
              Hey, nice to see you What's new?
            </div>
          }
        />
      );
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-ai-assistant-chat__empty-chat-intro {
      display: flex;
      padding: 12px;
      justify-content: center;
      align-items: center;
      gap: 10px;
      border-radius: 12px;
      background: #f9f8fd;
      width: 172px;
      color: #141414;
      text-align: center;
      font-size: 16px;
      font-weight: 400;
      line-height: 140%;
      margin: 10px 0;
    }
    ```
  </Tab>
</Tabs>

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-ai-assistant-chat {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-ai-assistant-chat__empty-state-greeting-message {
  font-size: 1.5rem;
  font-weight: 600;
}
```

***

## Props

`user` is required. All other props are optional.

***

### user

The AI assistant user entity. This is the CometChat user that represents the AI agent.

|         |                  |
| ------- | ---------------- |
| Type    | `CometChat.User` |
| Default | **REQUIRED**     |

***

### streamingSpeed

Milliseconds between text chunks during streaming display.

|         |          |
| ------- | -------- |
| Type    | `number` |
| Default | `30`     |

***

### aiAssistantTools

Tool handlers for AI function calls. Maps tool names to handler functions.

|         |                             |
| ------- | --------------------------- |
| Type    | `CometChatAIAssistantTools` |
| Default | `undefined`                 |

```tsx theme={null}
const tools = new CometChatAIAssistantTools({
  getWeather: (args) => fetchWeather(args.location as string),
  searchDocs: (args) => searchDocumentation(args.query as string),
});

<CometChatAIAssistantChat user={aiUser} aiAssistantTools={tools} />
```

***

### loadLastAgentConversation

Auto-load the most recent conversation with the AI assistant on mount.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideSuggestedMessages

Hide the suggestion pills in the empty chat state.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### suggestedMessages

Custom suggestion texts displayed as pills in the empty state. Overrides suggestions from user metadata.

|         |                                                        |
| ------- | ------------------------------------------------------ |
| Type    | `string[]`                                             |
| Default | `[]` (falls back to user metadata `suggestedMessages`) |

***

### emptyChatImageView

Custom image/icon view for the empty chat state.

|         |                    |
| ------- | ------------------ |
| Type    | `ReactNode`        |
| Default | Built-in AI avatar |

***

### emptyChatGreetingView

Custom greeting message view for the empty chat state.

|         |                                                   |
| ------- | ------------------------------------------------- |
| Type    | `ReactNode`                                       |
| Default | User's `greetingMessage` metadata or display name |

***

### emptyChatIntroMessageView

Custom intro message view for the empty chat state.

|         |                                                                     |
| ------- | ------------------------------------------------------------------- |
| Type    | `ReactNode`                                                         |
| Default | User's `introductoryMessage` metadata or "I am here to assist you!" |

***

### hideChatHistory

Hide the chat history sidebar button in the header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideNewChat

Hide the "New Chat" button in the header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showBackButton

Show the back button in the header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showCloseButton

Show the close button in the header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### onBackButtonClicked

Callback when the back button is clicked.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onCloseButtonClicked

Callback when the close button is clicked.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onSendButtonClick

Callback when a message is sent to the AI assistant.

|         |                                            |
| ------- | ------------------------------------------ |
| Type    | `(message: CometChat.BaseMessage) => void` |
| Default | `undefined`                                |

***

### emptyView

Custom empty state view. Replaces the entire default greeting (image + greeting + intro + suggestions).

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `ReactNode`                        |
| Default | Built-in greeting with suggestions |

***

### loadingView

Custom loading view.

|         |                        |
| ------- | ---------------------- |
| Type    | `ReactNode`            |
| Default | Built-in loading state |

***

### errorView

Custom error view.

|         |                      |
| ------- | -------------------- |
| Type    | `ReactNode`          |
| Default | Built-in error state |

***

### onError

Callback when an SDK error occurs.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `null`                                                    |

***

### className

Additional CSS class name applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### parentMessageId

Load a specific conversation thread by parent message ID.

|         |             |
| ------- | ----------- |
| Type    | `number`    |
| Default | `undefined` |

***

### headerItemView

Custom view that replaces the entire header.

|         |                                   |
| ------- | --------------------------------- |
| Type    | `ReactNode`                       |
| Default | Built-in `CometChatMessageHeader` |

***

### headerTitleView

Custom title view for the header.

|         |                        |
| ------- | ---------------------- |
| Type    | `ReactNode`            |
| Default | AI user's display name |

***

### headerSubtitleView

Custom subtitle view for the header.

|         |                   |
| ------- | ----------------- |
| Type    | `ReactNode`       |
| Default | Built-in subtitle |

***

### headerLeadingView

Custom leading view (avatar area) for the header.

|         |                  |
| ------- | ---------------- |
| Type    | `ReactNode`      |
| Default | AI user's avatar |

***

### headerTrailingView

Custom trailing view for the header.

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

### headerAuxiliaryButtonView

Custom auxiliary button view for the header. Replaces the default New Chat + History buttons.

|         |                                     |
| ------- | ----------------------------------- |
| Type    | `ReactNode`                         |
| Default | Built-in New Chat + History buttons |

***

## CSS Selectors

| Target             | Selector                                                       |
| ------------------ | -------------------------------------------------------------- |
| Root container     | `.cometchat-ai-assistant-chat`                                 |
| Header             | `.cometchat-ai-assistant-chat__header`                         |
| Body               | `.cometchat-ai-assistant-chat__body`                           |
| Empty state        | `.cometchat-ai-assistant-chat__empty-state`                    |
| Empty state icon   | `.cometchat-ai-assistant-chat__empty-state-icon`               |
| Greeting message   | `.cometchat-ai-assistant-chat__empty-state-greeting-message`   |
| Intro message      | `.cometchat-ai-assistant-chat__empty-state-intro-message`      |
| Suggested messages | `.cometchat-ai-assistant-chat__empty-state-suggested-messages` |

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="comments" href="/ui-kit/react/components/message-list">
    Display messages in a conversation
  </Card>

  <Card title="Message Composer" icon="pen" href="/ui-kit/react/components/message-composer">
    Compose and send messages
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Audio Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/audio-bubble

A batch-aware bubble that renders one or more audio file attachments with inline playback cards, seek controls, and download.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatAudiosBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatAudiosBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Batch-aware audio bubble for attached audio files. Renders stacked audio cards with play/pause, seekable slider, duration, and download. NOT used for voice notes — see CometChatVoiceNoteBubble.",
    "cssRootClass": ".cometchat-audios-bubble",
    "selfExtracting": true,
    "multiAttachment": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of audio attachments and caption." },
        "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." },
        "textFormatters": { "type": "CometChatTextFormatter[]" },
        "className": { "type": "string" }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatAudiosBubble` renders audio file attachment(s) as stacked playback cards. It is **self-extracting**: pass the SDK `message` and the bubble derives the audio attachments and caption itself. The message list uses it automatically for audio messages that do **not** carry the `audioType: "voice_note"` metadata tag (voice notes render as a [Voice Note Bubble](/docs/ui-kit/react/components/voice-note-bubble) instead).

<Note>
  **Audio files vs Voice notes.** The audio plugin routes messages by the `audioType` metadata key:

  * **No `audioType`** (attached audio files) → `CometChatAudiosBubble` (this component)
  * **`audioType: "voice_note"`** (recorded via voice recorder) → [Voice Note Bubble](/docs/ui-kit/react/components/voice-note-bubble)

  This distinction is automatic — you don't need to configure it.
</Note>

Key capabilities:

* **Stacked audio cards** — one card per audio attachment with filename, play/pause, seekable slider, elapsed/total time
* **Inline playback** — plays audio directly in the bubble without a fullscreen viewer
* **Download button** — download individual audio files
* **Batch grouping** — rendered as one connected group when several media messages are sent together (handled by the [message list](/docs/ui-kit/react/components/message-list#multi-attachment-batch-grouping))
* **Caption support** — optional caption rendered below the cards

<Info>
  **Live Preview** — interact with the audio bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble-audios--two-audios)
</Info>

<iframe title="CometChat Audio Bubble — Two Audios" />

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatAudiosBubble } from "@cometchat/chat-uikit-react";

function AudioFilesMessage({ message }: { message: CometChat.MediaMessage }) {
  return <CometChatAudiosBubble message={message} />;
}
```

***

## Audio Card Layout

Each attachment renders as a card with:

| Element           | Description                                    |
| ----------------- | ---------------------------------------------- |
| Play/Pause button | Toggles playback for that audio file           |
| Filename          | Display name of the audio file                 |
| Seek slider       | Seekable progress bar showing current position |
| Time display      | `currentTime / totalDuration` in `m:ss` format |
| Download button   | Downloads the audio file                       |

When a message has multiple audio attachments, cards stack vertically.

<iframe title="CometChat Audio Bubble — With Caption" />

***

## Props

### message

The audio message. The bubble extracts its attachments and caption from it. **Required.**

|          |                          |
| -------- | ------------------------ |
| Type     | `CometChat.MediaMessage` |
| Required | Yes                      |

***

### alignment

Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user.

|         |                     |
| ------- | ------------------- |
| Type    | `"left" \| "right"` |
| Default | derived             |

***

### textFormatters

Text formatters applied to the caption (mentions, URLs).

|         |                            |
| ------- | -------------------------- |
| Type    | `CometChatTextFormatter[]` |
| Default | `undefined`                |

***

### className

Additional CSS class applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target                           | Selector                                     |
| -------------------------------- | -------------------------------------------- |
| Root                             | `.cometchat-audios-bubble`                   |
| Incoming variant                 | `.cometchat-audios-bubble--incoming`         |
| Outgoing variant                 | `.cometchat-audios-bubble--outgoing`         |
| Container                        | `.cometchat-audios-bubble__container`        |
| Multi-card container             | `.cometchat-audios-bubble__container--multi` |
| Audio card                       | `.cometchat-audios-bubble__card`             |
| Play button                      | `.cometchat-audios-bubble__play-btn`         |
| Play button icon                 | `.cometchat-audios-bubble__play-btn-icon`    |
| Card body (name + slider + time) | `.cometchat-audios-bubble__body`             |
| Filename                         | `.cometchat-audios-bubble__name`             |
| Seek slider                      | `.cometchat-audios-bubble__slider`           |
| Time display                     | `.cometchat-audios-bubble__time`             |
| Expand/collapse toggle           | `.cometchat-audios-bubble__toggle`           |
| Caption                          | `.cometchat-audios-bubble__caption`          |

***

## Next Steps

<CardGroup>
  <Card title="Voice Note Bubble" icon="microphone" href="/ui-kit/react/components/voice-note-bubble">
    Waveform bubble for recorded voice notes
  </Card>

  <Card title="File Bubble" icon="file" href="/ui-kit/react/components/file-bubble">
    Batch-aware file bubble with stacked cards
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/react/components/message-list">
    Multi-attachment batch grouping in the list
  </Card>

  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/react/components/message-composer">
    Multi-attachment staging tray
  </Card>
</CardGroup>


# Call Action Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/call-action-bubble

A self-extracting bubble that renders call status system messages like 'Missed Call', 'Call Ended', and 'Outgoing Call' from an SDK call message.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatCallActionBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatCallActionBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Self-extracting bubble for call status system messages. Derives the status text, icon, and error color from the SDK call message and the logged-in user.",
    "cssRootClass": ".cometchat-action-bubble",
    "selfExtracting": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.BaseMessage", "required": true, "note": "The call message (audio/video) in the 'call' category. Drives all extraction." },
        "className": { "type": "string", "default": "undefined", "note": "Additional CSS class for the root element" }
      }
    },
    "rendersThrough": "CometChatActionBubble (base primitive)",
    "usedBy": ["CometChatCallActionPlugin"]
  }
  ```
</Accordion>

## Overview

`CometChatCallActionBubble` renders a centered, pill-shaped call status system message — "Missed Call", "Call Ended", "Outgoing Call", etc. It is **self-extracting**: pass the SDK call message and the bubble derives the status text, the status icon, and whether to use the error (missed-call) color itself, reading the logged-in user and locale from hooks. This means it works standalone — no plugin required.

It is the component the [Call Action Plugin](/docs/ui-kit/react/plugins/overview#built-in-plugins) forwards to, and it renders through the presentational `CometChatActionBubble` base primitive.

<Info>
  **Live Preview** — interact with the call action bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-call-action-bubble--outgoing-calls)
</Info>

<iframe title="CometChat Call Action Bubble — Outgoing" />

> The component renders nothing while the logged-in user is unavailable.

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallActionBubble } from "@cometchat/chat-uikit-react";

function CallStatusMessage({ message }: { message: CometChat.BaseMessage }) {
  return <CometChatCallActionBubble message={message} />;
}
```

***

## What It Derives

The bubble inspects the call's status and whether it was initiated by the logged-in user to pick the text, icon, and color.

### Status Text

**Sent by the logged-in user:**

| Call status  | Text            |
| ------------ | --------------- |
| `initiated`  | Outgoing Call   |
| `ongoing`    | Answered Call   |
| `ended`      | Call Ended      |
| `cancelled`  | Cancelled Call  |
| `rejected`   | Rejected Call   |
| `unanswered` | Unanswered Call |
| `busy`       | Missed Call     |

**Received:**

| Call status                | Text          |
| -------------------------- | ------------- |
| `initiated`                | Incoming Call |
| `ongoing`                  | Answered Call |
| `ended`                    | Call Ended    |
| `unanswered` / `cancelled` | Missed Call   |
| `busy`                     | Busy Call     |
| `rejected`                 | Rejected Call |

All text is localized.

### Status Icon

| Condition                                             | Icon class                              |
| ----------------------------------------------------- | --------------------------------------- |
| Missed (received `busy` / `unanswered` / `cancelled`) | `--missed-video` / `--missed-audio`     |
| Ended                                                 | `--call-ended`                          |
| Sent by me (other statuses)                           | `--outgoing-video` / `--outgoing-audio` |
| Received (other statuses)                             | `--incoming-video` / `--incoming-audio` |

Missed calls additionally render in the error (red) color. Icons are rendered via CSS `mask-image` — override the mask in your own CSS to use custom icons.

***

## Props

### message

The call message (audio/video) in the `call` category. The bubble extracts the status, icon, and text from it. **Required.**

|          |                         |
| -------- | ----------------------- |
| Type     | `CometChat.BaseMessage` |
| Required | Yes                     |

***

### className

Additional CSS class name applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

The bubble renders through the `CometChatActionBubble` primitive, so it uses the action-bubble selectors.

| Target              | Selector                                         |
| ------------------- | ------------------------------------------------ |
| Root container      | `.cometchat-action-bubble`                       |
| Icon element        | `.cometchat-action-bubble__icon`                 |
| Icon (error state)  | `.cometchat-action-bubble__icon--error`          |
| Text element        | `.cometchat-action-bubble__text`                 |
| Text (error state)  | `.cometchat-action-bubble__text--error`          |
| Missed video icon   | `.cometchat-action-bubble__icon--missed-video`   |
| Missed audio icon   | `.cometchat-action-bubble__icon--missed-audio`   |
| Outgoing video icon | `.cometchat-action-bubble__icon--outgoing-video` |
| Outgoing audio icon | `.cometchat-action-bubble__icon--outgoing-audio` |
| Incoming video icon | `.cometchat-action-bubble__icon--incoming-video` |
| Incoming audio icon | `.cometchat-action-bubble__icon--incoming-audio` |
| Call ended icon     | `.cometchat-action-bubble__icon--call-ended`     |

Override a specific icon's mask:

```css theme={null}
.cometchat-action-bubble__icon--missed-video {
  -webkit-mask-image: url('/my-custom-missed-video.svg');
  mask-image: url('/my-custom-missed-video.svg');
}
```

***

## Next Steps

<CardGroup>
  <Card title="Call Action Plugin" icon="phone" href="/ui-kit/react/plugins/overview#built-in-plugins">
    How call status messages are resolved and rendered in the message list
  </Card>

  <Card title="Group Action Bubble" icon="users" href="/ui-kit/react/components/group-action-bubble">
    System messages for group membership changes
  </Card>

  <Card title="Message Bubble" icon="comment" href="/ui-kit/react/components/message-bubble">
    The wrapper that hosts bubble content
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Call Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/call-bubble

A self-extracting bubble for direct-call / meeting messages, with a call icon, title, timestamp, and a Join button.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatCallBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatCallBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Self-extracting call bubble for meeting / direct-call custom messages. Derives the call type, session ID, title, icon, and timestamp from the message.",
    "cssRootClass": ".cometchat-call-bubble",
    "selfExtracting": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.BaseMessage", "required": true, "note": "The meeting/direct-call message; drives extraction." },
        "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." },
        "onJoinClick": { "type": "(sessionId: string) => void" },
        "className": { "type": "string" }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatCallBubble` renders a direct-call / meeting message — a call icon, a title, a timestamp subtitle, and a **Join** button. It is **self-extracting**: pass the SDK `message` and the bubble derives the call type, session ID, title, icon, and timestamp itself, so it works standalone. Use `onJoinClick` to start the call when the user taps Join.

<Info>
  **Live Preview** — interact with the call bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-call-bubble--audio-call-outgoing)
</Info>

<iframe title="CometChat Call Bubble — Outgoing" />

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallBubble } from "@cometchat/chat-uikit-react";

function MeetingMessage({ message }: { message: CometChat.BaseMessage }) {
  return (
    <CometChatCallBubble
      message={message}
      onJoinClick={(sessionId) => {
        // Start / join the call session
      }}
    />
  );
}
```

***

## Props

### message

The meeting / direct-call custom message. The bubble extracts the call type, session ID, title, icon, and timestamp from it. **Required.**

|          |                         |
| -------- | ----------------------- |
| Type     | `CometChat.BaseMessage` |
| Required | Yes                     |

***

### alignment

Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user.

|         |                     |
| ------- | ------------------- |
| Type    | `"left" \| "right"` |
| Default | derived             |

***

### onJoinClick

Callback when the Join button is clicked. Receives the session ID.

|         |                               |
| ------- | ----------------------------- |
| Type    | `(sessionId: string) => void` |
| Default | `undefined`                   |

***

### className

Additional CSS class applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target              | Selector                                                              |
| ------------------- | --------------------------------------------------------------------- |
| Root                | `.cometchat-call-bubble`                                              |
| Incoming / outgoing | `.cometchat-call-bubble-incoming` / `.cometchat-call-bubble-outgoing` |
| Icon wrapper        | `.cometchat-call-bubble__icon-wrapper`                                |
| Title               | `.cometchat-call-bubble__body-content-title`                          |
| Subtitle            | `.cometchat-call-bubble__body-content-subtitle`                       |
| Join button         | `.cometchat-call-bubble__button`                                      |

***

## Next Steps

<CardGroup>
  <Card title="Call Action Bubble" icon="phone" href="/ui-kit/react/components/call-action-bubble">
    Call status system messages (missed, ended, etc.)
  </Card>

  <Card title="Call Logs" icon="clock-rotate-left" href="/ui-kit/react/components/call-logs">
    Browse call history and re-initiate calls
  </Card>

  <Card title="Message Bubble" icon="comment" href="/ui-kit/react/components/message-bubble">
    The wrapper that hosts bubble content
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Call Buttons
Source: https://www.cometchat.com/docs/ui-kit/react/components/call-buttons

Voice and video call buttons for user or group conversations, with click overrides, custom button views, and full call lifecycle handling.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatCallButtons",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatCallButtons } from \"@cometchat/chat-uikit-react\";",
    "description": "Voice and video call initiation buttons for user or group conversations. Manages the full call lifecycle (outgoing + ongoing) internally.",
    "cssRootClass": ".cometchat-call-buttons",
    "primaryOutput": {
      "description": "Initiates calls via the SDK and renders the outgoing/ongoing call screens"
    },
    "props": {
      "data": {
        "user": {
          "type": "CometChat.User",
          "default": "undefined",
          "note": "Pass either user or group, not both"
        },
        "group": {
          "type": "CometChat.Group",
          "default": "undefined",
          "note": "Pass either user or group, not both"
        }
      },
      "callbacks": {
        "onVoiceCallClick": "(entity: CometChat.User | CometChat.Group) => void",
        "onVideoCallClick": "(entity: CometChat.User | CometChat.Group) => void",
        "onCallEnded": "() => void",
        "onError": "((error: CometChat.CometChatException) => void) | null"
      },
      "visibility": {
        "hideVoiceCallButton": { "type": "boolean", "default": false },
        "hideVideoCallButton": { "type": "boolean", "default": false }
      },
      "viewSlots": {
        "voiceCallButtonView": "ReactNode",
        "videoCallButtonView": "ReactNode"
      },
      "configuration": {
        "callSettingsBuilder": "(isAudioOnlyCall: boolean, user?: CometChat.User, group?: CometChat.Group) => CallSettingsBuilder",
        "className": "string"
      }
    },
    "eventsEmitted": [
      {
        "name": "ui:call/outgoing",
        "payload": "{ call }",
        "description": "User initiates a 1-on-1 voice/video call"
      },
      {
        "name": "ui:message/sent",
        "payload": "{ message, status }",
        "description": "Group call meeting message sent"
      }
    ],
    "eventsReceived": [
      {
        "name": "ui:call/rejected",
        "payload": "{ call }",
        "description": "Re-enables call buttons after the call is rejected"
      },
      {
        "name": "ui:call/ended",
        "payload": "{}",
        "description": "Resets all call state when the call ends"
      }
    ],
    "sdkListeners": [
      "onIncomingCallReceived",
      "onIncomingCallCancelled",
      "onOutgoingCallAccepted",
      "onOutgoingCallRejected"
    ],
    "compositionExample": {
      "description": "Standalone call buttons or embedded in the MessageHeader auxiliary view",
      "components": ["CometChatCallButtons", "CometChatOutgoingCall", "CometChatOngoingCall"],
      "flow": "user/group prop -> click button -> SDK initiateCall -> CometChatOutgoingCall overlay -> onOutgoingCallAccepted -> CometChatOngoingCall"
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatCallButtons` renders voice and video call buttons. Pass a `user` for 1-on-1 calls or a `group` for group calls. It is typically embedded in `CometChatMessageHeader`'s auxiliary view or used standalone. The component is self-contained: clicking a button initiates the call, renders `CometChatOutgoingCall` internally while waiting for an answer, transitions to `CometChatOngoingCall` on acceptance, and cleans up when the call ends.

<Info>
  **Live Preview** — interact with the call buttons component.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-calls-cometchatcallbuttons--default)
</Info>

<iframe title="CometChat Call Buttons — Default" />

```tsx theme={null}
import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function CallButtonsDemo() {
  const [chatUser, setChatUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("uid").then((user) => setChatUser(user));
  }, []);

  return chatUser ? <CometChatCallButtons user={chatUser} /> : null;
}

export default CallButtonsDemo;
```

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx theme={null}
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function CallButtonsMinimal({ chatUser }: { chatUser: CometChat.User }) {
  return <CometChatCallButtons user={chatUser} />;
}
```

Root CSS class: `.cometchat-call-buttons`

***

## Actions and Events

### Callback Props

#### onVoiceCallClick

Overrides the default voice call initiation behavior. When set, clicking the voice button invokes this callback (with the active `user` or `group` entity) instead of initiating a call via the SDK.

```tsx theme={null}
import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function CallButtonsVoiceOverride() {
  const [chatUser, setChatUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("uid").then((user) => setChatUser(user));
  }, []);

  return (
    <CometChatCallButtons
      user={chatUser}
      onVoiceCallClick={(entity) => {
        console.log("Custom voice call logic for", entity.getName());
      }}
    />
  );
}
```

#### onVideoCallClick

Overrides the default video call initiation behavior.

```tsx theme={null}
import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function CallButtonsVideoOverride() {
  const [chatUser, setChatUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("uid").then((user) => setChatUser(user));
  }, []);

  return (
    <CometChatCallButtons
      user={chatUser}
      onVideoCallClick={(entity) => {
        console.log("Custom video call logic for", entity.getName());
      }}
    />
  );
}
```

#### onCallEnded

Fires after an ongoing call session ends and the component has reset its internal state.

```tsx theme={null}
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function CallButtonsWithEndHandler({ chatUser }: { chatUser: CometChat.User }) {
  return (
    <CometChatCallButtons
      user={chatUser}
      onCallEnded={() => {
        console.log("Call ended");
      }}
    />
  );
}
```

#### onError

Fires on internal errors during call initiation.

```tsx theme={null}
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function CallButtonsWithError({ chatUser }: { chatUser: CometChat.User }) {
  return (
    <CometChatCallButtons
      user={chatUser}
      onError={(error: CometChat.CometChatException) => {
        console.error("CallButtons error:", error);
      }}
    />
  );
}
```

### Events Emitted

UI events this component publishes during the call lifecycle:

| Event              | Payload               | Fires when                             |
| ------------------ | --------------------- | -------------------------------------- |
| `ui:call/outgoing` | `{ call }`            | A 1-on-1 voice/video call is initiated |
| `ui:message/sent`  | `{ message, status }` | A group call meeting message is sent   |

### Events Received

UI events this component subscribes to (published by other components):

| Event              | Payload    | Behavior                                          |
| ------------------ | ---------- | ------------------------------------------------- |
| `ui:call/rejected` | `{ call }` | Clears the active call and re-enables the buttons |
| `ui:call/ended`    | `{}`       | Clears the active call and resets all call state  |

### SDK Listeners (Real-Time, Automatic)

The component attaches SDK call listeners internally:

| SDK Listener              | Internal behavior                                 |
| ------------------------- | ------------------------------------------------- |
| `onIncomingCallReceived`  | Disables call buttons to prevent concurrent calls |
| `onIncomingCallCancelled` | Re-enables call buttons                           |
| `onOutgoingCallAccepted`  | Transitions to the ongoing call screen            |
| `onOutgoingCallRejected`  | Clears the active call and resets state           |

***

## Call Settings

Customize the calling experience via `callSettingsBuilder`. The builder is forwarded to the internal `CometChatOngoingCall` session.

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons, CometChatUIKitCalls } from "@cometchat/chat-uikit-react";

function CallButtonsCustomSettings({ chatUser }: { chatUser: CometChat.User }) {
  return (
    <CometChatCallButtons
      user={chatUser}
      callSettingsBuilder={(isAudioOnlyCall, user, group) =>
        new CometChatUIKitCalls.CallSettingsBuilder()
          .enableDefaultLayout(true)
          .setIsAudioOnlyCall(isAudioOnlyCall)
      }
    />
  );
}
```

***

## Customization

### Custom Button Views

Use `voiceCallButtonView` and `videoCallButtonView` to replace the default buttons while keeping the component's call lifecycle behavior intact.

```tsx theme={null}
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function CallButtonsCustomViews({ chatUser }: { chatUser: CometChat.User }) {
  return (
    <CometChatCallButtons
      user={chatUser}
      voiceCallButtonView={<button className="my-voice-btn">Voice</button>}
      videoCallButtonView={<button className="my-video-btn">Video</button>}
    />
  );
}
```

| Slot                  | Type        | Replaces                  |
| --------------------- | ----------- | ------------------------- |
| `voiceCallButtonView` | `ReactNode` | Default voice call button |
| `videoCallButtonView` | `ReactNode` | Default video call button |

***

## Common Patterns

### Voice-only call button

```tsx theme={null}
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function VoiceOnlyCallButtons({ chatUser }: { chatUser: CometChat.User }) {
  return <CometChatCallButtons user={chatUser} hideVideoCallButton={true} />;
}
```

### Group call buttons

```tsx theme={null}
import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function GroupCallButtons() {
  const [group, setGroup] = useState<CometChat.Group>();

  useEffect(() => {
    CometChat.getGroup("guid").then((g) => setGroup(g));
  }, []);

  return group ? <CometChatCallButtons group={group} /> : null;
}
```

***

## CSS Architecture

The component uses CSS custom properties (design tokens) provided by the UI Kit. The cascade:

1. Global tokens set on the `.cometchat` root wrapper.
2. Component CSS (`.cometchat-call-buttons`) consumes these tokens via `var()`.
3. Overrides target `.cometchat-call-buttons` descendant selectors.

### Key Selectors

| Target            | Selector                                      |
| ----------------- | --------------------------------------------- |
| Root              | `.cometchat-call-buttons`                     |
| Button element    | `.cometchat-call-buttons__button`             |
| Button icon       | `.cometchat-call-buttons__button-icon`        |
| Voice button icon | `.cometchat-call-buttons__button-icon--voice` |
| Video button icon | `.cometchat-call-buttons__button-icon--video` |

### Example: Themed call buttons

<Frame>
  <img />
</Frame>

```css theme={null}
.cometchat-call-buttons {
  display: flex;
  padding: 8px 16px;
  justify-content: center;
  align-items: center;
  gap: 4px;
  background: #fff;
}

.cometchat-call-buttons__button {
  border-radius: 8px;
  border: 1px solid #e8e8e8;
  background: #edeafa;
}

.cometchat-call-buttons__button-icon--voice,
.cometchat-call-buttons__button-icon--video {
  background-color: #6852d6;
}
```

### Customization Matrix

| What to change                | Where           | Property/API                                  | Example                                                     |
| ----------------------------- | --------------- | --------------------------------------------- | ----------------------------------------------------------- |
| Override call initiation      | Component props | `onVoiceCallClick` / `onVideoCallClick`       | `onVoiceCallClick={(entity) => customCall(entity)}`         |
| Hide a call button            | Component props | `hideVoiceCallButton` / `hideVideoCallButton` | `hideVideoCallButton={true}`                                |
| Replace a button view         | Component props | `voiceCallButtonView` / `videoCallButtonView` | `voiceCallButtonView={<CustomButton />}`                    |
| Customize call settings       | Component props | `callSettingsBuilder`                         | `callSettingsBuilder={(audio) => builder}`                  |
| Change colors, fonts, spacing | Global CSS      | Target `.cometchat-call-buttons` class        | `.cometchat-call-buttons__button-icon { background: red; }` |

***

## Props

All props are optional. Sorted alphabetically.

### callSettingsBuilder

Builder function for customizing the ongoing call settings.

|         |                                                                                                     |
| ------- | --------------------------------------------------------------------------------------------------- |
| Type    | `(isAudioOnlyCall: boolean, user?: CometChat.User, group?: CometChat.Group) => CallSettingsBuilder` |
| Default | `undefined`                                                                                         |

***

### className

Additional CSS class name applied to the root container.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### group

The group for group call buttons. Pass either `user` or `group`, not both.

|         |                   |
| ------- | ----------------- |
| Type    | `CometChat.Group` |
| Default | `undefined`       |

***

### hideVideoCallButton

Hides the video call button.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideVoiceCallButton

Hides the voice call button.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### onCallEnded

Callback fired after an ongoing call ends and the component resets its state.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onError

Callback fired when the component encounters an error.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `undefined`                                               |

***

### onVideoCallClick

Overrides the default video call initiation. Receives the active `user` or `group` entity.

|         |                                                       |
| ------- | ----------------------------------------------------- |
| Type    | `(entity: CometChat.User \| CometChat.Group) => void` |
| Default | `undefined`                                           |

***

### onVoiceCallClick

Overrides the default voice call initiation. Receives the active `user` or `group` entity.

|         |                                                       |
| ------- | ----------------------------------------------------- |
| Type    | `(entity: CometChat.User \| CometChat.Group) => void` |
| Default | `undefined`                                           |

***

### user

The user for 1-on-1 call buttons. Pass either `user` or `group`, not both.

|         |                  |
| ------- | ---------------- |
| Type    | `CometChat.User` |
| Default | `undefined`      |

***

### videoCallButtonView

Custom view that replaces the default video call button.

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

### voiceCallButtonView

Custom view that replaces the default voice call button.

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

## CSS Selectors

| Target            | Selector                                      |
| ----------------- | --------------------------------------------- |
| Root              | `.cometchat-call-buttons`                     |
| Button element    | `.cometchat-call-buttons__button`             |
| Button icon       | `.cometchat-call-buttons__button-icon`        |
| Voice button icon | `.cometchat-call-buttons__button-icon--voice` |
| Video button icon | `.cometchat-call-buttons__button-icon--video` |

***

## Next Steps

<CardGroup>
  <Card title="Outgoing Call" icon="phone-arrow-up-right" href="/ui-kit/react/components/outgoing-call">
    Customize the outgoing call screen shown while waiting for an answer
  </Card>

  <Card title="Incoming Call" icon="phone-arrow-down-left" href="/ui-kit/react/components/incoming-call">
    Handle incoming call notifications with accept/decline actions
  </Card>

  <Card title="Call Logs" icon="clock-rotate-left" href="/ui-kit/react/components/call-logs">
    Browse call history and re-initiate calls
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Call Logs
Source: https://www.cometchat.com/docs/ui-kit/react/components/call-logs

Scrollable list of call history with call details, duration, and the ability to initiate new calls.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatCallLogs",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatCallLogs } from \"@cometchat/chat-uikit-react\";",
    "description": "Scrollable list of call history with call details, duration, and the ability to initiate new calls.",
    "cssRootClass": ".cometchat-call-logs",
    "primaryOutput": {
      "prop": "onItemClick",
      "type": "(call: any) => void"
    },
    "props": {
      "data": {
        "activeCall": {
          "type": "any",
          "default": "undefined",
          "note": "Object representing the active/selected call log"
        },
        "callLogRequestBuilder": {
          "type": "any",
          "default": "limit 30, category \"call\"",
          "note": "Custom request builder for filtering call logs"
        },
        "callInitiatedDateTimeFormat": {
          "type": "CometChatDateFormatConfig",
          "default": "hh:mm A today, Yesterday, dddd last week, DD/MM/YYYY older"
        }
      },
      "callbacks": {
        "onItemClick": "(call: any) => void",
        "onCallButtonClicked": "(call: any) => void",
        "onError": "((error: CometChat.CometChatException) => void) | null"
      },
      "configuration": {
        "callSettingsBuilder": {
          "type": "any",
          "default": "undefined",
          "note": "Custom call settings builder for ongoing call sessions initiated from call logs"
        }
      },
      "visibility": {
        "showScrollbar": { "type": "boolean", "default": false }
      },
      "viewSlots": {
        "loadingView": "ReactNode",
        "emptyView": "ReactNode",
        "errorView": "ReactNode",
        "itemView": "(call: any) => ReactNode",
        "leadingView": "(call: any) => ReactNode",
        "titleView": "(call: any) => ReactNode",
        "subtitleView": "(call: any) => ReactNode",
        "trailingView": "(call: any) => ReactNode"
      }
    },
    "events": [],
    "eventsReceived": [
      {
        "name": "ui:call/ended",
        "payload": "{}",
        "description": "Resets ongoing call state (hides call screen)"
      }
    ],
    "sdkListeners": [],
    "types": {
      "CometChatDateFormatConfig": {
        "today": "string | undefined",
        "yesterday": "string | undefined",
        "lastWeek": "string | undefined",
        "otherDays": "string | undefined",
        "relativeTime": {
          "minute": "string | undefined",
          "minutes": "string | undefined",
          "hour": "string | undefined",
          "hours": "string | undefined"
        }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatCallLogs` is a scrollable list component that displays the user's call history. Each item shows call direction (incoming/outgoing/missed), participant info, duration, and timestamp. The trailing view includes a call button to re-initiate calls directly from the log.

<Info>
  **Live Preview** — interact with the call logs component.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-calls-cometchat-call-logs--default)
</Info>

<iframe title="CometChat Call Logs — Default" />

The component handles:

* Paginated fetching of call logs with infinite scroll
* Call direction indicators (incoming, outgoing, missed)
* Call duration and timestamp display
* Call button in trailing view to re-initiate calls
* Transition to outgoing/ongoing call screens internally when a call is initiated
* Active call highlighting

> **No real-time updates:** This component fetches call logs via the request builder on mount and does not attach SDK listeners for real-time updates. Pull-to-refresh or remounting is needed to see new call logs.

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react";

function CallHistory() {
  return (
    <CometChatCallLogs
      onItemClick={(call) => {
        console.log("Call log clicked:", call);
      }}
      onCallButtonClicked={(call) => {
        console.log("Re-initiating call to:", call);
      }}
    />
  );
}
```

### Full Layout Example

```tsx theme={null}
import { useState } from "react";
import { CometChatCallLogs } from "@cometchat/chat-uikit-react";

function CallsTab() {
  const [selectedCall, setSelectedCall] = useState<any>(null);

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        <CometChatCallLogs
          onItemClick={(call) => setSelectedCall(call)}
          onCallButtonClicked={(call) => {
            // Initiate a new call to the same participant
            initiateCall(call);
          }}
        />
      </div>
      <div style={{ flex: 1, padding: 16 }}>
        {selectedCall && (
          // Render your own details panel for the selected call log
          <pre>{JSON.stringify(selectedCall, null, 2)}</pre>
        )}
      </div>
    </div>
  );
}
```

***

## Filtering

Pass a custom `callLogRequestBuilder` to control which call logs are fetched. The default fetches up to 30 call logs with category "call". Refer to [CallLogRequestBuilder](/docs/sdk/javascript/call-logs) for the full builder API.

```tsx theme={null}
import { CometChatUIKitCalls } from "@cometchat/chat-uikit-react";

<CometChatCallLogs
  callLogRequestBuilder={
    new CometChatUIKitCalls.CallLogRequestBuilder()
      .setLimit(50)
      .setCallCategory("call")
      .setAuthToken(authToken) // logged-in user's auth token (required when supplying your own builder)
  }
/>
```

### Filter Recipes

| Recipe                     | Code                                                                                    |
| -------------------------- | --------------------------------------------------------------------------------------- |
| Increase page size         | `new CometChatUIKitCalls.CallLogRequestBuilder().setLimit(50).setCallCategory("call")`  |
| Calls with a specific user | `new CometChatUIKitCalls.CallLogRequestBuilder().setUid("uid").setAuthToken(authToken)` |
| Only missed calls          | Custom filtering via `itemView` with conditional rendering                              |

***

## Actions and Events

### Callback Props

| Prop                  | Signature                                                 | Fires when                                   |
| --------------------- | --------------------------------------------------------- | -------------------------------------------- |
| `onItemClick`         | `(call: any) => void`                                     | User clicks a call log item                  |
| `onCallButtonClicked` | `(call: any) => void`                                     | User clicks the call button in trailing view |
| `onError`             | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs                             |

### Events Emitted

This component does not emit any UI events.

### Events Received

UI events this component subscribes to (published by other components):

| Event           | Payload | Behavior                                      |
| --------------- | ------- | --------------------------------------------- |
| `ui:call/ended` | `{}`    | Resets ongoing call state (hides call screen) |

### SDK Listeners (Automatic)

This component does not attach any SDK listeners. It fetches call logs via the request builder on mount and uses infinite scroll for pagination. No real-time updates are received.

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatCallLogs
  itemView={(call) => <MyCustomCallItem call={call} />}
  leadingView={(call) => <MyCustomAvatar call={call} />}
  subtitleView={(call) => <span>{call.getDuration()}s</span>}
  emptyView={<p>No call history yet</p>}
  loadingView={<Skeleton />}
  errorView={<ErrorBanner />}
/>
```

| Slot           | Signature                  | Replaces                  |
| -------------- | -------------------------- | ------------------------- |
| `itemView`     | `(call: any) => ReactNode` | Entire call log row       |
| `leadingView`  | `(call: any) => ReactNode` | Avatar section            |
| `titleView`    | `(call: any) => ReactNode` | Participant name          |
| `subtitleView` | `(call: any) => ReactNode` | Call direction + duration |
| `trailingView` | `(call: any) => ReactNode` | Call button + timestamp   |
| `loadingView`  | `ReactNode`                | Loading shimmer           |
| `emptyView`    | `ReactNode`                | Empty state               |
| `errorView`    | `ReactNode`                | Error state               |

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-call-logs {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-call-logs__list-item:hover {
  background: var(--cometchat-background-color-02);
}
```

***

## Props

All props are optional.

***

### activeCall

Object representing the currently active/selected call log. The matching item receives an active visual state.

|         |             |
| ------- | ----------- |
| Type    | `any`       |
| Default | `undefined` |

***

### callLogRequestBuilder

Custom request builder for filtering and paginating call logs.

|         |                           |
| ------- | ------------------------- |
| Type    | `any`                     |
| Default | Limit 30, category "call" |

***

### callInitiatedDateTimeFormat

Custom date/time format for the call initiation timestamp shown in each call log item.

|         |                                                                                           |
| ------- | ----------------------------------------------------------------------------------------- |
| Type    | `CometChatDateFormatConfig`                                                               |
| Default | `{ today: 'hh:mm A', yesterday: 'Yesterday', lastWeek: 'dddd', otherDays: 'DD/MM/YYYY' }` |

***

### onItemClick

Callback when a call log item is clicked.

|         |                       |
| ------- | --------------------- |
| Type    | `(call: any) => void` |
| Default | `undefined`           |

***

### onCallButtonClicked

Callback when the call button (in the trailing view) is clicked to re-initiate a call.

|         |                       |
| ------- | --------------------- |
| Type    | `(call: any) => void` |
| Default | `undefined`           |

***

### onError

Callback when an SDK error occurs during fetch operations.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `null`                                                    |

***

### callSettingsBuilder

Custom call settings builder for ongoing call sessions initiated from call logs. Falls back to `GlobalConfig.callSettingsBuilder`, then default settings.

|         |             |
| ------- | ----------- |
| Type    | `any`       |
| Default | `undefined` |

***

### loadingView

Custom loading state view shown while call logs are being fetched.

|         |                          |
| ------- | ------------------------ |
| Type    | `ReactNode`              |
| Default | Built-in loading shimmer |

***

### emptyView

Custom empty state view shown when no call logs exist.

|         |                      |
| ------- | -------------------- |
| Type    | `ReactNode`          |
| Default | Built-in empty state |

***

### errorView

Custom error state view shown when fetching call logs fails.

|         |                      |
| ------- | -------------------- |
| Type    | `ReactNode`          |
| Default | Built-in error state |

***

### itemView

Custom renderer for the entire call log row.

|         |                            |
| ------- | -------------------------- |
| Type    | `(call: any) => ReactNode` |
| Default | `undefined`                |

***

### leadingView

Custom renderer for the avatar section.

|         |                            |
| ------- | -------------------------- |
| Type    | `(call: any) => ReactNode` |
| Default | `undefined`                |

***

### titleView

Custom renderer for the participant name.

|         |                            |
| ------- | -------------------------- |
| Type    | `(call: any) => ReactNode` |
| Default | `undefined`                |

***

### subtitleView

Custom renderer for the call direction and duration section.

|         |                            |
| ------- | -------------------------- |
| Type    | `(call: any) => ReactNode` |
| Default | `undefined`                |

***

### trailingView

Custom renderer for the trailing section (call button + timestamp).

|         |                            |
| ------- | -------------------------- |
| Type    | `(call: any) => ReactNode` |
| Default | `undefined`                |

***

### showScrollbar

Show the native scrollbar on the call logs list.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

## CSS Selectors

| Target         | Selector                                        |
| -------------- | ----------------------------------------------- |
| Root container | `.cometchat-call-logs`                          |
| List container | `.cometchat-call-logs__list`                    |
| List item      | `.cometchat-call-logs__list-item`               |
| Item avatar    | `.cometchat-call-logs__list-item-avatar`        |
| Item title     | `.cometchat-call-logs__list-item-title`         |
| Item subtitle  | `.cometchat-call-logs__list-item-subtitle`      |
| Subtitle icon  | `.cometchat-call-logs__list-item-subtitle-icon` |
| Subtitle text  | `.cometchat-call-logs__list-item-subtitle-text` |
| Item trailing  | `.cometchat-call-logs__list-item-trailing`      |
| Empty state    | `.cometchat-call-logs__empty-state`             |
| Error state    | `.cometchat-call-logs__error-state`             |
| Loading state  | `.cometchat-call-logs__loading-state`           |

***

## Next Steps

<CardGroup>
  <Card title="Incoming Call" icon="phone-arrow-down-left" href="/ui-kit/react/components/incoming-call">
    Handle incoming call notifications with accept/decline actions
  </Card>

  <Card title="Outgoing Call" icon="phone-arrow-up-right" href="/ui-kit/react/components/outgoing-call">
    Display the outgoing call screen while waiting for the receiver to answer
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Card Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/card-bubble

A render-only bubble that draws developer-defined card messages (category "card") with the prebuilt CometChatCardView renderer and forwards card actions to your app.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatCardBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatCardBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Render-only bubble for developer card messages (category \"card\"). Stringifies the raw payload from message.getCard() and hands it to the prebuilt CometChatCardView renderer, then forwards user actions back to the app. It never parses, mutates, or acts on the card itself.",
    "cssRootClass": ".cometchat-card-bubble",
    "renderOnly": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.CardMessage", "required": true, "note": "The developer card message (category \"card\"). Drives message.getCard()." },
        "themeMode": { "type": "CometChatCardThemeMode", "default": "\"auto\"", "note": "Theme mode forwarded to CometChatCardView." },
        "themeOverride": { "type": "CometChatCardThemeOverride", "note": "Optional theme overrides forwarded to the renderer." },
        "onCardAction": { "type": "(message: CometChat.BaseMessage, action: CometChatCardAction) => void", "note": "Direct callback for card actions, fired in addition to the ui:card/action event." }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatCardBubble` renders a **card message** — a message with `category: "card"`. A card message carries a block of Card Schema JSON that is created and sent server-side (via the Platform (REST) API or the Dashboard Bubble Builder) and delivered to clients like any other message. Card messages are **receive-only**: the UI Kit renders them, it does not send them.

<Tip>
  **Design cards visually with [Card Builder](/docs/card-builder/overview).** Build your card messages in the CometChat Dashboard and export the Card Schema JSON — instead of writing it by hand.
</Tip>

The bubble is **render-only**, mirroring `CometChatTextBubble`: the kit performs zero transformation. It stringifies the raw payload from `message.getCard()` and hands it to the prebuilt [`CometChatCardView`](https://www.npmjs.com/package/@cometchat/cards-react) renderer (`@cometchat/cards-react`), then forwards user actions back to your app. It never parses or mutates the card body, and never performs an action itself — your app owns all action behavior (opening URLs, navigating to chats, API calls, etc.).

In the message list, card messages are routed to this bubble automatically by the built-in **Card plugin** — no configuration is required. See [Plugins → Built-in Plugins](/docs/ui-kit/react/plugins/overview#built-in-plugins).

### Where cards fit in the message hierarchy

`card` is a top-level message category, alongside `message`, `custom`, `action`, and `call`.

<Frame>
  <img />
</Frame>

***

## Usage

Card messages render automatically inside `CometChatMessageList`. To render one directly — for example in a custom layout — pass the SDK `CardMessage` to the bubble:

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCardBubble } from "@cometchat/chat-uikit-react";

function CardMessageItem({ message }: { message: CometChat.CardMessage }) {
  return <CometChatCardBubble message={message} />;
}
```

To receive card actions without going through the [event bus](/docs/ui-kit/react/event-system), pass an `onCardAction` callback:

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatCardBubble,
  type CometChatCardAction,
} from "@cometchat/chat-uikit-react";

function CardMessageItem({ message }: { message: CometChat.CardMessage }) {
  const handleAction = (
    msg: CometChat.BaseMessage,
    action: CometChatCardAction
  ) => {
    // Your app owns the behavior — open a URL, start a call, call an API, etc.
    console.log("Card action", action, "on message", msg.getId());
  };

  return <CometChatCardBubble message={message} onCardAction={handleAction} />;
}
```

***

## Props

### message

The developer card message (`category: "card"`). The bubble reads the raw card payload from `message.getCard()`. **Required.**

|          |                         |
| -------- | ----------------------- |
| Type     | `CometChat.CardMessage` |
| Required | Yes                     |

***

### themeMode

Theme mode forwarded to the `CometChatCardView` renderer.

|         |                          |
| ------- | ------------------------ |
| Type    | `CometChatCardThemeMode` |
| Default | `"auto"`                 |

***

### themeOverride

Optional theme overrides forwarded to the renderer.

|         |                              |
| ------- | ---------------------------- |
| Type    | `CometChatCardThemeOverride` |
| Default | `undefined`                  |

***

### onCardAction

Direct callback for card actions. Fired **in addition to** the `ui:card/action` UI event, so an app embedding the bubble directly can receive actions without subscribing to the event bus. Receives the message and the clicked action.

|         |                                                                         |
| ------- | ----------------------------------------------------------------------- |
| Type    | `(message: CometChat.BaseMessage, action: CometChatCardAction) => void` |
| Default | `undefined`                                                             |

***

## Card Actions

When a user clicks an action inside a card (a button, link, etc.), the bubble forwards the raw action to your app through **two** channels — it never handles the action itself:

1. The optional [`onCardAction`](#oncardaction) prop, when provided.
2. The [`ui:card/action`](/docs/ui-kit/react/event-system#card-actions) UI event, published on the event bus with the `message` and the clicked `action`. This is the only channel that can reach a card rendered by the kit (e.g. a nested agent card) where no prop is reachable.

Subscribe to the event anywhere in your app:

```tsx theme={null}
import { useCometChatEvents } from "@cometchat/chat-uikit-react";

function CardActionListener() {
  useCometChatEvents((event) => {
    if (event.type === "ui:card/action") {
      // event.message, event.action
      console.log("Card action clicked:", event.action);
    }
  });

  return null;
}
```

***

## Fallback

When `message.getCard()` is absent or empty, the renderer is **not** invoked. Instead the bubble renders a plain-text fallback, resolving the first available of:

1. `message.getFallbackText()`
2. `message.getText()`
3. The localized `"Card Message"` string

***

## CSS Selectors

| Target        | Selector                           |
| ------------- | ---------------------------------- |
| Root          | `.cometchat-card-bubble`           |
| Text fallback | `.cometchat-card-bubble__fallback` |

The card body itself is styled by the `CometChatCardView` renderer; use `themeMode` / `themeOverride` to theme it.

***

## Next Steps

<CardGroup>
  <Card title="Plugins" icon="puzzle-piece" href="/ui-kit/react/plugins/overview#built-in-plugins">
    How the Card plugin routes card messages to this bubble
  </Card>

  <Card title="Event System" icon="bolt" href="/ui-kit/react/event-system#card-actions">
    Subscribe to the ui:card/action event
  </Card>

  <Card title="Message Bubble" icon="comment" href="/ui-kit/react/components/message-bubble">
    The wrapper that hosts bubble content
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Collaborative Document Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/collaborative-document-bubble

A self-extracting bubble that renders a collaborative document card with a banner and an 'Open Document' button.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatCollaborativeDocumentBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatCollaborativeDocumentBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Self-extracting collaborative document bubble. Extracts the document URL from the message metadata and opens it on click.",
    "cssRootClass": ".cometchat-collaborative-bubble",
    "selfExtracting": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.BaseMessage", "required": true, "note": "Drives extraction of the document URL." },
        "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." },
        "onButtonClick": { "type": "(url: string) => void", "note": "Defaults to window.open." },
        "disabled": { "type": "boolean", "default": false },
        "className": { "type": "string" }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatCollaborativeDocumentBubble` renders a collaborative document card — a banner image, a title, a subtitle, and an "Open Document" button. It is **self-extracting**: pass the SDK `message` and the bubble reads the document URL from the message's extension metadata (`@injected.extensions.document.document_url`), so it works standalone. Clicking the button opens the document (by default in a new window).

<Info>
  **Live Preview** — interact with the collaborative document bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble--collaborative-document-message)
</Info>

<iframe title="CometChat Collaborative Document Bubble — Default" />

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCollaborativeDocumentBubble } from "@cometchat/chat-uikit-react";

function DocumentMessage({ message }: { message: CometChat.BaseMessage }) {
  return <CometChatCollaborativeDocumentBubble message={message} />;
}
```

***

## Props

### message

The collaborative-document message. The bubble extracts the URL from its metadata. **Required.**

|          |                         |
| -------- | ----------------------- |
| Type     | `CometChat.BaseMessage` |
| Required | Yes                     |

***

### alignment

Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user.

|         |                     |
| ------- | ------------------- |
| Type    | `"left" \| "right"` |
| Default | derived             |

***

### onButtonClick

Click handler for the action button. Receives the document URL. Defaults to `window.open`.

|         |                         |
| ------- | ----------------------- |
| Type    | `(url: string) => void` |
| Default | `window.open`           |

***

### disabled

Disable the action button (e.g. for a thread header preview).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### className

Additional CSS class applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target              | Selector                                                                                  |
| ------------------- | ----------------------------------------------------------------------------------------- |
| Root                | `.cometchat-collaborative-bubble`                                                         |
| Document modifier   | `.cometchat-collaborative-bubble--document`                                               |
| Incoming / outgoing | `.cometchat-collaborative-bubble--incoming` / `.cometchat-collaborative-bubble--outgoing` |
| Banner image        | `.cometchat-collaborative-bubble__banner-image`                                           |
| Title               | `.cometchat-collaborative-bubble__body-content-name`                                      |
| Subtitle            | `.cometchat-collaborative-bubble__body-content-description`                               |
| Open button         | `.cometchat-collaborative-bubble__button`                                                 |

***

## Next Steps

<CardGroup>
  <Card title="Collaborative Document Plugin" icon="file-pen" href="/ui-kit/react/plugins/overview#built-in-plugins">
    Plugin behavior, context menu, and conversation preview
  </Card>

  <Card title="Collaborative Whiteboard Bubble" icon="chalkboard" href="/ui-kit/react/components/collaborative-whiteboard-bubble">
    Render collaborative whiteboard messages
  </Card>

  <Card title="Message Bubble" icon="comment" href="/ui-kit/react/components/message-bubble">
    The wrapper that hosts bubble content
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Collaborative Whiteboard Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/collaborative-whiteboard-bubble

A self-extracting bubble that renders a collaborative whiteboard card with a banner and an 'Open Whiteboard' button.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatCollaborativeWhiteboardBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatCollaborativeWhiteboardBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Self-extracting collaborative whiteboard bubble. Extracts the board URL from the message metadata and opens it on click.",
    "cssRootClass": ".cometchat-collaborative-bubble",
    "selfExtracting": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.BaseMessage", "required": true, "note": "Drives extraction of the board URL." },
        "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." },
        "onButtonClick": { "type": "(url: string) => void", "note": "Defaults to window.open." },
        "disabled": { "type": "boolean", "default": false },
        "className": { "type": "string" }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatCollaborativeWhiteboardBubble` renders a collaborative whiteboard card — a banner image, a title, a subtitle, and an "Open Whiteboard" button. It is **self-extracting**: pass the SDK `message` and the bubble reads the board URL from the message's extension metadata (`@injected.extensions.whiteboard.board_url`), so it works standalone. Clicking the button opens the whiteboard (by default in a new window).

<Info>
  **Live Preview** — interact with the collaborative whiteboard bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble--collaborative-whiteboard-message)
</Info>

<iframe title="CometChat Collaborative Whiteboard Bubble — Default" />

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCollaborativeWhiteboardBubble } from "@cometchat/chat-uikit-react";

function WhiteboardMessage({ message }: { message: CometChat.BaseMessage }) {
  return <CometChatCollaborativeWhiteboardBubble message={message} />;
}
```

***

## Props

### message

The collaborative-whiteboard message. The bubble extracts the URL from its metadata. **Required.**

|          |                         |
| -------- | ----------------------- |
| Type     | `CometChat.BaseMessage` |
| Required | Yes                     |

***

### alignment

Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user.

|         |                     |
| ------- | ------------------- |
| Type    | `"left" \| "right"` |
| Default | derived             |

***

### onButtonClick

Click handler for the action button. Receives the board URL. Defaults to `window.open`.

|         |                         |
| ------- | ----------------------- |
| Type    | `(url: string) => void` |
| Default | `window.open`           |

***

### disabled

Disable the action button (e.g. for a thread header preview).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### className

Additional CSS class applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target              | Selector                                                                                  |
| ------------------- | ----------------------------------------------------------------------------------------- |
| Root                | `.cometchat-collaborative-bubble`                                                         |
| Whiteboard modifier | `.cometchat-collaborative-bubble--whiteboard`                                             |
| Incoming / outgoing | `.cometchat-collaborative-bubble--incoming` / `.cometchat-collaborative-bubble--outgoing` |
| Banner image        | `.cometchat-collaborative-bubble__banner-image`                                           |
| Title               | `.cometchat-collaborative-bubble__body-content-name`                                      |
| Subtitle            | `.cometchat-collaborative-bubble__body-content-description`                               |
| Open button         | `.cometchat-collaborative-bubble__button`                                                 |

***

## Next Steps

<CardGroup>
  <Card title="Collaborative Whiteboard Plugin" icon="chalkboard" href="/ui-kit/react/plugins/overview#built-in-plugins">
    Plugin behavior, context menu, and conversation preview
  </Card>

  <Card title="Collaborative Document Bubble" icon="file-pen" href="/ui-kit/react/components/collaborative-document-bubble">
    Render collaborative document messages
  </Card>

  <Card title="Message Bubble" icon="comment" href="/ui-kit/react/components/message-bubble">
    The wrapper that hosts bubble content
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Conversations
Source: https://www.cometchat.com/docs/ui-kit/react/components/conversations

Scrollable list of recent one-on-one and group conversations for the logged-in user with real-time updates.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatConversations",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatConversations } from \"@cometchat/chat-uikit-react\";",
    "description": "Scrollable list of recent one-on-one and group conversations for the logged-in user with real-time updates.",
    "cssRootClass": ".cometchat-conversations",
    "primaryOutput": {
      "prop": "onItemClick",
      "type": "(conversation: CometChat.Conversation) => void"
    },
    "props": {
      "data": {
        "conversationsRequestBuilder": {
          "type": "CometChat.ConversationsRequestBuilder",
          "default": "SDK default (30 per page)",
          "note": "Pass the builder instance, not the result of .build()"
        },
        "searchRequestBuilder": {
          "type": "CometChat.ConversationsRequestBuilder",
          "default": "undefined"
        },
        "searchKeyword": {
          "type": "string",
          "default": "undefined"
        },
        "activeConversation": {
          "type": "CometChat.Conversation",
          "default": "undefined"
        },
        "lastMessageDateTimeFormat": {
          "type": "CometChatDateFormatConfig",
          "default": "hh:mm A today, Yesterday, dddd last week, DD/MM/YYYY older"
        }
      },
      "callbacks": {
        "onItemClick": "(conversation: CometChat.Conversation) => void",
        "onSelect": "(conversation: CometChat.Conversation, selected: boolean) => void",
        "onError": "((error: CometChat.CometChatException) => void) | null",
        "onEmpty": "() => void",
        "onSearchBarClicked": "() => void"
      },
      "visibility": {
        "hideReceipts": { "type": "boolean", "default": false },
        "hideUserStatus": { "type": "boolean", "default": false },
        "hideGroupType": { "type": "boolean", "default": false },
        "hideUnreadCount": { "type": "boolean", "default": false },
        "hideDeleteConversation": { "type": "boolean", "default": false },
        "showSearchBar": { "type": "boolean", "default": true },
        "showScrollbar": { "type": "boolean", "default": false }
      },
      "sound": {
        "disableSoundForMessages": { "type": "boolean", "default": false },
        "customSoundForMessages": { "type": "string", "default": "built-in" }
      },
      "selection": {
        "selectionMode": {
          "type": "CometChatConversationsSelectionMode",
          "values": ["'none'", "'single'", "'multiple'"],
          "default": "'none'"
        }
      },
      "viewSlots": {
        "itemView": "(conversation: CometChat.Conversation) => ReactNode",
        "leadingView": "(conversation: CometChat.Conversation) => ReactNode",
        "titleView": "(conversation: CometChat.Conversation) => ReactNode",
        "subtitleView": "(conversation: CometChat.Conversation) => ReactNode",
        "trailingView": "(conversation: CometChat.Conversation) => ReactNode",
        "headerView": "ReactNode",
        "searchView": "ReactNode",
        "loadingView": "ReactNode",
        "emptyView": "ReactNode",
        "errorView": "ReactNode",
        "options": "(conversation: CometChat.Conversation) => CometChatConversationOption[]"
      }
    },
    "events": [
      {
        "name": "ui:conversation/deleted",
        "payload": "{ conversation: CometChat.Conversation }",
        "description": "Conversation deleted from list"
      }
    ],
    "sdkListeners": [
      "onTextMessageReceived",
      "onMediaMessageReceived",
      "onCustomMessageReceived",
      "onInteractiveMessageReceived",
      "onTypingStarted",
      "onTypingEnded",
      "onMessagesDelivered",
      "onMessagesRead",
      "onUserOnline",
      "onUserOffline",
      "onGroupMemberJoined",
      "onGroupMemberLeft",
      "onGroupMemberKicked",
      "onGroupMemberBanned",
      "onMemberAddedToGroup"
    ],
    "types": {
      "CometChatDateFormatConfig": {
        "today": "string | undefined",
        "yesterday": "string | undefined",
        "lastWeek": "string | undefined",
        "otherDays": "string | undefined",
        "relativeTime": {
          "minute": "string | undefined",
          "minutes": "string | undefined",
          "hour": "string | undefined",
          "hours": "string | undefined"
        }
      },
      "CometChatConversationOption": {
        "id": "string",
        "title": "string",
        "iconURL": "string | undefined",
        "onClick": "(conversation: CometChat.Conversation) => void"
      },
      "CometChatConversationsSelectionMode": "'none' | 'single' | 'multiple'"
    }
  }
  ```
</Accordion>

## Overview

`CometChatConversations` is a sidebar list component. It renders recent conversations for the logged-in user and emits the selected `CometChat.Conversation` via `onItemClick`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a standard two-panel chat layout.

<Frame>
  <img />
</Frame>

<Info>
  **Live Preview** — interact with the default conversations list.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-conversations-cometchat-conversations--default)
</Info>

<iframe title="CometChatConversations — Default" />

The component handles:

* Paginated fetching with infinite scroll
* Real-time updates (new messages, typing indicators, presence changes)
* Search filtering
* Selection mode (single/multiple)

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react";

function Sidebar() {
  return (
    <CometChatConversations
      onItemClick={(conversation) => {
        const entity = conversation.getConversationWith();
        // Pass entity to MessageHeader, MessageList, MessageComposer
      }}
    />
  );
}
```

### Compound Composition

```tsx theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react";

function Sidebar() {
  return (
    <CometChatConversations.Root onItemClick={handleClick}>
      <CometChatConversations.Header title="Messages" />
      <CometChatConversations.SearchBar placeholder="Find a conversation..." />
      <CometChatConversations.LoadingState />
      <CometChatConversations.ErrorState />
      <CometChatConversations.EmptyState>
        <p>No conversations yet. Start a new chat!</p>
      </CometChatConversations.EmptyState>
      <CometChatConversations.List />
    </CometChatConversations.Root>
  );
}
```

### Full Layout Example

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

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

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setUser(entity as CometChat.User);
      setGroup(undefined);
    } else {
      setGroup(entity as CometChat.Group);
      setUser(undefined);
    }
  };

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>
      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        <CometChatMessageHeader user={user} group={group} />
        <CometChatMessageList user={user} group={group} />
        <CometChatMessageComposer user={user} group={group} />
      </div>
    </div>
  );
}
```

***

## Filtering

Pass a `CometChat.ConversationsRequestBuilder` to `conversationsRequestBuilder` to control which conversations load. Pass the builder instance — not the result of `.build()`. Refer to [ConversationsRequestBuilder](/docs/sdk/javascript/retrieve-conversations) for the full builder API.

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

### Search

The component includes a built-in search bar. When the user types, it filters conversations client-side by name. For server-side search, pass a `searchRequestBuilder`:

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

To use the search bar as a trigger for a custom search UI (like `CometChatSearch`), pass `onSearchBarClicked`:

```tsx theme={null}
<CometChatConversations
  onSearchBarClicked={() => openGlobalSearch()}
/>
```

### Filter Recipes

| Recipe            | Code                                                                       |
| ----------------- | -------------------------------------------------------------------------- |
| Only 1-on-1 chats | `new CometChat.ConversationsRequestBuilder().setConversationType("user")`  |
| Only group chats  | `new CometChat.ConversationsRequestBuilder().setConversationType("group")` |
| Limit page size   | `new CometChat.ConversationsRequestBuilder().setLimit(10)`                 |
| With tags         | `new CometChat.ConversationsRequestBuilder().setTags(["support"])`         |

***

## Actions and Events

### Callback Props

| Prop                 | Signature                                                           | Fires when                                        |
| -------------------- | ------------------------------------------------------------------- | ------------------------------------------------- |
| `onItemClick`        | `(conversation: CometChat.Conversation) => void`                    | User clicks a conversation item                   |
| `onSelect`           | `(conversation: CometChat.Conversation, selected: boolean) => void` | Conversation selected/deselected (selection mode) |
| `onError`            | `((error: CometChat.CometChatException) => void) \| null`           | SDK error occurs                                  |
| `onEmpty`            | `() => void`                                                        | List is empty after initial fetch                 |
| `onSearchBarClicked` | `() => void`                                                        | Search bar is clicked (makes input read-only)     |

### Events Emitted

UI events this component publishes:

| Event                     | Payload            | Fires when                  |
| ------------------------- | ------------------ | --------------------------- |
| `ui:conversation/deleted` | `{ conversation }` | User deletes a conversation |

### Events Received

UI events this component subscribes to (published by other components):

| Event                      | Payload                        | Behavior                                                             |
| -------------------------- | ------------------------------ | -------------------------------------------------------------------- |
| `ui:message/sent`          | `{ message, status }`          | Moves conversation to top, updates last message, resets unread count |
| `ui:compose/edit`          | `{ message, status }`          | Updates the conversation's last message                              |
| `ui:message/deleted`       | `{ message }`                  | Updates the conversation's last message                              |
| `ui:message/read`          | `{ message }`                  | Resets unread count for that conversation                            |
| `ui:conversation/updated`  | `{ conversation }`             | Updates the conversation in the list                                 |
| `ui:conversation/read`     | `{ conversationId }`           | Resets unread count by conversation ID                               |
| `ui:conversation/deleted`  | `{ conversation }`             | Removes the conversation from the list                               |
| `ui:group/created`         | `{ group }`                    | Adds the new group conversation to the list                          |
| `ui:group/deleted`         | `{ group }`                    | Removes the group conversation from the list                         |
| `ui:group/left`            | `{ group }`                    | Removes the group conversation from the list                         |
| `ui:group/member-added`    | `{ group, members, messages }` | Updates last message and moves to top                                |
| `ui:group/member-kicked`   | `{ group, member, message }`   | Updates last message and moves to top                                |
| `ui:group/member-banned`   | `{ group, member, message }`   | Updates last message and moves to top                                |
| `ui:group/member-unbanned` | `{ group, member, message }`   | Updates last message and moves to top                                |

### SDK Listeners (Automatic)

These SDK listeners are attached internally. The component updates its state automatically — no manual subscription needed:

* Message listeners: `onTextMessageReceived`, `onMediaMessageReceived`, `onCustomMessageReceived`, `onInteractiveMessageReceived`
* Typing: `onTypingStarted`, `onTypingEnded`
* Receipts: `onMessagesDelivered`, `onMessagesRead`
* Presence: `onUserOnline`, `onUserOffline`
* Groups: `onGroupMemberJoined`, `onGroupMemberLeft`, `onGroupMemberKicked`, `onGroupMemberBanned`, `onMemberAddedToGroup`

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatConversations
  headerView={<MyCustomHeader />}
  itemView={(conversation) => <MyCustomItem conversation={conversation} />}
  emptyView={<EmptyState />}
  loadingView={<Skeleton />}
  errorView={<ErrorBanner />}
/>
```

| Slot           | Signature                     | Replaces                 |
| -------------- | ----------------------------- | ------------------------ |
| `itemView`     | `(conversation) => ReactNode` | Entire conversation row  |
| `leadingView`  | `(conversation) => ReactNode` | Avatar section           |
| `titleView`    | `(conversation) => ReactNode` | Conversation name        |
| `subtitleView` | `(conversation) => ReactNode` | Last message preview     |
| `trailingView` | `(conversation) => ReactNode` | Timestamp + unread badge |
| `headerView`   | `ReactNode`                   | Header area              |
| `searchView`   | `ReactNode`                   | Search bar               |
| `loadingView`  | `ReactNode`                   | Loading shimmer          |
| `emptyView`    | `ReactNode`                   | Empty state              |
| `errorView`    | `ReactNode`                   | Error state              |

#### itemView

Replace the entire list item row.

Default:

<Frame>
  <img />
</Frame>

Customized:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import {
      CometChatConversations,
      CometChatAvatar,
      CometChatDate,
    } from "@cometchat/chat-uikit-react";

    function CustomItemViewConversations() {
      const getItemView = (conversation: CometChat.Conversation) => {
        const title = conversation.getConversationWith().getName();
        const timestamp = conversation?.getLastMessage()?.getSentAt();

        return (
          <div className="conversations__custom-item">
            <CometChatAvatar.Root name={title}>
              <CometChatAvatar.Image />
              <CometChatAvatar.Initials />
            </CometChatAvatar.Root>
            <span className="conversations__custom-item-title">{title}</span>
            {timestamp ? (
              <CometChatDate.Root timestamp={timestamp}>
                <CometChatDate.Text />
              </CometChatDate.Root>
            ) : null}
          </div>
        );
      };

      return <CometChatConversations itemView={getItemView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .conversations__custom-item {
      display: flex;
      align-items: center;
      gap: 8px;
      padding: 8px 16px;
      width: 100%;
    }

    .conversations__custom-item-title {
      flex: 1;
      font: 500 16px/19.2px Roboto;
      color: #141414;
    }

    .cometchat-conversations .cometchat-avatar {
      border-radius: 8px;
      width: 32px;
      height: 32px;
    }
    ```
  </Tab>
</Tabs>

#### leadingView

Replace the avatar / left section. Typing-aware avatar example.

<Frame>
  <img />
</Frame>

```tsx theme={null}
import { useEffect, useRef, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatConversations,
  CometChatAvatar,
  useLoggedInUser,
} from "@cometchat/chat-uikit-react";

function TypingAwareConversations() {
  const [isTyping, setIsTyping] = useState(false);
  const typingObjRef = useRef<CometChat.TypingIndicator | null>(null);
  const loggedInUser = useLoggedInUser();

  useEffect(() => {
    const listenerId = "typing_demo_" + Date.now();
    CometChat.addMessageListener(
      listenerId,
      new CometChat.MessageListener({
        onTypingStarted: (typingIndicator: CometChat.TypingIndicator) => {
          typingObjRef.current = typingIndicator;
          setIsTyping(true);
        },
        onTypingEnded: (typingIndicator: CometChat.TypingIndicator) => {
          if (
            typingObjRef.current &&
            typingObjRef.current.getSender().getUid() ===
              typingIndicator.getSender().getUid()
          ) {
            typingObjRef.current = null;
            setIsTyping(false);
          }
        },
      })
    );
    return () => {
      CometChat.removeMessageListener(listenerId);
    };
  }, []);

  const getLeadingView = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    const isUser = entity instanceof CometChat.User;
    const isGroup = entity instanceof CometChat.Group;

    const isMyTyping = isUser
      ? (entity as CometChat.User).getUid() ===
          typingObjRef.current?.getSender().getUid() &&
        loggedInUser?.getUid() === typingObjRef.current?.getReceiverId()
      : isGroup &&
        (entity as CometChat.Group).getGuid() ===
          typingObjRef.current?.getReceiverId();

    const avatar = isUser
      ? (entity as CometChat.User).getAvatar()
      : (entity as CometChat.Group).getIcon();

    return (
      <div className="conversations__leading-view">
        <CometChatAvatar.Root
          image={isTyping && isMyTyping ? undefined : avatar}
          name={isTyping && isMyTyping ? undefined : entity.getName()}
        >
          <CometChatAvatar.Image />
          <CometChatAvatar.Initials />
        </CometChatAvatar.Root>
      </div>
    );
  };

  return <CometChatConversations leadingView={getLeadingView} />;
}
```

#### titleView

Replace the name / title text. Inline user status example.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatConversations } from "@cometchat/chat-uikit-react";

    function StatusTitleConversations() {
      const getTitleView = (conversation: CometChat.Conversation) => {
        const user =
          conversation.getConversationType() === "user"
            ? (conversation.getConversationWith() as CometChat.User)
            : undefined;

        return (
          <div className="conversations__title-view">
            <span className="conversations__title-view-name">
              {user
                ? conversation.getConversationWith().getName() + " · "
                : conversation.getConversationWith().getName()}
            </span>
            {user && (
              <span className="conversations__title-view-status">
                {user.getStatusMessage()}
              </span>
            )}
          </div>
        );
      };

      return <CometChatConversations titleView={getTitleView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-conversations .conversations__title-view {
      display: flex;
      gap: 4px;
      width: 100%;
    }

    .conversations__title-view-name {
      color: #141414;
      font: 500 16px/19.2px Roboto;
    }

    .conversations__title-view-status {
      color: #6852d6;
      font: 400 16px/19.2px Roboto;
    }
    ```
  </Tab>
</Tabs>

#### subtitleView

Replace the last message preview text.

Default:

<Frame>
  <img />
</Frame>

Customized:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatConversations } from "@cometchat/chat-uikit-react";

    function formatTimestamp(timestamp: number): string {
      return new Date(timestamp * 1000).toLocaleString();
    }

    function SubtitleConversations() {
      const getSubtitleView = (conversation: CometChat.Conversation) => {
        if (conversation.getConversationType() === "user") {
          return (
            <span className='custom-conversation-subtitle'>
              Last active:{" "}
              {new Date(
                (conversation.getConversationWith() as CometChat.User).getLastActiveAt() * 1000
              ).toLocaleString()}
            </span>
          );
        }
        return (
          <span className='custom-conversation-subtitle'>
            Created:{" "}
            {new Date(
              (conversation.getConversationWith() as CometChat.Group).getCreatedAt() * 1000
            ).toLocaleString()}
          </span>
        );
      };

      return <CometChatConversations subtitleView={getSubtitleView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .custom-conversation-subtitle {
      overflow: hidden;
      color: grey;
      text-overflow: ellipsis;
      white-space: nowrap;
      font: var(--cometchat-font-body-regular);
    }
    ```
  </Tab>
</Tabs>

#### trailingView

Replace the timestamp / badge / right section. Relative time badge example.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatConversations } from "@cometchat/chat-uikit-react";

    function RelativeTimeConversations() {
      const getTrailingView = (conv: CometChat.Conversation) => {
        if (!conv.getLastMessage()) return <></>;

        const timestamp = conv.getLastMessage()?.getSentAt() * 1000;
        const now = Date.now();
        const diffInMinutes = Math.floor((now - timestamp) / (1000 * 60));
        const diffInHours = Math.floor((now - timestamp) / (1000 * 60 * 60));

        let className = "conversations__trailing-view-min";
        let topLabel = `${diffInMinutes}`;
        let bottomLabel = diffInMinutes === 1 ? "Min ago" : "Mins ago";

        if (diffInHours >= 1 && diffInHours <= 10) {
          className = "conversations__trailing-view-hour";
          topLabel = `${diffInHours}`;
          bottomLabel = diffInHours === 1 ? "Hour ago" : "Hours ago";
        } else if (diffInHours > 10) {
          className = "conversations__trailing-view-date";
          const time = new Date(timestamp);
          topLabel = time.toLocaleDateString("en-US", { day: "numeric" });
          bottomLabel = time.toLocaleDateString("en-US", { month: "short", year: "numeric" });
        }

        return (
          <div className={`conversations__trailing-view ${className}`}>
            <span className="conversations__trailing-view-time">{topLabel}</span>
            <span className="conversations__trailing-view-status">{bottomLabel}</span>
          </div>
        );
      };

      return <CometChatConversations trailingView={getTrailingView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .conversations__trailing-view {
      display: flex;
      flex-direction: column;
      align-items: center;
      justify-content: center;
      width: 55px;
      height: 40px;
      border-radius: 8px;
      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
    }

    .conversations__trailing-view-min { background-color: #e0d4f7; }
    .conversations__trailing-view-hour { background-color: #fff3cd; }
    .conversations__trailing-view-date { background-color: #f8d7da; }

    .conversations__trailing-view-time {
      font: 600 18px Roboto;
      color: #4a3f99;
      margin-bottom: 4px;
    }

    .conversations__trailing-view-status {
      font: 600 8px Roboto;
      color: #6a5b99;
    }

    .cometchat-conversations .cometchat-list-item__trailing-view {
      height: 50px;
    }
    ```
  </Tab>
</Tabs>

#### headerView

Replace the entire header bar.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import {
      CometChatButton,
      CometChatConversations,
      useLocale,
    } from "@cometchat/chat-uikit-react";

    function CustomHeaderConversations() {
      const { getLocalizedString } = useLocale();

      return (
        <CometChatConversations
          headerView={
            <div className="conversations__header">
              <div className="conversations__header__title">
                {getLocalizedString("chats")}
              </div>
              <CometChatButton.Root onClick={() => { /* handle click */ }}>
                <CometChatButton.Icon />
              </CometChatButton.Root>
            </div>
          }
        />
      );
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .conversations__header {
      display: flex;
      width: 100%;
      padding: 8px 16px;
      align-items: center;
      justify-content: space-between;
      gap: 12px;
      border-radius: 10px;
      border: 1px solid #e8e8e8;
      background: #edeafa;
    }

    .conversations__header__title {
      overflow: hidden;
      color: #141414;
      text-overflow: ellipsis;
      font: 700 24px Roboto;
    }

    .conversations__header .cometchat-button .cometchat-button__icon {
      background: #141414;
    }

    .conversations__header .cometchat-button {
      width: 24px;
      border: none;
      background: transparent;
      border-radius: 0;
    }
    ```
  </Tab>
</Tabs>

#### options

Replace the context menu / hover actions on each conversation item.

Default:

<Frame>
  <img />
</Frame>

Customized:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import {
      CometChatConversations,
      type CometChatConversationOption,
    } from "@cometchat/chat-uikit-react";

    function CustomOptionsConversations() {
      const getOptions = (conversation: CometChat.Conversation): CometChatConversationOption[] => [
        {
          id: "delete",
          title: "Delete",
          onClick: (conv) => { /* delete logic */ },
        },
        {
          id: "mute",
          title: "Mute Notification",
          onClick: (conv) => { /* mute logic */ },
        },
        {
          id: "unread",
          title: "Mark as Unread",
          onClick: (conv) => { /* mark unread logic */ },
        },
        {
          id: "block",
          title: "Block",
          onClick: (conv) => { /* block logic */ },
        },
      ];

      return <CometChatConversations options={getOptions} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-conversations .cometchat-menu-list__main-menu-item-icon-delete {
      background: red;
    }

    .cometchat-conversations .cometchat-menu-list__sub-menu {
      background: transparent;
      box-shadow: none;
    }
    ```
  </Tab>
</Tabs>

### Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

```tsx theme={null}
<CometChatConversations.Root onItemClick={handleClick}>
  {/* No Header or SearchBar — they won't render */}
  <CometChatConversations.List />
</CometChatConversations.Root>
```

Available sub-components:

| Sub-component  | Description                    | Props                                                                   | Flat API equivalent |
| -------------- | ------------------------------ | ----------------------------------------------------------------------- | ------------------- |
| `Root`         | Context provider and container | All Root props + `children`                                             | —                   |
| `List`         | Scrollable conversation list   | `itemView`, `className`                                                 | `itemView`          |
| `Item`         | Individual conversation row    | `leadingView`, `titleView`, `subtitleView`, `trailingView`, `className` | Per-item view props |
| `Header`       | Header area                    | `title`, `children`                                                     | `headerView`        |
| `SearchBar`    | Search input                   | `placeholder`, `onClick`                                                | `searchView`        |
| `EmptyState`   | Empty state                    | `children`                                                              | `emptyView`         |
| `ErrorState`   | Error state                    | `children`                                                              | `errorView`         |
| `LoadingState` | Loading shimmer                | `children`                                                              | `loadingView`       |

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-conversations {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-conversations__item--active {
  background: var(--cometchat-primary-color);
}
```

***

## Props

All props are optional.

<Note>
  View slot props (`headerView`, `searchView`, `loadingView`, `emptyView`, `errorView`, `itemView`, `leadingView`, `titleView`, `subtitleView`, `trailingView`) are convenience props available only on the flat API. In compound composition mode, use the corresponding sub-components directly.
</Note>

***

### conversationsRequestBuilder

Custom request builder for fetching conversations. Controls pagination, filtering, and sorting.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `CometChat.ConversationsRequestBuilder` |
| Default | SDK default (limit 30)                  |

***

### searchRequestBuilder

Custom request builder used specifically when the user searches. Separate from the main builder.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `CometChat.ConversationsRequestBuilder` |
| Default | `undefined`                             |

***

### searchKeyword

Initial search keyword to pre-filter conversations on mount.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### activeConversation

The currently active/highlighted conversation. The matching item receives an active visual state.

|         |                          |
| ------- | ------------------------ |
| Type    | `CometChat.Conversation` |
| Default | `undefined`              |

***

### lastMessageDateTimeFormat

Custom date/time format for the last message timestamp shown in each conversation item.

|         |                                                                                           |
| ------- | ----------------------------------------------------------------------------------------- |
| Type    | `CometChatDateFormatConfig`                                                               |
| Default | `{ today: 'hh:mm A', yesterday: 'Yesterday', lastWeek: 'dddd', otherDays: 'DD/MM/YYYY' }` |

***

### hideReceipts

Hide message delivery/read receipts (double ticks) on conversation items.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideUserStatus

Hide the online/offline status indicator on user avatars.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideGroupType

Hide the group type indicator (public/private/password) on group conversation items.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideUnreadCount

Hide the unread message count badge.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideDeleteConversation

Hide the delete option in the conversation item's context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showSearchBar

Whether to show the search bar. Set to `false` to hide it entirely.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### showScrollbar

Show the native scrollbar on the conversation list.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### selectionMode

Enable selection mode for multi-select operations.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `'none' \| 'single' \| 'multiple'` |
| Default | `'none'`                           |

***

### disableSoundForMessages

Disable the notification sound when new messages arrive.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### customSoundForMessages

Custom sound URL to play when new messages arrive (replaces the built-in sound).

|         |                             |
| ------- | --------------------------- |
| Type    | `string`                    |
| Default | Built-in notification sound |

***

### options

Function that returns context menu options for each conversation item (shown on hover/swipe).

|         |                                                                           |
| ------- | ------------------------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => CometChatConversationOption[]` |
| Default | Default options (delete)                                                  |

```tsx theme={null}
<CometChatConversations
  options={(conversation) => [
    {
      id: "pin",
      title: "Pin",
      iconURL: pinIcon,
      onClick: (conv) => pinConversation(conv),
    },
    {
      id: "mute",
      title: "Mute",
      iconURL: muteIcon,
      onClick: (conv) => muteConversation(conv),
    },
  ]}
/>
```

***

### onItemClick

Callback when a conversation item is clicked.

|         |                                                  |
| ------- | ------------------------------------------------ |
| Type    | `(conversation: CometChat.Conversation) => void` |
| Default | `undefined`                                      |

***

### onSelect

Callback when a conversation is selected or deselected (only fires in selection mode).

|         |                                                                     |
| ------- | ------------------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation, selected: boolean) => void` |
| Default | `undefined`                                                         |

***

### onError

Callback when an SDK error occurs during fetch or real-time operations.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `null`                                                    |

***

### onEmpty

Callback when the conversation list is empty after the initial fetch completes.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onSearchBarClicked

Callback when the search bar is clicked. When provided, the search input becomes read-only and acts as a trigger (useful for opening a global search component like `CometChatSearch`).

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

## CSS Architecture

The component uses CSS custom properties (design tokens) that are bundled with `@cometchat/chat-uikit-react`. The cascade:

1. Global tokens (e.g., `--cometchat-primary-color`, `--cometchat-background-color-01`) are set on the `.cometchat` root wrapper.
2. Component CSS (`.cometchat-conversations`) consumes these tokens via `var()` with fallback values.
3. Overrides target `.cometchat-conversations` descendant selectors in a global stylesheet.

To scope overrides to a single instance when multiple `CometChatConversations` exist on the same page, wrap the component in a container and scope selectors:

```css theme={null}
.sidebar-left .cometchat-conversations .cometchat-badge {
  background: #e5484d;
}
```

Overrides survive component updates because the component never sets inline styles on these elements — all styling flows through CSS classes and custom properties.

### Key Selectors

| Target           | Selector                                                           |
| ---------------- | ------------------------------------------------------------------ |
| Root             | `.cometchat-conversations`                                         |
| Header title     | `.cometchat-conversations .cometchat-list__header-title`           |
| List item        | `.cometchat-conversations .cometchat-list-item`                    |
| Body title       | `.cometchat-conversations .cometchat-list-item__body-title`        |
| Avatar           | `.cometchat-conversations .cometchat-avatar`                       |
| Avatar text      | `.cometchat-conversations .cometchat-avatar__text`                 |
| Unread badge     | `.cometchat-conversations .cometchat-badge`                        |
| Subtitle text    | `.cometchat-conversations .cometchat-conversations__subtitle-text` |
| Status indicator | `.cometchat-conversations .cometchat-status-indicator`             |
| Read receipts    | `.cometchat-conversations .cometchat-receipts-read`                |
| Active item      | `.cometchat-conversations__list-item-active .cometchat-list-item`  |
| Typing indicator | `.cometchat-conversations__subtitle-typing`                        |
| Trailing view    | `.cometchat-conversations__trailing-view`                          |

### Example: Brand-themed conversations

<Frame>
  <img />
</Frame>

```css theme={null}
.cometchat-conversations .cometchat-conversations__item-title,
.cometchat-conversations .cometchat-conversations__header-title,
.cometchat-conversations .cometchat-avatar__text,
.cometchat-conversations .cometchat-conversations__item-unread-badge,
.cometchat-conversations .cometchat-conversations__item-subtitle-text {
  font-family: "SF Pro";
}

.cometchat-conversations .cometchat-conversations__header {
  background: #fef8f8;
  border-bottom: 2px solid #f4b6b8;
}

.cometchat-conversations .cometchat-avatar {
  background: #FAAA75;
}

.cometchat-conversations .cometchat-status-indicator {
  min-width: 10px;
  height: 10px;
}

.cometchat-conversations .cometchat-conversations__item-unread-badge {
  background: #F76809;
}

.cometchat-conversations .cometchat-conversations__item-receipt--read {
  background: #FAAA75;
}
```

### Customization Matrix

| What to change                        | Where           | Property/API                            | Example                                                                                  |
| ------------------------------------- | --------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- |
| Override behavior on user interaction | Component props | `on<Event>` callbacks                   | `onItemClick={(c) => setActive(c)}`                                                      |
| Filter which conversations appear     | Component props | `conversationsRequestBuilder`           | `conversationsRequestBuilder={new CometChat.ConversationsRequestBuilder().setLimit(10)}` |
| Toggle visibility of UI elements      | Component props | `hide<Feature>` boolean props           | `hideReceipts={true}`                                                                    |
| Replace a section of the list item    | Component props | `<slot>View` render props               | `itemView={(conversation) => <div>...</div>}`                                            |
| Change colors, fonts, spacing         | Global CSS      | Target `.cometchat-conversations` class | `.cometchat-conversations .cometchat-badge { background: #e5484d; }`                     |

***

## Next Steps

<CardGroup>
  <Card title="Users" icon="user" href="/ui-kit/react/components/users">
    Browse and select users for new conversations
  </Card>

  <Card title="Message List" icon="comments" href="/ui-kit/react/components/message-list">
    Display messages for the selected conversation
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/ui-kit/react/components/search">
    Search across conversations and messages
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Delete Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/delete-bubble

A presentational bubble that renders a 'This message was deleted' placeholder.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatDeleteBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatDeleteBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Presentational placeholder bubble for deleted messages.",
    "cssRootClass": ".cometchat-delete-bubble",
    "props": {
      "data": {
        "isSentByMe": { "type": "boolean", "note": "Affects sent vs received styling." },
        "text": { "type": "string", "note": "Defaults to localized \"This message was deleted\"." },
        "className": { "type": "string" }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatDeleteBubble` renders the placeholder shown in place of a deleted message — italic, muted text reading "This message was deleted". It is a presentational component: pass `isSentByMe` for sent-vs-received styling and an optional `text` override. The [Delete Plugin](/docs/ui-kit/react/plugins/overview#built-in-plugins) renders it automatically for any message whose `getDeletedAt()` is non-null.

<Info>
  **Live Preview** — interact with the delete bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/base-elements-delete-bubble--default)
</Info>

<iframe title="CometChat Delete Bubble — Default" />

***

## Usage

```tsx theme={null}
import { CometChatDeleteBubble } from "@cometchat/chat-uikit-react";

function DeletedMessage() {
  return <CometChatDeleteBubble isSentByMe={false} />;
}
```

***

## Props

### isSentByMe

Whether the deleted message was sent by the logged-in user. Affects styling.

|         |             |
| ------- | ----------- |
| Type    | `boolean`   |
| Default | `undefined` |

***

### text

Optional custom text override. Defaults to the localized "This message was deleted".

|         |                   |
| ------- | ----------------- |
| Type    | `string`          |
| Default | localized default |

***

### className

Additional CSS class applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target            | Selector                                                                  |
| ----------------- | ------------------------------------------------------------------------- |
| Root              | `.cometchat-delete-bubble`                                                |
| Sender / receiver | `.cometchat-delete-bubble--sender` / `.cometchat-delete-bubble--receiver` |
| Icon              | `.cometchat-delete-bubble__icon`                                          |
| Placeholder text  | `.cometchat-delete-bubble__text`                                          |

***

## Next Steps

<CardGroup>
  <Card title="Delete Plugin" icon="trash" href="/ui-kit/react/plugins/overview#built-in-plugins">
    How deleted messages are resolved and rendered
  </Card>

  <Card title="Message Bubble" icon="comment" href="/ui-kit/react/components/message-bubble">
    The wrapper that hosts bubble content
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# File Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/file-bubble

A batch-aware bubble that renders one or more generic file attachments with file-type icons, metadata, download, and a collapsible list.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatFilesBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatFilesBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Batch-aware file bubble. Extracts file attachments and caption from a MediaMessage; renders stacked file cards with type icons, name, size, extension, and download. Collapses to 3 cards with '+N more' expander.",
    "cssRootClass": ".cometchat-files-bubble",
    "selfExtracting": true,
    "multiAttachment": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of file attachments and caption." },
        "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." },
        "textFormatters": { "type": "CometChatTextFormatter[]" },
        "className": { "type": "string" }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatFilesBubble` renders generic file attachment(s) as stacked file cards. It is **self-extracting**: pass the SDK `message` and the bubble derives the file attachments and caption itself. The message list uses it automatically for file messages.

Key capabilities:

* **Stacked file cards** — one card per file with type icon, filename, extension label, and file size
* **File-type icons** — recognizes PDF, Word, Excel, PowerPoint, text, zip, audio, video, and image extensions
* **Collapsible list** — shows up to 3 files initially, with a "+N more" toggle to expand
* **Download button** — download individual files
* **Batch grouping** — rendered as one connected group when several media messages are sent together (handled by the [message list](/docs/ui-kit/react/components/message-list#multi-attachment-batch-grouping))
* **Caption support** — optional caption rendered below the cards

<Info>
  **Live Preview** — interact with the file bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble-files--two-files)
</Info>

<iframe title="CometChat File Bubble — Two Files" />

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatFilesBubble } from "@cometchat/chat-uikit-react";

function FileMessage({ message }: { message: CometChat.MediaMessage }) {
  return <CometChatFilesBubble message={message} />;
}
```

***

## File Card Layout

Each attachment renders as a card with:

| Element         | Description                                        |
| --------------- | -------------------------------------------------- |
| File-type icon  | Color-coded icon based on file extension           |
| Filename        | Display name of the file                           |
| Meta label      | Extension (uppercase) and human-readable file size |
| Download button | Downloads the file                                 |

When a message has more than 3 file attachments, the list is initially collapsed with a toggle showing "+N more". Clicking the toggle expands to show all files.

### Supported File-Type Icons

| Icon        | Extensions                                                        |
| ----------- | ----------------------------------------------------------------- |
| PDF         | `pdf`                                                             |
| Word        | `doc`, `docx`                                                     |
| Excel       | `xls`, `xlsx`, `csv`                                              |
| PowerPoint  | `ppt`, `pptx`                                                     |
| Text        | `txt`, `rtf`                                                      |
| Archive     | `zip`, `rar`, `7z`, `gz`                                          |
| Audio       | `mp3`, `wav`, `m4a`, `aac`, `ogg`                                 |
| Video       | `mov`, `mp4`, `avi`, `mkv`                                        |
| Image       | `jpg`, `jpeg`, `png`, `gif`, `webp`, `bmp`, `svg`, `heic`, `heif` |
| Unsupported | All other extensions                                              |

<iframe title="CometChat File Bubble — Five Files Expand" />

***

## Props

### message

The file message. The bubble extracts its attachments and caption from it. **Required.**

|          |                          |
| -------- | ------------------------ |
| Type     | `CometChat.MediaMessage` |
| Required | Yes                      |

***

### alignment

Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user.

|         |                     |
| ------- | ------------------- |
| Type    | `"left" \| "right"` |
| Default | derived             |

***

### textFormatters

Text formatters applied to the caption (mentions, URLs).

|         |                            |
| ------- | -------------------------- |
| Type    | `CometChatTextFormatter[]` |
| Default | `undefined`                |

***

### className

Additional CSS class applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target                  | Selector                                    |
| ----------------------- | ------------------------------------------- |
| Root                    | `.cometchat-files-bubble`                   |
| Incoming variant        | `.cometchat-files-bubble--incoming`         |
| Outgoing variant        | `.cometchat-files-bubble--outgoing`         |
| Container               | `.cometchat-files-bubble__container`        |
| Multi-card container    | `.cometchat-files-bubble__container--multi` |
| File card               | `.cometchat-files-bubble__card`             |
| File-type icon wrapper  | `.cometchat-files-bubble__card-icon`        |
| File-type icon image    | `.cometchat-files-bubble__card-icon-img`    |
| Card text area          | `.cometchat-files-bubble__card-text`        |
| Filename                | `.cometchat-files-bubble__card-name`        |
| Meta (extension + size) | `.cometchat-files-bubble__card-meta`        |
| Expand/collapse toggle  | `.cometchat-files-bubble__toggle`           |
| Caption                 | `.cometchat-files-bubble__caption`          |

***

## Next Steps

<CardGroup>
  <Card title="Image Bubble" icon="image" href="/ui-kit/react/components/image-bubble">
    Batch-aware image bubble with grid layouts
  </Card>

  <Card title="Audio Bubble" icon="music" href="/ui-kit/react/components/audio-bubble">
    Batch-aware audio bubble with player cards
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/react/components/message-list">
    Multi-attachment batch grouping in the list
  </Card>

  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/react/components/message-composer">
    Multi-attachment staging tray
  </Card>
</CardGroup>


# Flag Message Dialog
Source: https://www.cometchat.com/docs/ui-kit/react/components/flag-message-dialog

A dialog for reporting inappropriate messages with reason selection, an optional remark, and submission handling.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatFlagMessageDialog",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatFlagMessageDialog } from \"@cometchat/chat-uikit-react\";",
    "description": "Dialog for reporting/flagging an inappropriate message. Fetches flag reasons from the SDK, captures an optional remark, and submits the report.",
    "cssRootClass": ".cometchat-flag-message-dialog",
    "primaryOutput": {
      "prop": "onSubmit",
      "type": "(messageId: string, reasonId: string, remark?: string) => Promise<boolean>"
    },
    "props": {
      "data": {
        "message": { "type": "CometChat.BaseMessage", "note": "Required. The message being flagged." },
        "isOpen": { "type": "boolean", "note": "When provided, the dialog is controlled." }
      },
      "callbacks": {
        "onSubmit": { "type": "(messageId: string, reasonId: string, remark?: string) => Promise<boolean>", "note": "Return true to close, false to keep open and show an error." },
        "onClose": { "type": "() => void" },
        "onError": { "type": "((error: CometChat.CometChatException) => void) | null" }
      },
      "config": {
        "closeOnOutsideClick": { "type": "boolean", "default": true },
        "className": { "type": "string" }
      }
    },
    "types": {
      "CometChatFlagMessageDialogRootProps": "Root overlay props",
      "CometChatFlagMessageDialogHeaderProps": "Header sub-component props",
      "CometChatFlagMessageDialogReasonsProps": "Reasons list sub-component props",
      "CometChatFlagMessageDialogRemarkProps": "Remark input sub-component props",
      "CometChatFlagMessageDialogActionsProps": "Actions (cancel/submit) sub-component props",
      "CometChatFlagMessageDialogContextValue": "Full context value"
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatFlagMessageDialog` is a modal dialog that lets a user report an inappropriate message. When it opens, it fetches the available report reasons from the SDK (`CometChat.getFlagReasons`), renders them as a single-select list, captures an optional free-text remark, and—on submit—invokes your `onSubmit` handler with the message ID, the selected reason ID, and the remark.

<Info>
  **Live Preview** — interact with the flag message dialog.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-misc-flag-message-dialog--default)
</Info>

<iframe title="CometChat Flag Message Dialog — Default" />

Use it when a user chooses "Report" on a message. The parent owns the open state and decides what happens with the report inside `onSubmit` (e.g., calling a moderation backend).

```tsx lines theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatFlagMessageDialog } from "@cometchat/chat-uikit-react";

function FlagMessageExample({ message }: { message: CometChat.BaseMessage }) {
  const [open, setOpen] = useState(false);

  const handleSubmit = async (
    messageId: string,
    reasonId: string,
    remark?: string
  ) => {
    // Report the message to your backend / moderation service.
    console.log("Reporting", { messageId, reasonId, remark });
    return true; // return false to keep the dialog open and show an error
  };

  return (
    <>
      <button onClick={() => setOpen(true)}>Report message</button>

      <CometChatFlagMessageDialog
        message={message}
        isOpen={open}
        onClose={() => setOpen(false)}
        onSubmit={handleSubmit}
      />
    </>
  );
}
```

## Minimal Render

```tsx lines theme={null}
import { CometChatFlagMessageDialog } from "@cometchat/chat-uikit-react";

function Demo({ message }) {
  return <CometChatFlagMessageDialog message={message} isOpen />;
}
```

Root CSS class: `.cometchat-flag-message-dialog`

## Sub-Components

`CometChatFlagMessageDialog` is a compound component with these sub-components:

| Sub-Component | Purpose                                                                                                                                                                            |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Root`        | Overlay and context provider. Manages open/close state, focus trap, outside-click/Escape, reason fetching, and submission. Renders the default layout when no children are passed. |
| `Header`      | Title and subtitle. Defaults to a localized "Report a Message" heading.                                                                                                            |
| `Reasons`     | Single-select list of report reasons fetched from the SDK.                                                                                                                         |
| `Remark`      | Optional free-text input with a character counter (default max 500).                                                                                                               |
| `Actions`     | Cancel and submit (Report) buttons.                                                                                                                                                |

### Custom Layout

Compose sub-components to customize the layout — for example, omit `Remark` to collect only a reason:

```tsx lines theme={null}
<CometChatFlagMessageDialog.Root
  message={message}
  isOpen={open}
  onClose={() => setOpen(false)}
  onSubmit={handleSubmit}
>
  <CometChatFlagMessageDialog.Header />
  <CometChatFlagMessageDialog.Reasons />
  <CometChatFlagMessageDialog.Remark />
  <CometChatFlagMessageDialog.Actions />
</CometChatFlagMessageDialog.Root>
```

### Custom Header

Pass `title`/`subtitle` for text changes, or `children` for fully custom header content:

```tsx lines theme={null}
<CometChatFlagMessageDialog.Root message={message} isOpen={open} onClose={onClose}>
  <CometChatFlagMessageDialog.Header>
    <div style={{ textAlign: "center" }}>
      <h3>Custom Report Header</h3>
      <p>This uses children instead of title/subtitle props.</p>
    </div>
  </CometChatFlagMessageDialog.Header>
  <CometChatFlagMessageDialog.Reasons />
  <CometChatFlagMessageDialog.Actions />
</CometChatFlagMessageDialog.Root>
```

Sub-component props:

| Sub-component | Prop          | Type     | Default                          |
| ------------- | ------------- | -------- | -------------------------------- |
| `Header`      | `title`       | `string` | `"Report a Message"` (localized) |
| `Header`      | `subtitle`    | `string` | Localized description            |
| `Remark`      | `label`       | `string` | `"Reason"` (localized)           |
| `Remark`      | `placeholder` | `string` | Localized placeholder            |
| `Remark`      | `maxLength`   | `number` | `500`                            |
| `Actions`     | `cancelText`  | `string` | `"Cancel"` (localized)           |
| `Actions`     | `submitText`  | `string` | `"Report"` (localized)           |

Every sub-component also accepts `children` (where applicable) and a `className`.

## Actions and Events

### Callback Props

#### onSubmit

Called when the user clicks Report with a reason selected. Receives the message ID, the selected reason ID, and the optional remark. Return `true` to close the dialog, or `false` to keep it open and show an inline error.

```tsx lines theme={null}
<CometChatFlagMessageDialog
  message={message}
  isOpen={open}
  onClose={() => setOpen(false)}
  onSubmit={async (messageId, reasonId, remark) => {
    const ok = await reportToBackend({ messageId, reasonId, remark });
    return ok;
  }}
/>
```

#### onClose

Called when the dialog requests to close — via the cancel button, the Escape key, or an outside click. In controlled mode you own the open state, so update it here.

```tsx lines theme={null}
<CometChatFlagMessageDialog
  message={message}
  isOpen={open}
  onClose={() => setOpen(false)}
/>
```

#### onError

Called when an SDK error occurs (e.g., while fetching reasons or during submission).

```tsx lines theme={null}
<CometChatFlagMessageDialog
  message={message}
  isOpen={open}
  onClose={() => setOpen(false)}
  onError={(error) => console.error("Flag message error:", error)}
/>
```

## Behavior Details

### Controlled vs Uncontrolled

* **Controlled** — pass `isOpen` and `onClose`. You own the open state (recommended for most apps).
* **Uncontrolled** — omit `isOpen`. The dialog manages its own internal open state and closes itself on cancel, Escape, outside click, or a successful submit.

### Reason Fetching

On open, the dialog calls `CometChat.getFlagReasons()` and renders the result as a single-select list. While loading, a loading state is shown. If the call fails, `onError` is invoked.

### Remark

The remark is optional. It is trimmed before submission, and an empty remark is passed as `undefined` to `onSubmit`. A character counter enforces `maxLength` (default 500).

### Submission

The submit button is disabled until a reason is selected. On submit:

1. `onSubmit` is awaited.
2. Returning `false` (or throwing) keeps the dialog open and shows an inline error banner.
3. Returning `true` closes the dialog.

### Focus & Keyboard

The Root traps focus within the dialog while open, moves focus to the first focusable element on open, restores focus to the previously focused element on close, cycles focus with `Tab` / `Shift+Tab`, and closes on `Escape`.

## CSS Architecture

The component uses CSS custom properties provided by the UI Kit.

### Key Selectors

| Target                    | Selector                                                |
| ------------------------- | ------------------------------------------------------- |
| Backdrop                  | `.cometchat-flag-message-dialog__backdrop`              |
| Dialog container          | `.cometchat-flag-message-dialog`                        |
| Error banner              | `.cometchat-flag-message-dialog__error`                 |
| Header                    | `.cometchat-flag-message-dialog__header`                |
| Header title              | `.cometchat-flag-message-dialog__header-title`          |
| Header subtitle           | `.cometchat-flag-message-dialog__header-subtitle`       |
| Reasons list              | `.cometchat-flag-message-dialog__reasons`               |
| Reason item               | `.cometchat-flag-message-dialog__reason`                |
| Reason item (selected)    | `.cometchat-flag-message-dialog__reason--selected`      |
| Reasons loading           | `.cometchat-flag-message-dialog__reasons-loading`       |
| Remark wrapper            | `.cometchat-flag-message-dialog__remark`                |
| Remark label              | `.cometchat-flag-message-dialog__remark-label`          |
| Remark input              | `.cometchat-flag-message-dialog__remark-input`          |
| Remark counter            | `.cometchat-flag-message-dialog__remark-counter`        |
| Remark counter (at limit) | `.cometchat-flag-message-dialog__remark-counter--limit` |
| Actions container         | `.cometchat-flag-message-dialog__actions`               |
| Cancel button             | `.cometchat-flag-message-dialog__actions-cancel`        |
| Submit button             | `.cometchat-flag-message-dialog__actions-submit`        |

### Example: Custom styling

```css lines title="App.css" theme={null}
.cometchat-flag-message-dialog {
  --cometchat-background-color-01: #ffffff;
  --cometchat-text-color-primary: #141414;
}

.cometchat-flag-message-dialog__reason--selected {
  border-color: var(--my-brand-color);
}

.cometchat-flag-message-dialog__actions-submit {
  background: var(--my-brand-color);
}
```

## Props

The `message` prop is required. All other props are optional. The props below belong to `Root` (and to the flat `CometChatFlagMessageDialog`, which forwards them).

***

### message

The message being flagged. **Required.**

|         |                         |
| ------- | ----------------------- |
| Type    | `CometChat.BaseMessage` |
| Default | —                       |

***

### isOpen

Whether the dialog is open. When provided, the component is controlled.

|         |                            |
| ------- | -------------------------- |
| Type    | `boolean`                  |
| Default | `undefined` (uncontrolled) |

***

### onClose

Callback invoked when the dialog requests to close (outside click, Escape, or cancel).

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### closeOnOutsideClick

Whether clicking outside the dialog closes it.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### onSubmit

Custom submit handler. Receives the message ID, the selected reason ID, and the optional remark. Return `true` on success (the dialog closes) or `false` to keep it open and show an error.

|         |                                                                              |
| ------- | ---------------------------------------------------------------------------- |
| Type    | `(messageId: string, reasonId: string, remark?: string) => Promise<boolean>` |
| Default | `undefined`                                                                  |

***

### onError

Callback when an SDK error occurs.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `undefined`                                               |

***

### className

Additional CSS class applied to the dialog backdrop.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

## Accessibility

* Root has `role="dialog"` with `aria-modal="true"`.
* The dialog is labelled by its title (`aria-labelledby`) and described by its subtitle (`aria-describedby`).
* Focus moves into the dialog on open and is restored to the previously focused element on close.
* Focus is trapped within the dialog; `Tab` / `Shift+Tab` cycle through focusable elements.
* `Escape` closes the dialog.
* The error banner uses `role="alert"` with `aria-live="assertive"`.


# Group Action Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/group-action-bubble

A self-extracting bubble that renders group action system messages like 'Alice joined' and 'Bob was kicked' from an SDK group-action message.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatGroupActionBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatGroupActionBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Self-extracting bubble for group membership system messages. Derives the localized action text from the SDK group-action message.",
    "cssRootClass": ".cometchat-action-bubble",
    "selfExtracting": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.BaseMessage", "required": true, "note": "The group-action message (member joined/left/added/kicked/banned/scope change). Drives all extraction." },
        "className": { "type": "string", "default": "undefined", "note": "Additional CSS class for the root element" }
      }
    },
    "rendersThrough": "CometChatActionBubble (base primitive)",
    "usedBy": ["CometChatGroupActionPlugin"]
  }
  ```
</Accordion>

## Overview

`CometChatGroupActionBubble` renders a centered, pill-shaped group action system message — "Alice joined", "Admin kicked Bob", "Admin made Bob a moderator", etc. It is **self-extracting**: pass the SDK group-action message and the bubble derives the localized action text itself (via the shared action-text utility), reading the locale from hooks. This means it works standalone — no plugin required.

It is the component the [Group Action Plugin](/docs/ui-kit/react/plugins/overview#built-in-plugins) forwards to, and it renders through the presentational `CometChatActionBubble` base primitive. Group action bubbles have no icon and no sender attribution.

<Info>
  **Live Preview** — interact with the group action bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-group-action-bubble--all-actions)
</Info>

<iframe title="CometChat Group Action Bubble — Joined" />

> The component renders nothing if the derived action text is empty.

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatGroupActionBubble } from "@cometchat/chat-uikit-react";

function GroupActionMessage({ message }: { message: CometChat.BaseMessage }) {
  return <CometChatGroupActionBubble message={message} />;
}
```

***

## Supported Actions

The bubble derives localized text for each group membership change:

| Action          | Example text                 |
| --------------- | ---------------------------- |
| Member joined   | "Alice joined"               |
| Member left     | "Bob left"                   |
| Member kicked   | "Admin kicked Bob"           |
| Member banned   | "Admin banned Charlie"       |
| Member unbanned | "Admin unbanned Charlie"     |
| Scope changed   | "Admin made Bob a moderator" |
| Member added    | "Admin added Dave"           |

***

## Props

### message

The group-action message (member joined / left / added / kicked / banned / scope change). The bubble extracts the localized action text from it. **Required.**

|          |                         |
| -------- | ----------------------- |
| Type     | `CometChat.BaseMessage` |
| Required | Yes                     |

***

### className

Additional CSS class name applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

The bubble renders through the `CometChatActionBubble` primitive, so it uses the action-bubble selectors.

| Target         | Selector                         |
| -------------- | -------------------------------- |
| Root container | `.cometchat-action-bubble`       |
| Action text    | `.cometchat-action-bubble__text` |

***

## Next Steps

<CardGroup>
  <Card title="Group Action Plugin" icon="users" href="/ui-kit/react/plugins/overview#built-in-plugins">
    How group membership messages are resolved and rendered in the message list
  </Card>

  <Card title="Call Action Bubble" icon="phone" href="/ui-kit/react/components/call-action-bubble">
    System messages for call status
  </Card>

  <Card title="Message Bubble" icon="comment" href="/ui-kit/react/components/message-bubble">
    The wrapper that hosts bubble content
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Group Members
Source: https://www.cometchat.com/docs/ui-kit/react/components/group-members

Scrollable list of members for a specific group with role-based actions like kick, ban, and scope change.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatGroupMembers",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatGroupMembers } from \"@cometchat/chat-uikit-react\";",
    "description": "Scrollable list of members for a specific group with role-based actions like kick, ban, and scope change.",
    "cssRootClass": ".cometchat-group-members",
    "primaryOutput": {
      "prop": "onItemClick",
      "type": "(member: CometChat.GroupMember) => void"
    },
    "props": {
      "data": {
        "group": {
          "type": "CometChat.Group",
          "default": "none (required)",
          "note": "The group whose members to display"
        },
        "groupMemberRequestBuilder": {
          "type": "CometChat.GroupMembersRequestBuilder",
          "default": "SDK default (30 per page)",
          "note": "Pass the builder instance, not the result of .build()"
        },
        "searchRequestBuilder": {
          "type": "CometChat.GroupMembersRequestBuilder",
          "default": "undefined"
        },
        "searchKeyword": {
          "type": "string",
          "default": "undefined"
        }
      },
      "callbacks": {
        "onItemClick": "(member: CometChat.GroupMember) => void",
        "onSelect": "(member: CometChat.GroupMember, selected: boolean) => void",
        "onError": "((error: CometChat.CometChatException) => void) | null",
        "onEmpty": "() => void",
        "onBack": "() => void"
      },
      "visibility": {
        "hideUserStatus": { "type": "boolean", "default": false },
        "hideSearch": { "type": "boolean", "default": false },
        "hideKickMemberOption": { "type": "boolean", "default": false },
        "hideBanMemberOption": { "type": "boolean", "default": false },
        "hideScopeChangeOption": { "type": "boolean", "default": false },
        "showScrollbar": { "type": "boolean", "default": false }
      },
      "selection": {
        "selectionMode": {
          "type": "CometChatGroupMembersSelectionMode",
          "values": ["'none'", "'single'", "'multiple'"],
          "default": "'none'"
        }
      },
      "viewSlots": {
        "itemView": "(member: CometChat.GroupMember) => ReactNode",
        "leadingView": "(member: CometChat.GroupMember) => ReactNode",
        "titleView": "(member: CometChat.GroupMember) => ReactNode",
        "subtitleView": "(member: CometChat.GroupMember) => ReactNode",
        "trailingView": "(member: CometChat.GroupMember) => ReactNode",
        "headerView": "ReactNode",
        "loadingView": "ReactNode",
        "emptyView": "ReactNode",
        "errorView": "ReactNode",
        "options": "(member: CometChat.GroupMember) => CometChatGroupMemberOption[]"
      }
    },
    "events": [],
    "eventsReceived": [
      {
        "name": "ui:group/member-added",
        "payload": "{ group: CometChat.Group, members: CometChat.User[], messages: CometChat.BaseMessage[] }",
        "description": "Adds new members to the list"
      },
      {
        "name": "ui:group/member-kicked",
        "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }",
        "description": "Removes the kicked member from the list"
      },
      {
        "name": "ui:group/member-banned",
        "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }",
        "description": "Removes the banned member from the list"
      },
      {
        "name": "ui:group/member-scope-changed",
        "payload": "{ group: CometChat.Group, user: CometChat.User, newScope: string }",
        "description": "Updates the member's scope/role display"
      },
      {
        "name": "ui:group/ownership-changed",
        "payload": "{ group: CometChat.Group, newOwner: CometChat.User, previousOwnerUid: string }",
        "description": "Updates new owner's scope to owner and demotes previous owner to admin"
      }
    ],
    "sdkListeners": [
      "onGroupMemberJoined",
      "onGroupMemberLeft",
      "onGroupMemberKicked",
      "onGroupMemberBanned",
      "onGroupMemberScopeChanged",
      "onMemberAddedToGroup"
    ],
    "types": {
      "CometChatGroupMemberOption": {
        "id": "string",
        "title": "string",
        "iconURL": "string | undefined",
        "onClick": "(member: CometChat.GroupMember) => void"
      },
      "CometChatGroupMembersSelectionMode": "'none' | 'single' | 'multiple'"
    }
  }
  ```
</Accordion>

## Overview

`CometChatGroupMembers` is a list component that renders all members of a specific group. It provides role-based actions (kick, ban, scope change) for admins and moderators, and emits the selected `CometChat.GroupMember` via `onItemClick`. Use it inside group details panels or as a standalone member management view.

<Info>
  **Live Preview** — interact with the default group members list.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-groups-cometchat-group-members--default)
</Info>

<iframe title="CometChat Group Members — Default" />

The component handles:

* Paginated fetching with infinite scroll
* Real-time membership updates (joins, leaves, kicks, bans, scope changes)
* Search filtering
* Role-based action menus (kick, ban, change scope)
* Selection mode (single/multiple)

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react";

function MemberList({ group }: { group: CometChat.Group }) {
  return (
    <CometChatGroupMembers
      group={group}
      onItemClick={(member) => {
        console.log("Selected member:", member.getName());
      }}
    />
  );
}
```

### Compound Composition

```tsx theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react";

function MemberList({ group }: { group: CometChat.Group }) {
  return (
    <CometChatGroupMembers.Root group={group} onItemClick={handleClick} onBack={goBack}>
      <CometChatGroupMembers.Header title="Members" />
      <CometChatGroupMembers.SearchBar placeholder="Search members..." />
      <CometChatGroupMembers.LoadingState />
      <CometChatGroupMembers.ErrorState />
      <CometChatGroupMembers.EmptyState>
        <p>No members found.</p>
      </CometChatGroupMembers.EmptyState>
      <CometChatGroupMembers.List />
    </CometChatGroupMembers.Root>
  );
}
```

### Group Details Example

```tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatGroupMembers,
  CometChatMessages,
} from "@cometchat/chat-uikit-react";

function GroupDetailsPanel({ group }: { group: CometChat.Group }) {
  const [selectedMember, setSelectedMember] = useState<
    CometChat.GroupMember | undefined
  >();

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 320 }}>
        <CometChatGroupMembers
          group={group}
          onItemClick={(member) => setSelectedMember(member)}
          onBack={() => navigateBack()}
        />
      </div>
      {selectedMember && (
        <div style={{ flex: 1 }}>
          {/* Show member profile or start DM */}
        </div>
      )}
    </div>
  );
}
```

***

## Filtering

Pass a `CometChat.GroupMembersRequestBuilder` to `groupMemberRequestBuilder` to control which members load. Pass the builder instance — not the result of `.build()`. Refer to [GroupMembersRequestBuilder](/docs/sdk/javascript/retrieve-group-members) for the full builder API.

```tsx theme={null}
<CometChatGroupMembers
  group={group}
  groupMemberRequestBuilder={
    new CometChat.GroupMembersRequestBuilder(group.getGuid())
      .setLimit(15)
      .setScopes(["admin", "moderator"])
  }
/>
```

### Search

The component includes a built-in search bar. When the user types, it fetches matching members from the server. For custom search behavior, pass a `searchRequestBuilder`:

```tsx theme={null}
<CometChatGroupMembers
  group={group}
  searchRequestBuilder={
    new CometChat.GroupMembersRequestBuilder(group.getGuid())
      .setLimit(30)
      .setSearchKeyword("")
  }
/>
```

### Filter Recipes

| Recipe              | Code                                                                               |
| ------------------- | ---------------------------------------------------------------------------------- |
| Only admins         | `new CometChat.GroupMembersRequestBuilder(guid).setScopes(["admin"])`              |
| Admins & moderators | `new CometChat.GroupMembersRequestBuilder(guid).setScopes(["admin", "moderator"])` |
| Limit page size     | `new CometChat.GroupMembersRequestBuilder(guid).setLimit(10)`                      |

***

## Actions and Events

### Callback Props

| Prop          | Signature                                                    | Fires when                                  |
| ------------- | ------------------------------------------------------------ | ------------------------------------------- |
| `onItemClick` | `(member: CometChat.GroupMember) => void`                    | User clicks a member item                   |
| `onSelect`    | `(member: CometChat.GroupMember, selected: boolean) => void` | Member selected/deselected (selection mode) |
| `onError`     | `((error: CometChat.CometChatException) => void) \| null`    | SDK error occurs                            |
| `onEmpty`     | `() => void`                                                 | List is empty after initial fetch           |
| `onBack`      | `() => void`                                                 | Back button is clicked                      |

### Events Emitted

This component does not emit any UI events directly. Kick, ban, and scope change actions are handled by internal action handlers that publish their own events.

### Events Received

UI events this component subscribes to (published by other components):

| Event                           | Payload                                 | Behavior                                                                           |
| ------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
| `ui:group/member-added`         | `{ group, members, messages }`          | Adds new members to the list                                                       |
| `ui:group/member-kicked`        | `{ group, user, message }`              | Removes the kicked member from the list                                            |
| `ui:group/member-banned`        | `{ group, user, message }`              | Removes the banned member from the list                                            |
| `ui:group/member-scope-changed` | `{ group, user, newScope }`             | Updates the member's scope/role display                                            |
| `ui:group/ownership-changed`    | `{ group, newOwner, previousOwnerUid }` | Updates the new owner's scope to "owner" and demotes the previous owner to "admin" |

### SDK Listeners (Automatic)

These SDK listeners are attached internally. The component updates its state automatically — no manual subscription needed:

* Groups: `onGroupMemberJoined`, `onGroupMemberLeft`, `onGroupMemberKicked`, `onGroupMemberBanned`, `onGroupMemberScopeChanged`, `onMemberAddedToGroup`

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatGroupMembers
  group={group}
  headerView={<MyCustomHeader />}
  itemView={(member) => <MyCustomMemberItem member={member} />}
  emptyView={<EmptyState />}
  loadingView={<Skeleton />}
  errorView={<ErrorBanner />}
/>
```

| Slot           | Signature               | Replaces                  |
| -------------- | ----------------------- | ------------------------- |
| `itemView`     | `(member) => ReactNode` | Entire member row         |
| `leadingView`  | `(member) => ReactNode` | Avatar section            |
| `titleView`    | `(member) => ReactNode` | Member name               |
| `subtitleView` | `(member) => ReactNode` | Status / role text        |
| `trailingView` | `(member) => ReactNode` | Scope badge + action menu |
| `headerView`   | `ReactNode`             | Header area               |
| `loadingView`  | `ReactNode`             | Loading shimmer           |
| `emptyView`    | `ReactNode`             | Empty state               |
| `errorView`    | `ReactNode`             | Error state               |

#### itemView

Replace the entire list item row.

Default:

<Frame>
  <img />
</Frame>

Customized:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import {
      CometChatAvatar,
      CometChatGroupMembers,
    } from "@cometchat/chat-uikit-react";

    function CustomItemViewMembers({ group }: { group: CometChat.Group }) {
      const getItemView = (member: CometChat.GroupMember) => {
        const scope = member.getScope();
        return (
          <div className="group-member-list-item">
            <div className="group-member-list-item__avatar">
              <CometChatAvatar.Root image={member.getAvatar()} name={member.getName()}>
                <CometChatAvatar.Image />
                <CometChatAvatar.Initials />
              </CometChatAvatar.Root>
            </div>
            <div className="group-member-list-item__content">
              <div className="group-member-list-item__content-name">{member.getName()}</div>
              <div className={`group-member-list-item__content-tag group-member-list-item__content-tag-${scope}`}>
                {scope}
              </div>
            </div>
          </div>
        );
      };

      return <CometChatGroupMembers group={group} itemView={getItemView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .group-member-list-item {
      display: flex;
      min-width: 240px;
      padding: 8px 16px;
      align-items: center;
      gap: 12px;
      background: #fff;
    }

    .group-member-list-item__content {
      display: flex;
      justify-content: space-between;
      align-items: center;
      width: 100%;
    }

    .cometchat-avatar, .cometchat-avatar__image {
      border-radius: 10px;
    }

    .group-member-list-item__content-name {
      overflow: hidden;
      color: #141414;
      text-overflow: ellipsis;
      font: 500 16px Roboto;
    }

    .group-member-list-item__content-tag {
      display: flex;
      padding: 4px 12px;
      border-radius: 1000px;
      background: #edeafa;
      color: #6852d6;
      font: 400 12px Roboto;
    }

    .group-member-list-item__content-tag-owner {
      background: #6852d6;
      color: #fff;
    }

    .group-member-list-item__content-tag-admin {
      border: 1px solid #6852d6;
    }

    .group-member-list-item__content-tag-participant {
      display: none;
    }
    ```
  </Tab>
</Tabs>

#### subtitleView

Replace the subtitle text. Joined date example.

Default:

<Frame>
  <img />
</Frame>

Customized:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatGroupMembers } from "@cometchat/chat-uikit-react";

    function SubtitleMembers({ group }: { group: CometChat.Group }) {
      const getSubtitleView = (member: CometChat.GroupMember) => {
        const date = new Date(member.getJoinedAt() * 1000).toLocaleDateString();
        return <div className="group-member-subtitle">Joined: {date}</div>;
      };

      return <CometChatGroupMembers group={group} subtitleView={getSubtitleView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .group-member-subtitle {
      overflow: hidden;
      color: #727272;
      text-overflow: ellipsis;
      white-space: nowrap;
      font: 400 14px Roboto;
    }
    ```
  </Tab>
</Tabs>

#### trailingView

Replace the right section. Scope tag example.

Default:

<Frame>
  <img />
</Frame>

Customized:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatGroupMembers } from "@cometchat/chat-uikit-react";

    function TrailingViewMembers({ group }: { group: CometChat.Group }) {
      const getTrailingView = (member: CometChat.GroupMember) => {
        return (
          <div className="group-member-scope-tag">
            {member.getScope()}
          </div>
        );
      };

      return <CometChatGroupMembers group={group} trailingView={getTrailingView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .group-member-scope-tag {
      display: flex;
      padding: 4px 12px;
      border-radius: 1000px;
      background: #edeafa;
      color: #6852d6;
      font: 400 12px Roboto;
    }
    ```
  </Tab>
</Tabs>

#### headerView

Replace the entire header bar.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import {
      CometChatGroupMembers,
      CometChatButton,
      useLocale,
    } from "@cometchat/chat-uikit-react";

    function CustomHeaderMembers({ group }: { group: CometChat.Group }) {
      const { getLocalizedString } = useLocale();

      return (
        <CometChatGroupMembers
          group={group}
          headerView={
            <div className="group-members__header">
              <div className="group-members__header__title">
                {getLocalizedString("group_members")}
              </div>
              <CometChatButton.Root onClick={() => { /* handle click */ }}>
                <CometChatButton.Icon />
              </CometChatButton.Root>
            </div>
          }
        />
      );
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .group-members__header {
      display: flex;
      width: 100%;
      padding: 8px 16px;
      align-items: center;
      justify-content: space-between;
      gap: 12px;
      border-radius: 10px;
      border: 1px solid #e8e8e8;
      background: #edeafa;
    }

    .group-members__header__title {
      overflow: hidden;
      color: #141414;
      text-overflow: ellipsis;
      font: 700 24px Roboto;
    }
    ```
  </Tab>
</Tabs>

#### options

Replace the context menu / hover actions on each member item.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import {
      CometChatGroupMembers,
      type CometChatGroupMemberOption,
    } from "@cometchat/chat-uikit-react";

    function CustomOptionsMembers({ group }: { group: CometChat.Group }) {
      const getOptions = (member: CometChat.GroupMember): CometChatGroupMemberOption[] => [
        {
          id: "kick",
          title: "Kick User",
          onClick: (m) => { /* kick logic */ },
        },
      ];

      return <CometChatGroupMembers group={group} options={getOptions} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-group-members .cometchat-menu-list__main-menu-item-icon {
      background: #f44649;
    }

    .cometchat-group-members .cometchat-menu-list__menu {
      background: transparent;
      box-shadow: none;
    }
    ```
  </Tab>
</Tabs>

### Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

```tsx theme={null}
<CometChatGroupMembers.Root group={group} onItemClick={handleClick}>
  {/* No Header or SearchBar — they won't render */}
  <CometChatGroupMembers.List />
</CometChatGroupMembers.Root>
```

Available sub-components:

| Sub-component  | Description                    | Props                                                      | Flat API equivalent |
| -------------- | ------------------------------ | ---------------------------------------------------------- | ------------------- |
| `Root`         | Context provider and container | All Root props + `children`                                | —                   |
| `List`         | Scrollable member list         | `itemView`                                                 | `itemView`          |
| `Item`         | Individual member row          | `leadingView`, `titleView`, `subtitleView`, `trailingView` | Per-item view props |
| `Header`       | Header area                    | `title`, `children`                                        | `headerView`        |
| `SearchBar`    | Search input                   | `placeholder`                                              | —                   |
| `EmptyState`   | Empty state                    | `children`                                                 | `emptyView`         |
| `ErrorState`   | Error state                    | `children`                                                 | `errorView`         |
| `LoadingState` | Loading shimmer                | `children`                                                 | `loadingView`       |

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-group-members {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-group-members__item-scope {
  color: var(--cometchat-primary-color);
  font-weight: 600;
}
```

***

## Props

All props are optional unless marked **Required**.

<Note>
  View slot props (`headerView`, `loadingView`, `emptyView`, `errorView`, `itemView`, `leadingView`, `titleView`, `subtitleView`, `trailingView`) are convenience props available only on the flat API. The search input is the `SearchBar` sub-component (with a `placeholder` prop), not a view slot. In compound composition mode, use the corresponding sub-components directly.
</Note>

***

### group

**Required.** The group whose members to display.

|         |                   |
| ------- | ----------------- |
| Type    | `CometChat.Group` |
| Default | —                 |

***

### groupMemberRequestBuilder

Custom request builder for fetching group members. Controls pagination, filtering, and sorting.

|         |                                        |
| ------- | -------------------------------------- |
| Type    | `CometChat.GroupMembersRequestBuilder` |
| Default | SDK default (limit 30)                 |

***

### searchRequestBuilder

Custom request builder used specifically when the user searches. Separate from the main builder.

|         |                                        |
| ------- | -------------------------------------- |
| Type    | `CometChat.GroupMembersRequestBuilder` |
| Default | `undefined`                            |

***

### searchKeyword

Initial search keyword to pre-filter members on mount.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### hideUserStatus

Hide the online/offline status indicator on member avatars.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideSearch

Hide the search bar entirely.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideKickMemberOption

Hide the "Kick Member" option from the action menu (even for admins/owners).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideBanMemberOption

Hide the "Ban Member" option from the action menu (even for admins/owners).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideScopeChangeOption

Hide the "Change Scope" option from the action menu (even for admins/owners).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showScrollbar

Show the native scrollbar on the member list.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### selectionMode

Enable selection mode for single or multi-select operations.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `'none' \| 'single' \| 'multiple'` |
| Default | `'none'`                           |

***

### options

Function that returns context menu options for each member item (shown on hover/swipe). Overrides the default kick/ban/scope options.

|         |                                                                            |
| ------- | -------------------------------------------------------------------------- |
| Type    | `(member: CometChat.GroupMember) => CometChatGroupMemberOption[]`          |
| Default | Default options (kick, ban, change scope — based on logged-in user's role) |

```tsx theme={null}
<CometChatGroupMembers
  group={group}
  options={(member) => [
    {
      id: "message",
      title: "Message Privately",
      iconURL: messageIcon,
      onClick: (m) => openDirectMessage(m),
    },
    {
      id: "remove",
      title: "Remove",
      iconURL: removeIcon,
      onClick: (m) => kickMember(m),
    },
  ]}
/>
```

***

### onItemClick

Callback when a member item is clicked.

|         |                                           |
| ------- | ----------------------------------------- |
| Type    | `(member: CometChat.GroupMember) => void` |
| Default | `undefined`                               |

***

### onSelect

Callback when a member is selected or deselected (only fires in selection mode).

|         |                                                              |
| ------- | ------------------------------------------------------------ |
| Type    | `(member: CometChat.GroupMember, selected: boolean) => void` |
| Default | `undefined`                                                  |

***

### onError

Callback when an SDK error occurs during fetch or real-time operations.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `null`                                                    |

***

### onEmpty

Callback when the member list is empty after the initial fetch completes.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onBack

Callback when the back button in the header is clicked.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

## CSS Selectors

| Target         | Selector                                  |
| -------------- | ----------------------------------------- |
| Root container | `.cometchat-group-members`                |
| Header         | `.cometchat-group-members__header`        |
| Search bar     | `.cometchat-group-members__search-bar`    |
| List container | `.cometchat-group-members__list`          |
| Member item    | `.cometchat-group-members__item`          |
| Scope badge    | `.cometchat-group-members__item-scope`    |
| Empty state    | `.cometchat-group-members__empty-state`   |
| Error state    | `.cometchat-group-members__error-state`   |
| Loading state  | `.cometchat-group-members__loading-state` |

***

## Next Steps

<CardGroup>
  <Card title="Groups" icon="users" href="/ui-kit/react/components/groups">
    Browse and select groups
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Groups
Source: https://www.cometchat.com/docs/ui-kit/react/components/groups

Searchable, scrollable list of groups with selection support and real-time membership updates.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatGroups",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatGroups } from \"@cometchat/chat-uikit-react\";",
    "description": "Searchable, scrollable list of groups with selection support and real-time membership updates.",
    "cssRootClass": ".cometchat-groups",
    "primaryOutput": {
      "prop": "onItemClick",
      "type": "(group: CometChat.Group) => void"
    },
    "props": {
      "data": {
        "groupsRequestBuilder": {
          "type": "CometChat.GroupsRequestBuilder",
          "default": "SDK default (30 per page)",
          "note": "Pass the builder instance, not the result of .build()"
        },
        "searchRequestBuilder": {
          "type": "CometChat.GroupsRequestBuilder",
          "default": "undefined"
        },
        "searchKeyword": {
          "type": "string",
          "default": "undefined"
        },
        "activeGroup": {
          "type": "CometChat.Group",
          "default": "undefined"
        }
      },
      "callbacks": {
        "onItemClick": "(group: CometChat.Group) => void",
        "onSelect": "(group: CometChat.Group, selected: boolean) => void",
        "onError": "((error: CometChat.CometChatException) => void) | null",
        "onEmpty": "() => void"
      },
      "visibility": {
        "hideGroupType": { "type": "boolean", "default": false },
        "hideSearch": { "type": "boolean", "default": false },
        "showScrollbar": { "type": "boolean", "default": false }
      },
      "selection": {
        "selectionMode": {
          "type": "CometChatGroupsSelectionMode",
          "values": ["'none'", "'single'", "'multiple'"],
          "default": "'none'"
        }
      },
      "viewSlots": {
        "itemView": "(group: CometChat.Group) => ReactNode",
        "leadingView": "(group: CometChat.Group) => ReactNode",
        "titleView": "(group: CometChat.Group) => ReactNode",
        "subtitleView": "(group: CometChat.Group) => ReactNode",
        "trailingView": "(group: CometChat.Group) => ReactNode",
        "headerView": "ReactNode",
        "loadingView": "ReactNode",
        "emptyView": "ReactNode",
        "errorView": "ReactNode",
        "options": "(group: CometChat.Group) => CometChatGroupOption[]"
      }
    },
    "events": [],
    "eventsReceived": [
      {
        "name": "ui:group/created",
        "payload": "{ group: CometChat.Group }",
        "description": "Adds the new group to the list"
      },
      {
        "name": "ui:group/deleted",
        "payload": "{ group: CometChat.Group }",
        "description": "Removes the group from the list"
      },
      {
        "name": "ui:group/left",
        "payload": "{ group: CometChat.Group }",
        "description": "Removes (private) or updates (public) the group"
      },
      {
        "name": "ui:group/member-joined",
        "payload": "{ joinedGroup: CometChat.Group }",
        "description": "Updates the group (member count)"
      },
      {
        "name": "ui:group/member-added",
        "payload": "{ group: CometChat.Group, members: CometChat.User[], messages: CometChat.BaseMessage[] }",
        "description": "Updates the group"
      },
      {
        "name": "ui:group/member-kicked",
        "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }",
        "description": "Updates the group"
      },
      {
        "name": "ui:group/member-banned",
        "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }",
        "description": "Updates the group"
      },
      {
        "name": "ui:group/member-scope-changed",
        "payload": "{ group: CometChat.Group, user: CometChat.User, newScope: string }",
        "description": "Updates the group"
      },
      {
        "name": "ui:group/ownership-changed",
        "payload": "{ group: CometChat.Group, newOwner: CometChat.User, previousOwnerUid: string }",
        "description": "Updates the group"
      }
    ],
    "sdkListeners": [
      "onGroupMemberJoined",
      "onGroupMemberLeft",
      "onGroupMemberKicked",
      "onGroupMemberBanned",
      "onMemberAddedToGroup"
    ],
    "types": {
      "CometChatGroupOption": {
        "id": "string",
        "title": "string",
        "iconURL": "string | undefined",
        "onClick": "(group: CometChat.Group) => void"
      },
      "CometChatGroupsSelectionMode": "'none' | 'single' | 'multiple'"
    }
  }
  ```
</Accordion>

## Overview

`CometChatGroups` is a list component that renders all available groups in the app. It emits the selected `CometChat.Group` via `onItemClick`. Wire it to `CometChatMessages` or use it as a group picker in flows like "join group" or "group details."

<Info>
  **Live Preview** — interact with the default groups list.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-groups-cometchat-groups--default)
</Info>

<iframe title="CometChat Groups — Default" />

The component handles:

* Paginated fetching with infinite scroll
* Real-time membership updates (joins, leaves, kicks, bans)
* Search filtering
* Swipe/hover options
* Selection mode (single/multiple)

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react";

function GroupList() {
  return (
    <CometChatGroups
      onItemClick={(group) => {
        console.log("Selected group:", group.getName());
      }}
    />
  );
}
```

### Compound Composition

```tsx theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react";

function GroupList() {
  return (
    <CometChatGroups.Root onItemClick={handleClick}>
      <CometChatGroups.Header title="Groups" />
      <CometChatGroups.SearchBar placeholder="Search groups..." />
      <CometChatGroups.LoadingState />
      <CometChatGroups.ErrorState />
      <CometChatGroups.EmptyState>
        <p>No groups found. Create one!</p>
      </CometChatGroups.EmptyState>
      <CometChatGroups.List />
    </CometChatGroups.Root>
  );
}
```

### Full Layout Example

```tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatGroups,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

function GroupChat() {
  const [group, setGroup] = useState<CometChat.Group | undefined>();

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        <CometChatGroups onItemClick={(g) => setGroup(g)} activeGroup={group} />
      </div>
      {group && (
        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
          <CometChatMessageHeader group={group} />
          <CometChatMessageList group={group} />
          <CometChatMessageComposer group={group} />
        </div>
      )}
    </div>
  );
}
```

***

## Filtering

Pass a `CometChat.GroupsRequestBuilder` to `groupsRequestBuilder` to control which groups load. Pass the builder instance — not the result of `.build()`. Refer to [GroupsRequestBuilder](/docs/sdk/javascript/retrieve-groups) for the full builder API.

```tsx theme={null}
<CometChatGroups
  groupsRequestBuilder={
    new CometChat.GroupsRequestBuilder()
      .setLimit(15)
      .joinedOnly(true)
  }
/>
```

### Search

The component includes a built-in search bar. When the user types, it fetches matching groups from the server. For custom search behavior, pass a `searchRequestBuilder`:

```tsx theme={null}
<CometChatGroups
  searchRequestBuilder={
    new CometChat.GroupsRequestBuilder().setLimit(30).setSearchKeyword("")
  }
/>
```

### Filter Recipes

| Recipe              | Code                                                      |
| ------------------- | --------------------------------------------------------- |
| Only joined groups  | `new CometChat.GroupsRequestBuilder().joinedOnly(true)`   |
| Only public groups  | `new CometChat.GroupsRequestBuilder().setType("public")`  |
| Only private groups | `new CometChat.GroupsRequestBuilder().setType("private")` |
| Limit page size     | `new CometChat.GroupsRequestBuilder().setLimit(10)`       |
| With tags           | `new CometChat.GroupsRequestBuilder().setTags(["team"])`  |

***

## Actions and Events

### Callback Props

| Prop          | Signature                                                 | Fires when                                 |
| ------------- | --------------------------------------------------------- | ------------------------------------------ |
| `onItemClick` | `(group: CometChat.Group) => void`                        | User clicks a group item                   |
| `onSelect`    | `(group: CometChat.Group, selected: boolean) => void`     | Group selected/deselected (selection mode) |
| `onError`     | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs                           |
| `onEmpty`     | `() => void`                                              | List is empty after initial fetch          |

### Events Emitted

This component does not emit any UI events.

### Events Received

UI events this component subscribes to (published by other components):

| Event                           | Payload                                 | Behavior                                        |
| ------------------------------- | --------------------------------------- | ----------------------------------------------- |
| `ui:group/created`              | `{ group }`                             | Adds the new group to the list                  |
| `ui:group/deleted`              | `{ group }`                             | Removes the group from the list                 |
| `ui:group/left`                 | `{ group }`                             | Removes (private) or updates (public) the group |
| `ui:group/member-joined`        | `{ joinedGroup }`                       | Updates the group (member count)                |
| `ui:group/member-added`         | `{ group, members, messages }`          | Updates the group                               |
| `ui:group/member-kicked`        | `{ group, user, message }`              | Updates the group                               |
| `ui:group/member-banned`        | `{ group, user, message }`              | Updates the group                               |
| `ui:group/member-scope-changed` | `{ group, user, newScope }`             | Updates the group                               |
| `ui:group/ownership-changed`    | `{ group, newOwner, previousOwnerUid }` | Updates the group                               |

### SDK Listeners (Automatic)

These SDK listeners are attached internally. The component updates its state automatically — no manual subscription needed:

* Groups: `onGroupMemberJoined`, `onGroupMemberLeft`, `onGroupMemberKicked`, `onGroupMemberBanned`, `onMemberAddedToGroup`

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatGroups
  headerView={<MyCustomHeader />}
  itemView={(group) => <MyCustomGroupItem group={group} />}
  emptyView={<EmptyState />}
  loadingView={<Skeleton />}
  errorView={<ErrorBanner />}
/>
```

| Slot           | Signature              | Replaces                           |
| -------------- | ---------------------- | ---------------------------------- |
| `itemView`     | `(group) => ReactNode` | Entire group row                   |
| `leadingView`  | `(group) => ReactNode` | Avatar section                     |
| `titleView`    | `(group) => ReactNode` | Group name                         |
| `subtitleView` | `(group) => ReactNode` | Member count / description         |
| `trailingView` | `(group) => ReactNode` | Trailing content (group type icon) |
| `headerView`   | `ReactNode`            | Header area                        |
| `loadingView`  | `ReactNode`            | Loading shimmer                    |
| `emptyView`    | `ReactNode`            | Empty state                        |
| `errorView`    | `ReactNode`            | Error state                        |

#### itemView

Replace the entire list item row.

Default:

<Frame>
  <img />
</Frame>

Customized:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatGroups } from "@cometchat/chat-uikit-react";

    function CustomItemViewGroups() {
      const getItemView = (group: CometChat.Group) => {
        return (
          <div className="group-list-item">
            <div className="group-list-item__title-wrapper">
              <div className="group-list-item__title">{group.getName()}</div>
              <div className="group-list-item__tail">JOIN</div>
            </div>
            <div className="group-list-item__subtitle">
              {group.getMembersCount()} Members • {group.getDescription()}
            </div>
          </div>
        );
      };

      return <CometChatGroups itemView={getItemView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .group-list-item {
      display: flex;
      flex-direction: column;
      text-align: left;
      min-width: 240px;
      padding: 8px 16px;
      gap: 4px;
      flex: 1 0 0;
      border-right: 1px solid #f5f5f5;
      background: #fff;
    }

    .group-list-item:hover {
      background-color: #f5f5f5;
    }

    .group-list-item__title-wrapper {
      display: flex;
      justify-content: space-between;
      align-items: center;
      align-self: stretch;
    }

    .group-list-item__title {
      overflow: hidden;
      color: #141414;
      text-overflow: ellipsis;
      font: 500 16px Roboto;
    }

    .group-list-item__tail {
      display: flex;
      padding: 4px 12px;
      justify-content: center;
      align-items: center;
      border-radius: 1000px;
      background: #edeafa;
      overflow: hidden;
      color: #6852d6;
      text-overflow: ellipsis;
      font: 700 12px Roboto;
    }

    .group-list-item__subtitle {
      overflow: hidden;
      color: #727272;
      text-overflow: ellipsis;
      white-space: nowrap;
      font: 400 14px Roboto;
    }
    ```
  </Tab>
</Tabs>

#### titleView

Replace the name / title text. Group type badge inline example.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatGroups } from "@cometchat/chat-uikit-react";

    function GroupTypeTitleGroups() {
      const getTitleView = (group: CometChat.Group) => {
        return (
          <div className={`groups__title-view groups__title-view-${group.getType()}`}>
            <span className="groups__title-view-name">{group.getName()}</span>
            <span className="groups__title-view-type">{group.getType()}</span>
          </div>
        );
      };

      return <CometChatGroups titleView={getTitleView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .groups__title-view {
      display: flex;
      align-items: center;
      gap: 4px;
      align-self: stretch;
    }

    .groups__title-view-name {
      overflow: hidden;
      color: #141414;
      text-overflow: ellipsis;
      font: 500 16px Roboto;
    }

    .groups__title-view-type {
      color: #fff;
      font: 600 8px Roboto;
      display: flex;
      height: 15px;
      padding: 1px 3px;
      justify-content: center;
      align-items: center;
      gap: 4px;
      border-radius: 7px;
      background: #09c26f;
    }

    .groups__title-view-public .groups__title-view-type {
      background: #0b7bea;
    }
    ```
  </Tab>
</Tabs>

#### subtitleView

Replace the member count subtitle text.

Default:

<Frame>
  <img />
</Frame>

Customized:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatGroups } from "@cometchat/chat-uikit-react";

    function SubtitleGroups() {
      const getSubtitleView = (group: CometChat.Group) => {
        return (
          <div className="group-subtitle">
            {group.getMembersCount()} Members • {group.getDescription()}
          </div>
        );
      };

      return <CometChatGroups subtitleView={getSubtitleView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-groups .group-subtitle {
      overflow: hidden;
      color: #727272;
      text-overflow: ellipsis;
      white-space: nowrap;
      font: 400 14px Roboto;
    }
    ```
  </Tab>
</Tabs>

### Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

```tsx theme={null}
<CometChatGroups.Root onItemClick={handleClick}>
  {/* No Header or SearchBar — they won't render */}
  <CometChatGroups.List />
</CometChatGroups.Root>
```

Available sub-components:

| Sub-component  | Description                    | Props                                                      | Flat API equivalent |
| -------------- | ------------------------------ | ---------------------------------------------------------- | ------------------- |
| `Root`         | Context provider and container | All Root props + `children`                                | —                   |
| `List`         | Scrollable group list          | `itemView`                                                 | `itemView`          |
| `Item`         | Individual group row           | `leadingView`, `titleView`, `subtitleView`, `trailingView` | Per-item view props |
| `Header`       | Header area                    | `title`, `children`                                        | `headerView`        |
| `SearchBar`    | Search input                   | `placeholder`                                              | —                   |
| `EmptyState`   | Empty state                    | `children`                                                 | `emptyView`         |
| `ErrorState`   | Error state                    | `children`                                                 | `errorView`         |
| `LoadingState` | Loading shimmer                | `children`                                                 | `loadingView`       |

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-groups {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-groups__item--active {
  background: var(--cometchat-primary-color);
}
```

***

## Props

All props are optional.

<Note>
  View slot props (`headerView`, `loadingView`, `emptyView`, `errorView`, `itemView`, `leadingView`, `titleView`, `subtitleView`, `trailingView`) are convenience props available only on the flat API. The search input is the `SearchBar` sub-component (with a `placeholder` prop), not a view slot. In compound composition mode, use the corresponding sub-components directly.
</Note>

***

### groupsRequestBuilder

Custom request builder for fetching groups. Controls pagination, filtering, and sorting.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `CometChat.GroupsRequestBuilder` |
| Default | SDK default (limit 30)           |

***

### searchRequestBuilder

Custom request builder used specifically when the user searches. Separate from the main builder.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `CometChat.GroupsRequestBuilder` |
| Default | `undefined`                      |

***

### searchKeyword

Initial search keyword to pre-filter groups on mount.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### hideGroupType

Hide the group type indicator (public/private/password-protected) on group items.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideSearch

Hide the search bar entirely.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showScrollbar

Show the native scrollbar on the group list.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### selectionMode

Enable selection mode for single or multi-select operations.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `'none' \| 'single' \| 'multiple'` |
| Default | `'none'`                           |

***

### activeGroup

The currently active/highlighted group. The matching item receives an active visual state.

|         |                   |
| ------- | ----------------- |
| Type    | `CometChat.Group` |
| Default | `undefined`       |

***

### options

Function that returns context menu options for each group item (shown on hover/swipe).

|         |                                                      |
| ------- | ---------------------------------------------------- |
| Type    | `(group: CometChat.Group) => CometChatGroupOption[]` |
| Default | `undefined`                                          |

```tsx theme={null}
<CometChatGroups
  options={(group) => [
    {
      id: "leave",
      title: "Leave Group",
      iconURL: leaveIcon,
      onClick: (g) => leaveGroup(g),
    },
    {
      id: "info",
      title: "Group Info",
      iconURL: infoIcon,
      onClick: (g) => openGroupDetails(g),
    },
  ]}
/>
```

***

### onItemClick

Callback when a group item is clicked.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `(group: CometChat.Group) => void` |
| Default | `undefined`                        |

***

### onSelect

Callback when a group is selected or deselected (only fires in selection mode).

|         |                                                       |
| ------- | ----------------------------------------------------- |
| Type    | `(group: CometChat.Group, selected: boolean) => void` |
| Default | `undefined`                                           |

***

### onError

Callback when an SDK error occurs during fetch or real-time operations.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `null`                                                    |

***

### onEmpty

Callback when the group list is empty after the initial fetch completes.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

## CSS Selectors

| Target         | Selector                           |
| -------------- | ---------------------------------- |
| Root container | `.cometchat-groups`                |
| Header         | `.cometchat-groups__header`        |
| Search bar     | `.cometchat-groups__search-bar`    |
| List container | `.cometchat-groups__list`          |
| Group item     | `.cometchat-groups__item`          |
| Active item    | `.cometchat-groups__item--active`  |
| Empty state    | `.cometchat-groups__empty-state`   |
| Error state    | `.cometchat-groups__error-state`   |
| Loading state  | `.cometchat-groups__loading-state` |

***

## Next Steps

<CardGroup>
  <Card title="Group Members" icon="user-group" href="/ui-kit/react/components/group-members">
    View and manage members of a group
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/react/components/conversations">
    View recent conversations including group chats
  </Card>

  <Card title="Message List" icon="comment-dots" href="/ui-kit/react/components/message-list">
    Display messages for the selected group
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Image Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/image-bubble

A batch-aware bubble that renders one or more image attachments with adaptive grid layouts, a caption, and a fullscreen gallery viewer.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatImagesBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatImagesBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Batch-aware image bubble. Extracts image attachments and caption from a MediaMessage; renders adaptive grid layouts (single, 2-col, 2x2, overflow) and opens a fullscreen gallery viewer.",
    "cssRootClass": ".cometchat-images-bubble",
    "selfExtracting": true,
    "multiAttachment": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of attachments and caption." },
        "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." },
        "textFormatters": { "type": "CometChatTextFormatter[]" },
        "placeholderImage": { "type": "string" },
        "onImageClicked": { "type": "(attachment, index) => void" },
        "className": { "type": "string" }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatImagesBubble` renders the image attachment(s) of a media message with batch-aware styling. It is **self-extracting**: pass the SDK `message` and the bubble derives its attachments, caption, and alignment itself. The message list uses it automatically for image messages.

Key capabilities:

* **Adaptive grid layouts** — single image, 2-column, 2×2 grid, and overflow (+N) based on attachment count
* **Fullscreen gallery viewer** — click any image to open a paginated fullscreen gallery
* **Batch grouping** — rendered as one connected group when several media messages are sent together (handled by the [message list](/docs/ui-kit/react/components/message-list#multi-attachment-batch-grouping))
* **Placeholder loading** — shows a configurable placeholder while images load

<Info>
  **Live Preview** — interact with the image bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble-images--grid-3-images)
</Info>

<iframe title="CometChat Image Bubble — 3 Image Grid" />

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatImagesBubble } from "@cometchat/chat-uikit-react";

function ImageMessage({ message }: { message: CometChat.MediaMessage }) {
  return <CometChatImagesBubble message={message} />;
}
```

***

## Grid Layouts

The bubble automatically selects a layout based on the number of image attachments:

| Attachment Count | Layout         | Description                                  |
| ---------------- | -------------- | -------------------------------------------- |
| 1                | `single`       | Full-width single image                      |
| 2                | `grid` (2-col) | Side-by-side images                          |
| 3                | `grid` (three) | 2-col grid with one spanning                 |
| 4                | `grid-2x2`     | 2×2 even grid                                |
| 5+               | `overflow`     | 2×2 grid with last tile showing "+N" overlay |

<iframe title="CometChat Image Bubble — Grid Overflow" />

***

## Props

### message

The image message. The bubble extracts its attachments and caption from it. **Required.**

|          |                          |
| -------- | ------------------------ |
| Type     | `CometChat.MediaMessage` |
| Required | Yes                      |

***

### alignment

Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user.

|         |                     |
| ------- | ------------------- |
| Type    | `"left" \| "right"` |
| Default | derived             |

***

### textFormatters

Text formatters applied to the caption (mentions, URLs).

|         |                            |
| ------- | -------------------------- |
| Type    | `CometChatTextFormatter[]` |
| Default | `undefined`                |

***

### placeholderImage

Custom placeholder image URL shown while the image is loading. Falls back to a default photo icon.

|         |                      |
| ------- | -------------------- |
| Type    | `string`             |
| Default | built-in placeholder |

***

### onImageClicked

Callback fired when an image tile is clicked (in addition to opening the fullscreen viewer).

|         |                                                                        |
| ------- | ---------------------------------------------------------------------- |
| Type    | `(attachment: CometChatImagesBubbleAttachment, index: number) => void` |
| Default | `undefined`                                                            |

***

### className

Additional CSS class applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target             | Selector                                     |
| ------------------ | -------------------------------------------- |
| Root               | `.cometchat-images-bubble`                   |
| Incoming variant   | `.cometchat-images-bubble--incoming`         |
| Outgoing variant   | `.cometchat-images-bubble--outgoing`         |
| Single layout      | `.cometchat-images-bubble--single`           |
| Grid container     | `.cometchat-images-bubble__grid`             |
| 2-column grid      | `.cometchat-images-bubble__grid--two-col`    |
| 3-image grid       | `.cometchat-images-bubble__grid--three`      |
| 2×2 grid           | `.cometchat-images-bubble__grid--2x2`        |
| Overflow grid      | `.cometchat-images-bubble__grid--overflow`   |
| Image wrapper      | `.cometchat-images-bubble__image-wrapper`    |
| Image element      | `.cometchat-images-bubble__image`            |
| Placeholder        | `.cometchat-images-bubble__placeholder`      |
| Overflow tile      | `.cometchat-images-bubble__overflow-tile`    |
| Overflow overlay   | `.cometchat-images-bubble__overflow-overlay` |
| Overflow text (+N) | `.cometchat-images-bubble__overflow-text`    |
| Container          | `.cometchat-images-bubble__container`        |
| Caption            | `.cometchat-images-bubble__caption`          |

***

## Next Steps

<CardGroup>
  <Card title="Video Bubble" icon="video" href="/ui-kit/react/components/video-bubble">
    Batch-aware video bubble with grid layouts
  </Card>

  <Card title="File Bubble" icon="file" href="/ui-kit/react/components/file-bubble">
    Batch-aware file bubble with stacked cards
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/react/components/message-list">
    Multi-attachment batch grouping in the list
  </Card>

  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/react/components/message-composer">
    Multi-attachment staging tray
  </Card>
</CardGroup>


# Incoming Call
Source: https://www.cometchat.com/docs/ui-kit/react/components/incoming-call

Displays an incoming call notification with caller info, accept/decline buttons, and transitions to the ongoing call screen.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatIncomingCall",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatIncomingCall } from \"@cometchat/chat-uikit-react\";",
    "description": "Displays an incoming call notification with caller info, accept/decline buttons, and transitions to the ongoing call screen.",
    "cssRootClass": ".cometchat-incoming-call",
    "primaryOutput": {
      "prop": "onAccept",
      "type": "(call: CometChat.Call) => void"
    },
    "props": {
      "callbacks": {
        "onAccept": "(call: CometChat.Call) => void",
        "onDecline": "(call: CometChat.Call) => void",
        "onCallEnded": "() => void",
        "onError": "((error: CometChat.CometChatException) => void) | null"
      },
      "sound": {
        "disableSoundForCalls": { "type": "boolean", "default": false },
        "customSoundForCalls": { "type": "string", "default": "built-in" }
      },
      "configuration": {
        "callSettingsBuilder": {
          "type": "(call: CometChat.Call) => any",
          "default": "undefined",
          "note": "Custom call settings for the ongoing call session after accepting"
        }
      },
      "viewSlots": {
        "itemView": "(call: CometChat.Call) => ReactNode",
        "leadingView": "(call: CometChat.Call) => ReactNode",
        "titleView": "(call: CometChat.Call) => ReactNode",
        "subtitleView": "(call: CometChat.Call) => ReactNode",
        "trailingView": "(call: CometChat.Call) => ReactNode"
      }
    },
    "events": [
      {
        "name": "ui:call/rejected",
        "payload": "{ call }",
        "description": "Call declined by user"
      },
      {
        "name": "ui:call/ended",
        "payload": "{}",
        "description": "Ongoing call ended"
      }
    ],
    "sdkListeners": [
      "onIncomingCallReceived",
      "onIncomingCallCancelled",
      "onOutgoingCallAccepted",
      "onOutgoingCallRejected"
    ],
    "types": {
      "CometChatDateFormatConfig": {
        "today": "string | undefined",
        "yesterday": "string | undefined",
        "lastWeek": "string | undefined",
        "otherDays": "string | undefined"
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatIncomingCall` is a full-screen notification component that automatically listens for incoming calls via the CometChat SDK `CallListener`. When an incoming call is detected, it displays the caller's avatar, name, and call type (Voice/Video) with accept and decline buttons.

<Info>
  **Live Preview** — interact with the default incoming call screen.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-calls-cometchat-incoming-call--default)
</Info>

<iframe title="CometChat Incoming Call — Default" />

The component handles:

* Automatic detection of incoming calls via SDK `CallListener`
* Caller avatar, name, and call type display (Voice/Video)
* Accept button — transitions to `CometChatOngoingCall` internally
* Decline button — rejects the call via SDK
* Incoming call sound playback (looping while notification is visible)
* Self-managed visibility (renders nothing when no incoming call is active)

> **Placement:** Render `CometChatIncomingCall` at your app's root level. It manages its own visibility internally and only appears when an incoming call is detected.

> **Note:** Call **initiation** buttons are provided by the standalone [`CometChatCallButtons`](/docs/ui-kit/react/components/call-buttons) component (also rendered automatically inside `CometChatMessageHeader`). `CometChatIncomingCall` is separate — it handles the incoming call notification flow.

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react";

function App() {
  return (
    <div>
      {/* Your app content */}
      <CometChatIncomingCall
        onAccept={(call) => {
          console.log("Call accepted:", call.getSessionId());
        }}
        onDecline={(call) => {
          console.log("Call declined:", call.getSessionId());
        }}
        onCallEnded={() => {
          console.log("Call ended");
        }}
      />
    </div>
  );
}
```

### Full Layout Example

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

function ChatApp() {
  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>
      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        <CometChatMessageHeader user={user} group={group} />
        <CometChatMessageList user={user} group={group} />
        <CometChatMessageComposer user={user} group={group} />
      </div>

      {/* Render at root level — manages its own visibility */}
      <CometChatIncomingCall />
    </div>
  );
}
```

***

## Actions and Events

### Callback Props

| Prop          | Signature                                                 | Fires when                     |
| ------------- | --------------------------------------------------------- | ------------------------------ |
| `onAccept`    | `(call: CometChat.Call) => void`                          | User clicks the accept button  |
| `onDecline`   | `(call: CometChat.Call) => void`                          | User clicks the decline button |
| `onCallEnded` | `() => void`                                              | Ongoing call session ends      |
| `onError`     | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs               |

### Events Emitted

UI events this component publishes:

| Event              | Payload    | Fires when            |
| ------------------ | ---------- | --------------------- |
| `ui:call/rejected` | `{ call }` | Call declined by user |
| `ui:call/ended`    | `{}`       | Ongoing call ended    |

### Events Received

This component does not subscribe to any UI events from other components.

### SDK Listeners (Automatic)

These SDK `CallListener` callbacks are attached internally. The component updates its state automatically:

* `onIncomingCallReceived` — shows the incoming call notification
* `onIncomingCallCancelled` — hides the notification (caller cancelled)
* `onOutgoingCallAccepted` — transitions to ongoing call screen
* `onOutgoingCallRejected` — hides the notification (call rejected elsewhere)

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatIncomingCall
  leadingView={(call) => <MyCustomAvatar call={call} />}
  titleView={(call) => <span>{call.getSender().getName()}</span>}
  subtitleView={(call) => <span>Incoming {call.getType()} call</span>}
/>
```

| Slot           | Signature                             | Replaces                      |
| -------------- | ------------------------------------- | ----------------------------- |
| `itemView`     | `(call: CometChat.Call) => ReactNode` | Entire call notification card |
| `leadingView`  | `(call: CometChat.Call) => ReactNode` | Avatar section                |
| `titleView`    | `(call: CometChat.Call) => ReactNode` | Caller name                   |
| `subtitleView` | `(call: CometChat.Call) => ReactNode` | Call type label               |
| `trailingView` | `(call: CometChat.Call) => ReactNode` | Trailing section              |

#### leadingView

<Frame>
  <img />
</Frame>

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatAvatar, CometChatIncomingCall } from "@cometchat/chat-uikit-react";

function CustomLeadingIncoming() {
  return (
    <CometChatIncomingCall
      leadingView={(call: CometChat.Call) => (
        <CometChatAvatar.Root
          name={call.getCallInitiator()?.getName()}
          image={call.getCallInitiator()?.getAvatar()}
        >
          <CometChatAvatar.Image />
          <CometChatAvatar.Initials />
        </CometChatAvatar.Root>
      )}
    />
  );
}
```

#### titleView

<Frame>
  <img />
</Frame>

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react";

function CustomTitleIncoming() {
  return (
    <CometChatIncomingCall
      titleView={(call: CometChat.Call) => (
        <div>{call.getCallInitiator()?.getName()}</div>
      )}
    />
  );
}
```

#### itemView

<Frame>
  <img />
</Frame>

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatAvatar, CometChatIncomingCall } from "@cometchat/chat-uikit-react";

function CustomItemViewIncoming() {
  return (
    <CometChatIncomingCall
      itemView={(call: CometChat.Call) => (
        <div className="incoming-call__item">
          <CometChatAvatar.Root
            name={call.getCallInitiator()?.getName()}
            image={call.getCallInitiator()?.getAvatar()}
          >
            <CometChatAvatar.Image />
            <CometChatAvatar.Initials />
          </CometChatAvatar.Root>
          <div>{call.getCallInitiator()?.getName()}</div>
        </div>
      )}
    />
  );
}
```

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-incoming-call {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-incoming-call__button-accept {
  background: var(--cometchat-success-color);
}

.cometchat-incoming-call__button-decline {
  background: var(--cometchat-error-color);
}
```

***

## Props

All props are optional.

***

### onAccept

Custom accept handler. When provided, overrides the default `CometChat.acceptCall` behavior.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `(call: CometChat.Call) => void` |
| Default | `undefined`                      |

***

### onDecline

Custom decline handler. When provided, overrides the default `CometChat.rejectCall` behavior.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `(call: CometChat.Call) => void` |
| Default | `undefined`                      |

***

### onCallEnded

Callback when the ongoing call session ends and the call screen should close.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### disableSoundForCalls

Disable the incoming call ringtone sound.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### customSoundForCalls

Custom sound URL to play for incoming calls (replaces the built-in ringtone).

|         |                   |
| ------- | ----------------- |
| Type    | `string`          |
| Default | Built-in ringtone |

***

### callSettingsBuilder

Custom call settings builder for the ongoing call session after accepting. If not provided, the component uses default settings.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `(call: CometChat.Call) => any` |
| Default | `undefined`                     |

```tsx theme={null}
<CometChatIncomingCall
  callSettingsBuilder={(call) => {
    return new CometChat.CallSettingsBuilder()
      .enableDefaultLayout(true)
      .setIsAudioOnlyCall(call.getType() === "audio")
      .build();
  }}
/>
```

***

### onError

Callback when an SDK error occurs.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `null`                                                    |

***

### itemView

Custom renderer for the entire incoming call notification card.

|         |                                       |
| ------- | ------------------------------------- |
| Type    | `(call: CometChat.Call) => ReactNode` |
| Default | `undefined`                           |

***

### leadingView

Custom renderer for the avatar section.

|         |                                       |
| ------- | ------------------------------------- |
| Type    | `(call: CometChat.Call) => ReactNode` |
| Default | `undefined`                           |

***

### titleView

Custom renderer for the caller name.

|         |                                       |
| ------- | ------------------------------------- |
| Type    | `(call: CometChat.Call) => ReactNode` |
| Default | `undefined`                           |

***

### subtitleView

Custom renderer for the call type label (Voice/Video).

|         |                                       |
| ------- | ------------------------------------- |
| Type    | `(call: CometChat.Call) => ReactNode` |
| Default | `undefined`                           |

***

### trailingView

Custom renderer for the trailing section.

|         |                                       |
| ------- | ------------------------------------- |
| Type    | `(call: CometChat.Call) => ReactNode` |
| Default | `undefined`                           |

***

### className

Additional CSS class name applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target            | Selector                                   |
| ----------------- | ------------------------------------------ |
| Root container    | `.cometchat-incoming-call`                 |
| Info section      | `.cometchat-incoming-call__info`           |
| Avatar            | `.cometchat-incoming-call__avatar`         |
| Details container | `.cometchat-incoming-call__details`        |
| Title             | `.cometchat-incoming-call__title`          |
| Subtitle          | `.cometchat-incoming-call__subtitle`       |
| Trailing section  | `.cometchat-incoming-call__trailing`       |
| Button group      | `.cometchat-incoming-call__button-group`   |
| Accept button     | `.cometchat-incoming-call__button-accept`  |
| Decline button    | `.cometchat-incoming-call__button-decline` |

***

## Next Steps

<CardGroup>
  <Card title="Outgoing Call" icon="phone-arrow-up-right" href="/ui-kit/react/components/outgoing-call">
    Display the outgoing call screen while waiting for the receiver to answer
  </Card>

  <Card title="Call Logs" icon="clock-rotate-left" href="/ui-kit/react/components/call-logs">
    Browse call history and re-initiate calls
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Message Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/message-bubble

A shared wrapper component that renders all message types with common chrome — avatar, sender name, bubble background, timestamp, receipts, thread replies, and context menu.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatMessageBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatMessageBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Layout shell that wraps plugin-rendered bubble content with shared chrome — avatar, sender name, bubble background, timestamp, receipts, thread replies, reactions, and context menu.",
    "cssRootClass": ".cometchat-message-bubble",
    "props": {
      "data": {
        "message": { "type": "CometChat.BaseMessage", "required": true },
        "alignment": { "type": "'left' | 'right' | 'center'", "required": true },
        "contentView": { "type": "ReactNode", "required": true, "note": "Inner content from the plugin's renderBubble()." },
        "group": { "type": "CometChat.Group" },
        "options": { "type": "CometChatMessageOption[]" },
        "quickOptionsCount": { "type": "number", "default": 2 }
      },
      "visibility": {
        "hideAvatar": { "type": "boolean", "default": false },
        "forceShowAvatar": { "type": "boolean", "default": false },
        "hideSenderName": { "type": "boolean", "default": false },
        "hideTimestamp": { "type": "boolean", "default": false },
        "hideThreadView": { "type": "boolean", "default": false },
        "hideReceipts": { "type": "boolean", "note": "Reads from GlobalConfig if not set." },
        "showError": { "type": "boolean", "default": false },
        "disableInteraction": { "type": "boolean", "default": false }
      },
      "config": {
        "messageSentAtDateTimeFormat": { "type": "CometChatDateFormatConfig" },
        "isSelected": { "type": "boolean" },
        "ariaPosinset": { "type": "number" },
        "ariaSetsize": { "type": "number" },
        "className": { "type": "string" },
        "setRef": { "type": "Ref<HTMLDivElement>" },
        "includeBottomViewHeight": { "type": "boolean", "default": false },
        "toggleOptionsVisibility": { "type": "boolean" }
      },
      "viewSlots": {
        "leadingView": "((message) => ReactNode) | null",
        "headerView": "((message) => ReactNode) | null",
        "statusInfoView": "((message) => ReactNode) | null",
        "footerView": "((message) => ReactNode) | null",
        "threadView": "((message) => ReactNode) | null",
        "replyView": "ReactNode | null",
        "bottomView": "((message) => ReactNode) | null"
      },
      "callbacks": {
        "onAvatarClick": "(user: CometChat.User) => void",
        "onThreadRepliesClick": "(message: CometChat.BaseMessage) => void",
        "onOptionClick": "(option: CometChatMessageOption, message: CometChat.BaseMessage) => void",
        "onReactionChipClick": "(messageId: number, emoji: string) => void",
        "onReactorClick": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void"
      }
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatMessageBubble` is the layout shell for every message in the message list. The plugin system's `renderBubble()` produces the inner content (text, image, video, etc.), and the bubble wraps it with shared chrome.

<Info>
  **Live Preview** — interact with the message bubble component.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble--default)
</Info>

<iframe title="CometChat Message Bubble — Default" />

```tsx lines theme={null}
import {
  CometChatMessageBubble,
  CometChatTextBubble,
} from "@cometchat/chat-uikit-react";

function MessageItem({ message, alignment }) {
  return (
    <CometChatMessageBubble
      message={message}
      alignment={alignment}
      contentView={
        <CometChatTextBubble message={message} isSentByMe={alignment === "right"} />
      }
    />
  );
}
```

<Note>
  Message bubbles are **self-extracting**: each bubble takes the SDK `message` and derives its own content (text, attachments, caption, poll data, call info, action text), reading the logged-in user, theme, and locale from hooks. Pass just `message` to render a bubble standalone — no plugin or pre-extracted props required. `CometChatTextBubble` also accepts an optional `text` override so media bubbles can render captions through it.
</Note>

## Shared Chrome Elements

| Element           | When Shown                                        | Source                                                    |
| ----------------- | ------------------------------------------------- | --------------------------------------------------------- |
| Avatar            | Incoming + group + `!hideAvatar`                  | `message.getSender().getAvatar()`                         |
| Sender name       | Incoming + group + `!hideSenderName`              | `message.getSender().getName()`                           |
| Bubble background | Always                                            | Type-specific: primary for outgoing, neutral for incoming |
| Timestamp         | `!hideTimestamp`                                  | `message.getSentAt()` via `CometChatDate`                 |
| Receipts          | Outgoing + `!hideReceipts`                        | `message.getReadAt()` / `getDeliveredAt()`                |
| Edited indicator  | `message.getEditedAt()` truthy                    | "(edited)" text                                           |
| Thread replies    | `message.getReplyCount() > 0` + `!hideThreadView` | Reply count button                                        |
| Context menu      | `options.length > 0` + `!disableInteraction`      | Hover/click                                               |

## GlobalConfig Integration

`hideReceipts` reads from `GlobalConfigContext` when the prop is not explicitly set:

```tsx lines theme={null}
<GlobalConfigProvider config={{ hideReceipts: true }}>
  {/* All bubbles hide receipts unless overridden */}
  <CometChatMessageBubble hideReceipts={false} ... />  {/* This one shows receipts */}
</GlobalConfigProvider>
```

## Props

### message

The SDK message object. **Required.**

|      |                         |
| ---- | ----------------------- |
| Type | `CometChat.BaseMessage` |

***

### alignment

Bubble alignment: `'left'` (incoming), `'right'` (outgoing), `'center'` (action).

|      |                                 |
| ---- | ------------------------------- |
| Type | `'left' \| 'right' \| 'center'` |

***

### contentView

The inner content from the plugin's `renderBubble()`. **Required.**

|      |             |
| ---- | ----------- |
| Type | `ReactNode` |

***

### group

Group context. Enables avatar and sender name display.

|         |                   |
| ------- | ----------------- |
| Type    | `CometChat.Group` |
| Default | `undefined`       |

***

### hideAvatar / hideSenderName / hideTimestamp / hideThreadView

Per-bubble display controls. Not in GlobalConfig.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideReceipts

Hide receipt indicators. Reads from GlobalConfig if not set.

|         |                                                        |
| ------- | ------------------------------------------------------ |
| Type    | `boolean`                                              |
| Default | `undefined` (falls back to GlobalConfig, then `false`) |

***

### showError

Show error receipt icon instead of normal receipts.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### disableInteraction

Disable hover options and keyboard interactions.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### options

Context menu options for this message (the hover/overflow actions).

|         |                            |
| ------- | -------------------------- |
| Type    | `CometChatMessageOption[]` |
| Default | `undefined`                |

***

### quickOptionsCount

Number of quick options shown directly; the rest move to the overflow menu.

|         |          |
| ------- | -------- |
| Type    | `number` |
| Default | `2`      |

***

### forceShowAvatar

Force-show the avatar for incoming messages even in 1:1 chats (used by agent chat).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### messageSentAtDateTimeFormat

Override the date format for the sent-at timestamp shown beside the bubble.

|         |                             |
| ------- | --------------------------- |
| Type    | `CometChatDateFormatConfig` |
| Default | `undefined`                 |

***

### View override props

Render-prop overrides for each region of the bubble. Semantics for all of them: omit (`undefined`) to use the built-in default, pass `null` to suppress the region, or pass a function/node to override it.

| Prop             | Type                               | Overrides                                      |
| ---------------- | ---------------------------------- | ---------------------------------------------- |
| `leadingView`    | `((message) => ReactNode) \| null` | Leading view (avatar area)                     |
| `headerView`     | `((message) => ReactNode) \| null` | Header view (sender name area)                 |
| `statusInfoView` | `((message) => ReactNode) \| null` | Status info (timestamp + receipts)             |
| `footerView`     | `((message) => ReactNode) \| null` | Footer (reactions area)                        |
| `threadView`     | `((message) => ReactNode) \| null` | Thread reply view                              |
| `replyView`      | `ReactNode \| null`                | Reply preview (quoted message) above content   |
| `bottomView`     | `((message) => ReactNode) \| null` | View below the bubble (e.g. moderation footer) |

***

### Callback props

| Prop                   | Signature                                                                  | Fires when                                     |
| ---------------------- | -------------------------------------------------------------------------- | ---------------------------------------------- |
| `onAvatarClick`        | `(user: CometChat.User) => void`                                           | The avatar is clicked                          |
| `onThreadRepliesClick` | `(message: CometChat.BaseMessage) => void`                                 | The thread view is clicked                     |
| `onOptionClick`        | `(option: CometChatMessageOption, message: CometChat.BaseMessage) => void` | A context menu option is clicked               |
| `onReactionChipClick`  | `(messageId: number, emoji: string) => void`                               | A reaction chip is clicked (toggle add/remove) |
| `onReactorClick`       | `(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void`   | A reactor in the reaction list is clicked      |

***

### Accessibility & advanced props

| Prop                      | Type                  | Default     | Description                                                                                                 |
| ------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------------------------------------- |
| `isSelected`              | `boolean`             | `false`     | Whether this message is selected                                                                            |
| `ariaPosinset`            | `number`              | —           | Position in the message list (1-indexed)                                                                    |
| `ariaSetsize`             | `number`              | —           | Total messages in the list                                                                                  |
| `className`               | `string`              | —           | Additional CSS class on the root element                                                                    |
| `setRef`                  | `Ref<HTMLDivElement>` | —           | Ref to the outermost wrapper div (`role="article"`)                                                         |
| `includeBottomViewHeight` | `boolean`             | `false`     | Use `fit-content` height for the options toolbar (useful with a `bottomView`)                               |
| `toggleOptionsVisibility` | `boolean`             | `undefined` | Explicitly control options toolbar visibility (`true` = always, `false` = never, `undefined` = hover-based) |

## CSS Selectors

| Target           | Selector                                           |
| ---------------- | -------------------------------------------------- |
| Wrapper          | `.cometchat-message-bubble__wrapper`               |
| Outgoing wrapper | `.cometchat-message-bubble__wrapper--outgoing`     |
| Avatar area      | `.cometchat-message-bubble__leading-view`          |
| Bubble container | `.cometchat-message-bubble`                        |
| Incoming         | `.cometchat-message-bubble-incoming`               |
| Outgoing         | `.cometchat-message-bubble-outgoing`               |
| Action (center)  | `.cometchat-message-bubble-action`                 |
| Sender name      | `.cometchat-message-bubble__sender-name`           |
| Body             | `.cometchat-message-bubble__body`                  |
| Content          | `.cometchat-message-bubble__body-content-view`     |
| Status info      | `.cometchat-message-bubble__body-status-info-view` |
| Receipts         | `.cometchat-receipts`                              |
| Thread button    | `.cometchat-message-bubble__thread-button`         |


# Message Composer
Source: https://www.cometchat.com/docs/ui-kit/react/components/message-composer

Rich text input with attachments, emoji, voice recording, mentions, and formatting for sending messages.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatMessageComposer",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatMessageComposer } from \"@cometchat/chat-uikit-react\";",
    "description": "Rich text input with attachments, emoji, voice recording, mentions, and formatting for sending messages.",
    "cssRootClass": ".cometchat-message-composer",
    "primaryOutput": {
      "prop": "onSendButtonClick",
      "type": "(message: CometChat.BaseMessage, mode?: 'send' | 'edit') => void"
    },
    "props": {
      "entity": {
        "user": { "type": "CometChat.User", "default": "undefined" },
        "group": { "type": "CometChat.Group", "default": "undefined" },
        "parentMessageId": { "type": "number", "default": "undefined" }
      },
      "layout": {
        "layout": {
          "type": "CometChatMessageComposerLayout",
          "values": ["'compact'", "'multiline'"],
          "default": "'compact'"
        }
      },
      "textInput": {
        "initialText": { "type": "string", "default": "undefined" },
        "text": { "type": "string", "default": "undefined", "note": "Controlled mode — consumer owns state" },
        "placeholder": { "type": "string", "default": "'Type a message...'" },
        "enterKeyBehavior": {
          "type": "'send' | 'newline' | 'none'",
          "default": "'send'"
        },
        "maxInputHeight": { "type": "number", "default": "200" }
      },
      "richText": {
        "enableRichTextEditor": { "type": "boolean", "default": false },
        "hideRichTextFormattingOptions": { "type": "boolean", "default": false },
        "showBubbleMenuOnSelection": { "type": "boolean", "default": false }
      },
      "editReply": {
        "messageToEdit": { "type": "CometChat.TextMessage | null", "default": "null" },
        "messageToReply": { "type": "CometChat.BaseMessage | null", "default": "null" }
      },
      "attachments": {
        "attachmentOptions": { "type": "CometChatComposerAttachmentOption[]", "default": "undefined" },
        "hideAttachmentOptions": { "type": "CometChatAttachmentHideOptions", "default": "undefined" },
        "showAttachmentPreview": { "type": "boolean", "default": true },
        "enableMultipleAttachments": { "type": "boolean", "default": true, "note": "Enable multi-attachment staging tray and batch send. Set false for legacy single-select behavior." },
        "disableDragAndDrop": { "type": "boolean", "default": false, "note": "Disable drag-and-drop file upload." },
        "allowedFileTypes": { "type": "string[]", "default": "undefined" }
      },
      "hideButtons": {
        "hideAttachmentButton": { "type": "boolean", "default": false },
        "hideEmojiKeyboardButton": { "type": "boolean", "default": false },
        "hideVoiceRecordingButton": { "type": "boolean", "default": false },
        "hideStickersButton": { "type": "boolean", "default": false },
        "hideAIButton": { "type": "boolean", "default": true },
        "hideLiveReaction": { "type": "boolean", "default": false },
        "hideSendButton": { "type": "boolean", "default": false },
        "hideError": { "type": "boolean", "default": false }
      },
      "mentions": {
        "textFormatters": { "type": "CometChatTextFormatter[]", "default": "undefined" },
        "disableMentions": { "type": "boolean", "default": false },
        "disableMentionAll": { "type": "boolean", "default": false },
        "mentionAllLabel": { "type": "string", "default": "'all'" },
        "mentionsUsersRequestBuilder": { "type": "CometChat.UsersRequestBuilder", "default": "undefined" },
        "mentionsGroupMembersRequestBuilder": { "type": "CometChat.GroupMembersRequestBuilder", "default": "undefined" }
      },
      "sound": {
        "disableTypingEvents": { "type": "boolean", "default": false },
        "disableSoundForMessage": { "type": "boolean", "default": false },
        "customSoundForMessage": { "type": "string", "default": "undefined" }
      },
      "misc": {
        "disableAutoFocusOnMobile": { "type": "boolean", "default": true },
        "liveReactionIcon": { "type": "string", "default": "undefined" },
        "showScrollbar": { "type": "boolean", "default": false }
      },
      "customViews": {
        "attachmentButtonIconView": "ReactNode",
        "voiceRecordingButtonIconView": "ReactNode",
        "emojiButtonIconView": "ReactNode",
        "sendButtonView": "ReactNode",
        "auxiliaryButtonView": "ReactNode",
        "headerView": "ReactNode"
      },
      "callbacks": {
        "onTextChange": "(text: string) => void",
        "onSendButtonClick": "(message: CometChat.BaseMessage, mode?: 'send' | 'edit') => void",
        "sendTextMessageOverride": "(text: string, richTextHtml?: string) => string",
        "onError": "(error: unknown) => void",
        "onClosePreview": "() => void",
        "onAttachmentAdded": "(file: File) => void",
        "onAttachmentRemoved": "(file: File) => void",
        "onMentionSelected": "(user: CometChat.User | CometChat.GroupMember) => void"
      }
    },
    "events": {
      "emitted": [
        { "name": "ui:message/sent", "payload": "{ message, status }", "description": "Message sent (inprogress → success/error)" },
        { "name": "ui:compose/edit", "payload": "{ message, status }", "description": "Message edit (inprogress → success/error/cancelled)" },
        { "name": "ui:compose/reply", "payload": "{ message, status }", "description": "Reply context set/cleared" },
        { "name": "ui:compose/recording-started", "payload": "{ composerInstanceId }", "description": "Voice recording started (stops other instances)" }
      ],
      "received": [
        { "name": "ui:compose/edit", "payload": "{ message, status: 'inprogress' }", "description": "Enters edit mode for the message" },
        { "name": "ui:compose/reply", "payload": "{ message, status: 'inprogress' }", "description": "Sets reply-to message" },
        { "name": "ui:compose/text", "payload": "{ text }", "description": "Sets the composer text programmatically" },
        { "name": "ui:compose/recording-started", "payload": "{ composerInstanceId }", "description": "Stops own recording if another instance started" }
      ]
    },
    "sdkListeners": [],
    "types": {
      "CometChatMessageComposerLayout": "'compact' | 'multiline'",
      "CometChatAttachmentHideOptions": {
        "image": "boolean | undefined",
        "video": "boolean | undefined",
        "audio": "boolean | undefined",
        "file": "boolean | undefined",
        "polls": "boolean | undefined",
        "collaborativeDocument": "boolean | undefined",
        "collaborativeWhiteboard": "boolean | undefined"
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatMessageComposer` is a rich text input component for sending messages. It supports attachments, emoji, voice recording, mentions, rich text formatting, and reply/edit previews. Wire it alongside `CometChatMessageList` and `CometChatMessageHeader` to build a complete messaging experience.

<Info>
  **Live Preview** — interact with the default message composer.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-messages-cometchat-message-composer--default)
</Info>

<iframe title="CometChat Message Composer — Default" />

The component handles:

* Text input with placeholder and auto-resize
* Rich text formatting (bold, italic, links, code, lists)
* File attachments with preview thumbnails
* Emoji keyboard
* Voice recording
* @mentions with user/group member search
* Edit and reply mode with preview banners
* Typing indicator events
* Live reactions

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react";

function ChatPanel({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageComposer
      user={user}
      onSendButtonClick={(message, mode) => {
        console.log(`Message ${mode}:`, message);
      }}
    />
  );
}
```

### Compound Composition

```tsx theme={null}
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react";

function ChatPanel({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageComposer.Root user={user}>
      <CometChatMessageComposer.Header />
      <CometChatMessageComposer.EditPreview />
      <CometChatMessageComposer.ReplyPreview />
      <CometChatMessageComposer.Input />
      <CometChatMessageComposer.AuxiliaryButtons />
      <CometChatMessageComposer.AttachmentButton />
      <CometChatMessageComposer.EmojiButton />
      <CometChatMessageComposer.VoiceButton />
      <CometChatMessageComposer.AIButton />
      <CometChatMessageComposer.SendButton />
      <CometChatMessageComposer.Footer />
    </CometChatMessageComposer.Root>
  );
}
```

### Full Layout Example

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

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

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setUser(entity as CometChat.User);
      setGroup(undefined);
    } else {
      setGroup(entity as CometChat.Group);
      setUser(undefined);
    }
  };

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>
      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        <CometChatMessageHeader user={user} group={group} />
        <CometChatMessageList user={user} group={group} />
        <CometChatMessageComposer user={user} group={group} />
      </div>
    </div>
  );
}
```

***

## Multi-Attachment Staging Tray

When `enableMultipleAttachments` is `true` (the default), picking a file does **not** send it immediately. Files are **staged in a tray** above the input, uploaded in the background, and sent together when the user hits send. This is the composer half of the end-to-end multi-attachment flow:

1. **Pick** — choose files from the attachment (`+`) menu, drag-and-drop them onto the composer (unless [`disableDragAndDrop`](#disabledraganddrop) is set), or paste image/file data straight into the composer — pasted media stages into the tray just like a pick.
2. **Stage & upload** — each file becomes a tile in the tray and begins uploading directly to storage right away, showing its own progress. The user can keep typing or add more files while uploads run. The voice-recording button hides while attachments are staged.
3. **Review** — remove any tile, or retry one whose upload failed. A file that can't be accepted shows why on hover (see [Why a file is rejected](#why-a-file-is-rejected)).
4. **Send** — on send, the staged files fan out into media messages that share a single batch, so the message list renders them as a connected group of [media bubbles](/docs/ui-kit/react/components/image-bubble) (see [Batch send](#batch-send)).

<Info>
  **Live Preview** — interact with the message composer staging tray.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-messages-cometchat-message-composer-tray--success)
</Info>

<iframe title="CometChat Message Composer — Staging Tray (Success States)" />

### Tray item states

Each staged file is a tile with its own upload lifecycle:

| State       | Meaning                                         | Tile UI                              | Retryable |
| ----------- | ----------------------------------------------- | ------------------------------------ | --------- |
| `uploading` | Bytes are transferring                          | Progress ring with percentage        | —         |
| `success`   | Uploaded, ready to send                         | Thumbnail (image/video) or file card | —         |
| `failed`    | Transfer failed (transient — e.g. network drop) | Retry control on the tile            | Yes       |
| `rejected`  | File not accepted (see below)                   | Rejected marker + hover tooltip      | No        |

This mirrors the underlying SDK upload semantics: **failed** uploads are transient and can be retried, while **rejected** files must be swapped out.

### Attachment limits

* **Count** — a single batch can hold up to a configurable maximum (default **10**, from the `file.count.max` app setting, resolved at runtime). The limit is **all-or-nothing**: if a pick would push the tray past the maximum, the **entire new selection is rejected** — nothing is staged — and a validation banner is shown. The composer does **not** partially accept a subset of files to fill the remaining slots.
* **Per-file size** — a file larger than the allowed size (`file.size.max`) is rejected as an individual tile.

### Why a file is rejected

A rejected tile explains itself on hover via a tooltip:

| Reason                        | What the tooltip conveys                                                               |
| ----------------------------- | -------------------------------------------------------------------------------------- |
| File exceeds the maximum size | The file is too large, including the configured size limit in MB.                      |
| File type not permitted       | The file's type is blocked by your app's role-based file-type permissions (RBAC/SBAC). |

<Note>
  The per-file **size** and **type** rejections surface on the individual tile (with the hover tooltip above). The **count** limit is different — it rejects the whole over-limit pick at once and surfaces as a validation banner, not a per-tile tooltip.
</Note>

### Batch send

On send, the staged files are grouped by media kind and sent as **one media message per kind**, in a fixed order — **images → videos → audio → files** — with all of the resulting messages sharing a single `batchId`. The composer's **text is sent as the batch caption**, carried on the **last** message of the batch; when you're replying, the **quoted message is attached to the first**. The [message list](/docs/ui-kit/react/components/message-list#multi-attachment-batch-grouping) groups messages with the same `batchId` and renders them as one visually connected set, with shared avatar/sender on the first bubble and receipts on the last.

### Disabling the tray

Set [`enableMultipleAttachments`](#enablemultipleattachments) to `false` to revert to legacy single-select, send-immediately behavior: each attachment option sends one file straight away, with no staging tray. **Pasting or dropping files behaves the same way** — the first file is sent immediately, matching the attachment picker (whether you pick, paste, or drop, only a single attachment is sent).

***

## Actions and Events

### Callback Props

| Prop                  | Signature                                                           | Fires when                             |
| --------------------- | ------------------------------------------------------------------- | -------------------------------------- |
| `onSendButtonClick`   | `(message: CometChat.BaseMessage, mode?: 'send' \| 'edit') => void` | Message is sent or edited              |
| `onTextChange`        | `(text: string) => void`                                            | Text content changes                   |
| `onError`             | `(error: unknown) => void`                                          | An error occurs                        |
| `onClosePreview`      | `() => void`                                                        | Reply/edit preview is closed           |
| `onAttachmentAdded`   | `(file: File) => void`                                              | File attachment is added               |
| `onAttachmentRemoved` | `(file: File) => void`                                              | File attachment is removed             |
| `onMentionSelected`   | `(user: CometChat.User \| CometChat.GroupMember) => void`           | A mention is selected from suggestions |

### Events Emitted

UI events this component publishes:

| Event                          | Payload                  | Fires when                                          |
| ------------------------------ | ------------------------ | --------------------------------------------------- |
| `ui:message/sent`              | `{ message, status }`    | Message sent (inprogress → success/error)           |
| `ui:compose/edit`              | `{ message, status }`    | Message edit (inprogress → success/error/cancelled) |
| `ui:compose/reply`             | `{ message, status }`    | Reply context set/cleared                           |
| `ui:compose/recording-started` | `{ composerInstanceId }` | Voice recording started (stops other instances)     |

### Events Received

UI events this component subscribes to (published by other components):

| Event                          | Payload                             | Behavior                                        |
| ------------------------------ | ----------------------------------- | ----------------------------------------------- |
| `ui:compose/edit`              | `{ message, status: 'inprogress' }` | Enters edit mode for the message                |
| `ui:compose/reply`             | `{ message, status: 'inprogress' }` | Sets reply-to message                           |
| `ui:compose/text`              | `{ text }`                          | Sets the composer text programmatically         |
| `ui:compose/recording-started` | `{ composerInstanceId }`            | Stops own recording if another instance started |

### SDK Listeners (Automatic)

The composer does not subscribe to SDK listeners directly. It relies on typing indicator events emitted via the SDK when `disableTypingEvents` is `false`.

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatMessageComposer
  user={user}
  headerView={<MyCustomHeader />}
  sendButtonView={<MyCustomSendButton />}
  attachmentButtonIconView={<PaperclipIcon />}
  emojiButtonIconView={<SmileyIcon />}
  voiceRecordingButtonIconView={<MicIcon />}
  auxiliaryButtonView={<GifButton />}
/>
```

| Slot                           | Type        | Replaces                               |
| ------------------------------ | ----------- | -------------------------------------- |
| `attachmentButtonIconView`     | `ReactNode` | Icon inside the attachment button      |
| `voiceRecordingButtonIconView` | `ReactNode` | Icon inside the voice recording button |
| `emojiButtonIconView`          | `ReactNode` | Icon inside the emoji button           |
| `sendButtonView`               | `ReactNode` | Content inside the send button         |
| `auxiliaryButtonView`          | `ReactNode` | Additional buttons in the actions area |
| `headerView`                   | `ReactNode` | Header area above the input            |

#### attachmentOptions

Override the default attachment options.

<Frame>
  <img />
</Frame>

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react";

function ComposerCustomAttachments({ chatUser }: { chatUser: CometChat.User }) {
  return (
    <CometChatMessageComposer
      user={chatUser}
      attachmentOptions={[
        { id: "image", title: "Photo", iconURL: photoIcon, onClick: () => openPhotoPicker() },
        { id: "file", title: "Document", iconURL: fileIcon, onClick: () => openFilePicker() },
      ]}
    />
  );
}
```

#### auxiliaryButtonView

Replace the auxiliary button area.

<Frame>
  <img />
</Frame>

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatMessageComposer, CometChatButton } from "@cometchat/chat-uikit-react";

function ComposerCustomAuxiliary({ chatUser }: { chatUser: CometChat.User }) {
  return (
    <CometChatMessageComposer
      user={chatUser}
      auxiliaryButtonView={
        <CometChatButton.Root onClick={() => {}}>
          <CometChatButton.Icon />
        </CometChatButton.Root>
      }
    />
  );
}
```

#### sendButtonView

Replace the send button.

<Frame>
  <img />
</Frame>

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatMessageComposer, CometChatButton } from "@cometchat/chat-uikit-react";

function ComposerCustomSend({ chatUser }: { chatUser: CometChat.User }) {
  return (
    <CometChatMessageComposer
      user={chatUser}
      sendButtonView={
        <CometChatButton.Root onClick={() => {}}>
          <CometChatButton.Icon />
        </CometChatButton.Root>
      }
    />
  );
}
```

### Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

```tsx theme={null}
<CometChatMessageComposer.Root user={user}>
  {/* No Header, EditPreview, or ReplyPreview — they won't render */}
  <CometChatMessageComposer.Input />
  <CometChatMessageComposer.SendButton />
</CometChatMessageComposer.Root>
```

Available sub-components:

| Sub-component      | Description                    | Props                       | Flat API equivalent            |
| ------------------ | ------------------------------ | --------------------------- | ------------------------------ |
| `Root`             | Context provider and container | All Root props + `children` | —                              |
| `Input`            | Text input area                | `className`                 | —                              |
| `SendButton`       | Send/edit button               | `children`, `className`     | `sendButtonView` (as children) |
| `AttachmentButton` | Attachment picker              | `hideOptions`, `className`  | `attachmentButtonIconView`     |
| `EmojiButton`      | Emoji keyboard toggle          | `className`                 | `emojiButtonIconView`          |
| `VoiceButton`      | Voice recording toggle         | `className`                 | `voiceRecordingButtonIconView` |
| `EditPreview`      | Edit mode preview banner       | `className`                 | —                              |
| `ReplyPreview`     | Reply mode preview banner      | `className`                 | —                              |
| `AuxiliaryButtons` | Custom auxiliary buttons       | `children`, `className`     | `auxiliaryButtonView`          |
| `AIButton`         | AI features toggle             | `className`                 | —                              |
| `Header`           | Header area                    | `children`, `className`     | `headerView`                   |
| `Footer`           | Footer area                    | `children`, `className`     | —                              |

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-message-composer {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-message-composer__input-area {
  border-radius: 12px;
}
```

***

## Props

All props are optional unless noted.

<Note>
  View slot props (`headerView`, `sendButtonView`, `auxiliaryButtonView`, `attachmentButtonIconView`, `voiceRecordingButtonIconView`, `emojiButtonIconView`) are convenience props available only on the flat API. In compound composition mode, use the corresponding sub-components directly or pass children to them.
</Note>

***

### Entity

***

#### user

User for 1:1 conversations.

|         |                  |
| ------- | ---------------- |
| Type    | `CometChat.User` |
| Default | `undefined`      |

***

#### group

Group for group conversations.

|         |                   |
| ------- | ----------------- |
| Type    | `CometChat.Group` |
| Default | `undefined`       |

***

#### parentMessageId

Parent message ID for threaded replies.

|         |             |
| ------- | ----------- |
| Type    | `number`    |
| Default | `undefined` |

***

### Layout

***

#### layout

Layout mode for the composer. `compact` keeps everything on one line; `multiline` expands the input area.

|         |                            |
| ------- | -------------------------- |
| Type    | `'compact' \| 'multiline'` |
| Default | `'compact'`                |

***

### Text Input

***

#### initialText

Initial text to pre-fill the input (uncontrolled).

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

#### text

Controlled text value. When provided, the consumer owns the text state and must update it via `onTextChange`.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

#### placeholder

Placeholder text shown when the input is empty.

|         |                       |
| ------- | --------------------- |
| Type    | `string`              |
| Default | `'Type a message...'` |

***

#### enterKeyBehavior

What happens when the user presses Enter.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `'send' \| 'newline' \| 'none'` |
| Default | `'send'`                        |

***

#### maxInputHeight

Maximum height for the input area in pixels before it scrolls.

|         |          |
| ------- | -------- |
| Type    | `number` |
| Default | `200`    |

***

### Rich Text

***

#### enableRichTextEditor

Enable rich text formatting (toolbar, keyboard shortcuts, markdown auto-conversion).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### hideRichTextFormattingOptions

Hide the rich text formatting toolbar (shortcuts still work).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### showBubbleMenuOnSelection

Show a floating bubble menu near selected text with formatting options (desktop only).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### Edit / Reply

***

#### messageToEdit

Message to edit (triggers edit mode).

|         |                                 |
| ------- | ------------------------------- |
| Type    | `CometChat.TextMessage \| null` |
| Default | `null`                          |

***

#### messageToReply

Message to reply to (triggers reply mode with preview).

|         |                                 |
| ------- | ------------------------------- |
| Type    | `CometChat.BaseMessage \| null` |
| Default | `null`                          |

***

### Attachments

***

#### attachmentOptions

Custom attachment options (overrides plugin-provided ones).

|         |                                       |
| ------- | ------------------------------------- |
| Type    | `CometChatComposerAttachmentOption[]` |
| Default | `undefined`                           |

***

#### hideAttachmentOptions

Hide specific attachment options in the default layout.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `CometChatAttachmentHideOptions` |
| Default | `undefined`                      |

```tsx theme={null}
<CometChatMessageComposer
  user={user}
  hideAttachmentOptions={{ polls: true, collaborativeWhiteboard: true }}
/>
```

***

#### showAttachmentPreview

Whether to show attachment preview thumbnails before sending.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

#### enableMultipleAttachments

Enable multi-attachment staging tray and batch send. When `true` (default), selecting an attachment option stages files in a tray for a single batched send. When `false`, each attachment option reverts to legacy single-select, send-immediately behavior.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

#### disableDragAndDrop

Disable drag-and-drop file upload on the composer.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### allowedFileTypes

Allowed file MIME types for attachments.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `string[]`                      |
| Default | `undefined` (all types allowed) |

***

### Hide Buttons

***

#### hideAttachmentButton

Hide the attachment ("+") button entirely.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### hideEmojiKeyboardButton

Hide the emoji keyboard button.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### hideVoiceRecordingButton

Hide the voice recording button.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### hideStickersButton

Hide the stickers button.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### hideAIButton

Hide the AI button.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

#### hideLiveReaction

Hide the live reaction button.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### hideSendButton

Hide the send button.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### hideError

Hide the error state UI.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### Mentions

***

#### textFormatters

Text formatters pipeline for custom text processing.

|         |                            |
| ------- | -------------------------- |
| Type    | `CometChatTextFormatter[]` |
| Default | `undefined`                |

***

#### disableMentions

Disable @mentions entirely.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### disableMentionAll

Disable the @all mention option in groups.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### mentionAllLabel

Label for the @all mention option.

|         |          |
| ------- | -------- |
| Type    | `string` |
| Default | `'all'`  |

***

#### mentionsUsersRequestBuilder

Custom request builder for mention user search.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `CometChat.UsersRequestBuilder` |
| Default | `undefined`                     |

***

#### mentionsGroupMembersRequestBuilder

Custom request builder for mention group member search.

|         |                                        |
| ------- | -------------------------------------- |
| Type    | `CometChat.GroupMembersRequestBuilder` |
| Default | `undefined`                            |

***

### Sound

***

#### disableTypingEvents

Disable typing indicator events.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### disableSoundForMessage

Disable sound on message send.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

#### customSoundForMessage

Custom sound URL for message send.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### Misc

***

#### disableAutoFocusOnMobile

Disable auto-focus on mobile devices to prevent the keyboard from automatically opening on load.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

#### liveReactionIcon

Custom icon URL for the live reaction button.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

#### showScrollbar

Show the native scrollbar on the input area.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### Custom Views

***

#### attachmentButtonIconView

Custom ReactNode to replace the content inside the attachment button (keeps action wired).

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

#### voiceRecordingButtonIconView

Custom ReactNode to replace the content inside the voice recording button (keeps action wired).

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

#### emojiButtonIconView

Custom ReactNode to replace the content inside the emoji button (keeps action wired).

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

#### sendButtonView

Custom ReactNode to replace the content inside the send button (keeps send/edit action wired).

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

#### auxiliaryButtonView

Custom ReactNode for additional buttons rendered in the actions area before the send button.

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

#### headerView

Custom ReactNode for the header area above the input (replaces edit/reply preview + validation).

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

### Callbacks

***

#### onTextChange

Called when text changes.

|         |                          |
| ------- | ------------------------ |
| Type    | `(text: string) => void` |
| Default | `undefined`              |

***

#### onSendButtonClick

Called when a message is sent or edited.

|         |                                                                     |
| ------- | ------------------------------------------------------------------- |
| Type    | `(message: CometChat.BaseMessage, mode?: 'send' \| 'edit') => void` |
| Default | `undefined`                                                         |

***

#### sendTextMessageOverride

Override the internal SDK sendTextMessage call for optimistic updates. When provided, called instead of `CometChat.sendMessage()`.

|         |                                                   |
| ------- | ------------------------------------------------- |
| Type    | `(text: string, richTextHtml?: string) => string` |
| Default | `undefined`                                       |

***

#### onError

Called when an error occurs.

|         |                            |
| ------- | -------------------------- |
| Type    | `(error: unknown) => void` |
| Default | `undefined`                |

***

#### onClosePreview

Called when reply/edit preview is closed.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

#### onAttachmentAdded

Called when a file attachment is added.

|         |                        |
| ------- | ---------------------- |
| Type    | `(file: File) => void` |
| Default | `undefined`            |

***

#### onAttachmentRemoved

Called when a file attachment is removed.

|         |                        |
| ------- | ---------------------- |
| Type    | `(file: File) => void` |
| Default | `undefined`            |

***

#### onMentionSelected

Called when a mention is selected from the suggestions list.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `(user: CometChat.User \| CometChat.GroupMember) => void` |
| Default | `undefined`                                               |

***

## CSS Selectors

| Target                       | Selector                                                 |
| ---------------------------- | -------------------------------------------------------- |
| Root container               | `.cometchat-message-composer`                            |
| Body wrapper                 | `.cometchat-message-composer__body`                      |
| Input area                   | `.cometchat-message-composer__input-area`                |
| Actions bar                  | `.cometchat-message-composer__actions`                   |
| Attachment button            | `.cometchat-message-composer__attachment-button-wrapper` |
| Emoji button                 | `.cometchat-message-composer__emoji-button-wrapper`      |
| Voice button                 | `.cometchat-message-composer__voice-button-wrapper`      |
| Send button                  | `.cometchat-message-composer__send-button-wrapper`       |
| Sticker button               | `.cometchat-message-composer__sticker-button-wrapper`    |
| AI button                    | `.cometchat-message-composer__ai-button-wrapper`         |
| Staging tray                 | `.cometchat-message-composer__tray`                      |
| Tray overlay (upload status) | `.cometchat-message-composer__tray-overlay`              |
| Tray audio card body         | `.cometchat-message-composer__tray-audio-body`           |
| Tray audio name              | `.cometchat-message-composer__tray-audio-name`           |
| Tray audio slider            | `.cometchat-message-composer__tray-audio-slider`         |
| Tray audio time              | `.cometchat-message-composer__tray-audio-time`           |
| Tray retry button            | `.cometchat-message-composer__tray-retry-button`         |
| Tray rejected icon           | `.cometchat-message-composer__tray-rejected-icon`        |
| Drag-and-drop overlay        | `.cometchat-message-composer__drop-zone`                 |

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="comments" href="/ui-kit/react/components/message-list">
    Display messages for the selected conversation
  </Card>

  <Card title="Thread Header" icon="code-branch" href="/ui-kit/react/components/thread-header">
    Show threaded replies for a parent message
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Message Header
Source: https://www.cometchat.com/docs/ui-kit/react/components/message-header

Toolbar displaying conversation details with avatar, name, presence status, typing indicator, and call buttons.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatMessageHeader",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatMessageHeader } from \"@cometchat/chat-uikit-react\";",
    "description": "Toolbar displaying conversation details with avatar, name, presence status, typing indicator, and call buttons.",
    "cssRootClass": ".cometchat-message-header",
    "primaryOutput": {
      "prop": "onItemClick",
      "type": "(entity: CometChat.User | CometChat.Group) => void"
    },
    "props": {
      "data": {
        "user": {
          "type": "CometChat.User",
          "default": "undefined",
          "note": "For 1-on-1 conversations. Mutually exclusive with group."
        },
        "group": {
          "type": "CometChat.Group",
          "default": "undefined",
          "note": "For group conversations. Mutually exclusive with user."
        },
        "callSettingsBuilder": {
          "type": "any",
          "default": "GlobalConfig.callSettingsBuilder or built-in default",
          "note": "Custom call settings builder for ongoing call sessions."
        },
        "lastActiveAtDateTimeFormat": {
          "type": "CometChatDateFormatConfig",
          "default": "relative time format"
        },
        "summaryGenerationMessageCount": {
          "type": "number",
          "default": 1000
        }
      },
      "callbacks": {
        "onBack": "() => void",
        "onItemClick": "(entity: CometChat.User | CometChat.Group) => void",
        "onSearchOptionClicked": "() => void",
        "onSummaryClick": "() => void",
        "onVoiceCallClick": "(entity: CometChat.User | CometChat.Group) => void",
        "onVideoCallClick": "(entity: CometChat.User | CometChat.Group) => void",
        "onError": "((error: CometChat.CometChatException) => void) | null"
      },
      "visibility": {
        "hideUserStatus": { "type": "boolean", "default": false },
        "hideBackButton": { "type": "boolean", "default": false },
        "showSearchOption": { "type": "boolean", "default": true },
        "showConversationSummaryButton": { "type": "boolean", "default": false },
        "enableAutoSummaryGeneration": { "type": "boolean", "default": false },
        "hideVoiceCallButton": { "type": "boolean", "default": false },
        "hideVideoCallButton": { "type": "boolean", "default": false }
      },
      "viewSlots": {
        "leadingView": "ReactNode",
        "titleView": "ReactNode",
        "subtitleView": "ReactNode",
        "trailingView": "ReactNode",
        "auxiliaryButtonView": "ReactNode"
      }
    },
    "eventsEmitted": [],
    "eventsReceived": [
      {
        "name": "ui:call/rejected",
        "payload": "{ call }",
        "description": "Re-enables call buttons after incoming call rejection"
      },
      {
        "name": "ui:call/ended",
        "payload": "{}",
        "description": "Resets all call state (re-enables buttons, hides call screens)"
      },
      {
        "name": "ui:call/join",
        "payload": "{ sessionId, isAudioOnly, group }",
        "description": "Starts a direct call (user clicked Join on meeting bubble)"
      },
      {
        "name": "ui:active-chat/changed",
        "payload": "{ unreadCount, ... }",
        "description": "Auto-triggers summary when unread >= 15 (if enabled)"
      },
      {
        "name": "ui:group/member-added",
        "payload": "{ group, members, messages }",
        "description": "Updates group member count"
      },
      {
        "name": "ui:group/member-kicked",
        "payload": "{ group, user, message }",
        "description": "Updates group member count"
      },
      {
        "name": "ui:group/member-banned",
        "payload": "{ group, user, message }",
        "description": "Updates group member count"
      },
      {
        "name": "ui:group/left",
        "payload": "{ group }",
        "description": "Updates group member count"
      },
      {
        "name": "ui:group/member-joined",
        "payload": "{ joinedGroup }",
        "description": "Updates group member count"
      },
      {
        "name": "ui:group/ownership-changed",
        "payload": "{ group: CometChat.Group, newOwner: CometChat.User, previousOwnerUid: string }",
        "description": "Updates group member count"
      },
      {
        "name": "ui:group/member-scope-changed",
        "payload": "{ group, user, newScope }",
        "description": "Updates group member count"
      }
    ],
    "sdkListeners": [
      "onUserOnline",
      "onUserOffline",
      "onTypingStarted",
      "onTypingEnded",
      "onGroupMemberJoined",
      "onGroupMemberLeft",
      "onGroupMemberKicked",
      "onGroupMemberBanned",
      "onMemberAddedToGroup",
      "onIncomingCallReceived",
      "onOutgoingCallAccepted",
      "onOutgoingCallRejected",
      "onIncomingCallCancelled"
    ],
    "types": {
      "CometChatDateFormatConfig": {
        "today": "string | undefined",
        "yesterday": "string | undefined",
        "lastWeek": "string | undefined",
        "otherDays": "string | undefined",
        "relativeTime": {
          "minute": "string | undefined",
          "minutes": "string | undefined",
          "hour": "string | undefined",
          "hours": "string | undefined"
        }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatMessageHeader` is a toolbar component that sits at the top of the message panel. It displays the avatar, name, online status (for users), member count (for groups), typing indicator, and call buttons for the active conversation. Wire it with `CometChatMessageList` and `CometChatMessageComposer` to build a complete messaging experience.

<Info>
  **Live Preview** — interact with the default message header.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-messages-cometchat-message-header--user-chat-header)
</Info>

<iframe title="CometChat Message Header — User" />

The component handles:

* Displaying user avatar and name
* Online/offline presence status (for 1-on-1 conversations)
* Group member count (for group conversations)
* Real-time typing indicators
* Voice and video call buttons with call state management
* Back navigation for mobile layouts
* AI conversation summary trigger
* Search option for in-conversation search

> **Note:** `user` and `group` are mutually exclusive. Pass one or the other — not both. The component requires at least one to display anything.

***

## Usage

### Flat API (User Conversation)

```tsx theme={null}
import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";

function MessagePanel({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader
      user={user}
      onItemClick={(entity) => openDetails(entity)}
      onBack={() => navigateBack()}
    />
  );
}
```

### Flat API (Group Conversation)

```tsx theme={null}
import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";

function MessagePanel({ group }: { group: CometChat.Group }) {
  return (
    <CometChatMessageHeader
      group={group}
      onItemClick={(entity) => openDetails(entity)}
      hideVoiceCallButton={true}
    />
  );
}
```

### Compound Composition

```tsx theme={null}
import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";

function CustomHeader({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader.Root user={user} onBack={() => navigateBack()}>
      <CometChatMessageHeader.BackButton />
      <CometChatMessageHeader.Avatar />
      <CometChatMessageHeader.Title />
      <CometChatMessageHeader.Subtitle />
      <CometChatMessageHeader.CallButtons />
      <CometChatMessageHeader.SearchButton />
      <CometChatMessageHeader.AuxiliaryButtons />
    </CometChatMessageHeader.Root>
  );
}
```

### Full Layout Example

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

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

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setUser(entity as CometChat.User);
      setGroup(undefined);
    } else {
      setGroup(entity as CometChat.Group);
      setUser(undefined);
    }
  };

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>
      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        <CometChatMessageHeader user={user} group={group} />
        <CometChatMessageList user={user} group={group} />
        <CometChatMessageComposer user={user} group={group} />
      </div>
    </div>
  );
}
```

***

## Actions and Events

### Callback Props

| Prop                    | Signature                                                 | Fires when                        |
| ----------------------- | --------------------------------------------------------- | --------------------------------- |
| `onBack`                | `() => void`                                              | User clicks the back button       |
| `onItemClick`           | `(entity: CometChat.User \| CometChat.Group) => void`     | User clicks the avatar/name area  |
| `onSearchOptionClicked` | `() => void`                                              | User clicks the search button     |
| `onSummaryClick`        | `() => void`                                              | User clicks the AI summary button |
| `onVoiceCallClick`      | `(entity: CometChat.User \| CometChat.Group) => void`     | User clicks the voice call button |
| `onVideoCallClick`      | `(entity: CometChat.User \| CometChat.Group) => void`     | User clicks the video call button |
| `onError`               | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs                  |

### Events Emitted

This component does not emit any UI events directly. Call initiation publishes call events internally via the SDK.

### Events Received

UI events this component subscribes to (published by other components):

| Event                           | Payload                                 | Behavior                                                       |
| ------------------------------- | --------------------------------------- | -------------------------------------------------------------- |
| `ui:call/rejected`              | `{ call }`                              | Re-enables call buttons after incoming call rejection          |
| `ui:call/ended`                 | `{}`                                    | Resets all call state (re-enables buttons, hides call screens) |
| `ui:call/join`                  | `{ sessionId, isAudioOnly, group }`     | Starts a direct call (user clicked Join on meeting bubble)     |
| `ui:active-chat/changed`        | `{ unreadCount, ... }`                  | Auto-triggers summary when unread >= 15 (if enabled)           |
| `ui:group/member-added`         | `{ group, members, messages }`          | Updates group member count                                     |
| `ui:group/member-kicked`        | `{ group, user, message }`              | Updates group member count                                     |
| `ui:group/member-banned`        | `{ group, user, message }`              | Updates group member count                                     |
| `ui:group/left`                 | `{ group }`                             | Updates group member count                                     |
| `ui:group/member-joined`        | `{ joinedGroup }`                       | Updates group member count                                     |
| `ui:group/ownership-changed`    | `{ group, newOwner, previousOwnerUid }` | Updates group member count                                     |
| `ui:group/member-scope-changed` | `{ group, user, newScope }`             | Updates group member count                                     |

### SDK Listeners (Automatic)

These SDK listeners are attached internally. The component updates its state automatically — no manual subscription needed:

* Presence: `onUserOnline`, `onUserOffline`
* Typing: `onTypingStarted`, `onTypingEnded`
* Groups: `onGroupMemberJoined`, `onGroupMemberLeft`, `onGroupMemberKicked`, `onGroupMemberBanned`, `onMemberAddedToGroup`
* Calls: `onIncomingCallReceived`, `onOutgoingCallAccepted`, `onOutgoingCallRejected`, `onIncomingCallCancelled`

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatMessageHeader
  user={user}
  leadingView={<MyCustomAvatar user={user} />}
  subtitleView={<MyCustomSubtitle />}
  trailingView={<MyCustomActions />}
/>
```

| Slot                  | Type        | Replaces                     |
| --------------------- | ----------- | ---------------------------- |
| `leadingView`         | `ReactNode` | Avatar area                  |
| `titleView`           | `ReactNode` | Display name                 |
| `subtitleView`        | `ReactNode` | Status / typing indicator    |
| `trailingView`        | `ReactNode` | Call buttons + overflow menu |
| `auxiliaryButtonView` | `ReactNode` | Auxiliary button area        |

#### Custom item layout

Combine `leadingView`, `titleView`, and `subtitleView` to fully replace the header's item area.

<Frame>
  <img />
</Frame>

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatMessageHeader, CometChatAvatar } from "@cometchat/chat-uikit-react";

function CustomItemViewHeader({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageHeader
      user={user}
      leadingView={
        <CometChatAvatar.Root name={user.getName()} image={user.getAvatar()}>
          <CometChatAvatar.Image />
          <CometChatAvatar.Initials />
        </CometChatAvatar.Root>
      }
      titleView={<span>{user.getName()}</span>}
      subtitleView={<span>{user.getStatus()}</span>}
    />
  );
}
```

#### titleView

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";

    function CustomTitleHeader({ user }: { user: CometChat.User }) {
      return (
        <CometChatMessageHeader
          user={user}
          titleView={
            <div className="message-header__title-view">
              <span className="message-header__title-view-name">
                {user.getName() + " • "}
              </span>
              <span className="message-header__title-view-status">
                {user.getStatusMessage()}
              </span>
            </div>
          }
        />
      );
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-message-header .message-header__title-view {
      display: flex;
      gap: 4px;
      width: 100%;
    }

    .message-header__title-view-name {
      color: #141414;
      font: 500 16px/19.2px Roboto;
    }

    .message-header__title-view-status {
      color: #6852d6;
      font: 400 16px/19.2px Roboto;
    }
    ```
  </Tab>
</Tabs>

#### subtitleView

<Frame>
  <img />
</Frame>

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";

function CustomSubtitleHeader({ group }: { group: CometChat.Group }) {
  return (
    <CometChatMessageHeader
      group={group}
      subtitleView={
        <>{group.getMembersCount() + " • " + group.getDescription()}</>
      }
    />
  );
}
```

#### leadingView

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatMessageHeader, CometChatAvatar } from "@cometchat/chat-uikit-react";

    function CustomLeadingHeader({ user }: { user: CometChat.User }) {
      return (
        <CometChatMessageHeader
          user={user}
          leadingView={
            <div className="message-header__leading-view">
              <CometChatAvatar.Root image={user.getAvatar()} name={user.getName()}>
                <CometChatAvatar.Image />
                <CometChatAvatar.Initials />
              </CometChatAvatar.Root>
              <span className="message-header__leading-view-role">
                {user.getRole()}
              </span>
            </div>
          }
        />
      );
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .message-header__leading-view {
      display: flex;
      flex-direction: column;
      align-items: center;
      gap: 4px;
    }

    .message-header__leading-view-role {
      color: #6852d6;
      font: 600 8px Roboto;
    }
    ```
  </Tab>
</Tabs>

### Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

```tsx theme={null}
<CometChatMessageHeader.Root user={user}>
  {/* No BackButton — it won't render */}
  <CometChatMessageHeader.Avatar />
  <CometChatMessageHeader.Title />
  <CometChatMessageHeader.Subtitle />
  {/* No CallButtons — they won't render */}
</CometChatMessageHeader.Root>
```

Available sub-components:

| Sub-component      | Description                    | Props                       | Flat API equivalent   |
| ------------------ | ------------------------------ | --------------------------- | --------------------- |
| `Root`             | Context provider and container | All Root props + `children` | —                     |
| `BackButton`       | Back navigation button         | `className`                 | —                     |
| `Avatar`           | User/group avatar              | `className`                 | `leadingView`         |
| `Title`            | Display name                   | `className`                 | `titleView`           |
| `Subtitle`         | Status / typing indicator      | `className`                 | `subtitleView`        |
| `CallButtons`      | Voice and video call buttons   | `className`                 | —                     |
| `SearchButton`     | Search trigger                 | `onClick`, `className`      | —                     |
| `SummaryButton`    | AI summary trigger             | `onClick`, `className`      | —                     |
| `OverflowMenu`     | Additional actions             | `className`                 | —                     |
| `AuxiliaryButtons` | Custom auxiliary buttons       | `children`, `className`     | `auxiliaryButtonView` |

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-message-header {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-message-header__call-buttons {
  gap: 12px;
}
```

***

## Props

All props are optional (but you need either `user` or `group` for the component to display anything).

<Note>
  View slot props (`leadingView`, `titleView`, `subtitleView`, `trailingView`, `auxiliaryButtonView`) are convenience props available only on the flat API. In compound composition mode, use the corresponding sub-components directly.
</Note>

***

### user

The user to display in the header. Use for 1-on-1 conversations. Mutually exclusive with `group`.

|         |                  |
| ------- | ---------------- |
| Type    | `CometChat.User` |
| Default | `undefined`      |

***

### group

The group to display in the header. Use for group conversations. Mutually exclusive with `user`.

|         |                   |
| ------- | ----------------- |
| Type    | `CometChat.Group` |
| Default | `undefined`       |

***

### hideUserStatus

Hide the online/offline status indicator in the subtitle.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideBackButton

Hide the back navigation button. Useful on desktop layouts where back navigation is unnecessary.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showSearchOption

Whether to show the search button in the header toolbar.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### showConversationSummaryButton

Whether to show the AI conversation summary button.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### enableAutoSummaryGeneration

Auto-trigger conversation summary when unread message count >= 15. Requires `showConversationSummaryButton` to be `true` and `onSummaryClick` to be provided.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### summaryGenerationMessageCount

Number of last messages to include in the summary request. Passed to the `onSummaryClick` callback via context.

|         |          |
| ------- | -------- |
| Type    | `number` |
| Default | `1000`   |

***

### hideVoiceCallButton

Hide the voice call button.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideVideoCallButton

Hide the video call button.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### callSettingsBuilder

Custom call settings builder for ongoing call sessions. Passed to the OngoingCall component when a call is started. Falls back to `GlobalConfig.callSettingsBuilder`, then the built-in default.

|         |                                                        |
| ------- | ------------------------------------------------------ |
| Type    | `any`                                                  |
| Default | `GlobalConfig.callSettingsBuilder` or built-in default |

***

### lastActiveAtDateTimeFormat

Custom date/time format for the "last active" timestamp shown in the subtitle when the user is offline.

|         |                             |
| ------- | --------------------------- |
| Type    | `CometChatDateFormatConfig` |
| Default | Relative time format        |

***

### onBack

Callback when the back button is clicked.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onItemClick

Callback when the header item (avatar/name area) is clicked. Typically used to open a details panel.

|         |                                                       |
| ------- | ----------------------------------------------------- |
| Type    | `(entity: CometChat.User \| CometChat.Group) => void` |
| Default | `undefined`                                           |

***

### onSearchOptionClicked

Callback when the search button is clicked.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onSummaryClick

Callback when the AI conversation summary button is clicked.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onVoiceCallClick

Callback when the voice call button is clicked. When provided, overrides the default call initiation behavior.

|         |                                                       |
| ------- | ----------------------------------------------------- |
| Type    | `(entity: CometChat.User \| CometChat.Group) => void` |
| Default | `undefined` (uses built-in call initiation)           |

***

### onVideoCallClick

Callback when the video call button is clicked. When provided, overrides the default call initiation behavior.

|         |                                                       |
| ------- | ----------------------------------------------------- |
| Type    | `(entity: CometChat.User \| CometChat.Group) => void` |
| Default | `undefined` (uses built-in call initiation)           |

***

### onError

Callback when an SDK error occurs during call operations or other internal processes.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `null`                                                    |

***

## CSS Selectors

| Target         | Selector                                    |
| -------------- | ------------------------------------------- |
| Root container | `.cometchat-message-header`                 |
| Back button    | `.cometchat-message-header__back-button`    |
| Avatar         | `.cometchat-message-header__avatar`         |
| Content area   | `.cometchat-message-header__content`        |
| Title          | `.cometchat-message-header__title`          |
| Subtitle       | `.cometchat-message-header__subtitle`       |
| Trailing area  | `.cometchat-message-header__trailing`       |
| Call buttons   | `.cometchat-message-header__call-buttons`   |
| Search button  | `.cometchat-message-header__search-button`  |
| Summary button | `.cometchat-message-header__summary-button` |

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="comments" href="/ui-kit/react/components/message-list">
    Display messages for the active conversation
  </Card>

  <Card title="Message Composer" icon="pen" href="/ui-kit/react/components/message-composer">
    Compose and send messages
  </Card>

  <Card title="Thread Header" icon="code-branch" href="/ui-kit/react/components/thread-header">
    Header for threaded message views
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Message Information
Source: https://www.cometchat.com/docs/ui-kit/react/components/message-information

Displays detailed message information including delivery and read receipts for 1-on-1 and group conversations.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatMessageInformation",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatMessageInformation } from \"@cometchat/chat-uikit-react\";",
    "description": "Displays detailed message information including delivery and read receipts for 1-on-1 and group conversations.",
    "cssRootClass": ".cometchat-message-information",
    "primaryOutput": {
      "prop": "onClose",
      "type": "() => void"
    },
    "props": {
      "data": {
        "message": { "type": "CometChat.BaseMessage", "note": "Required. The message to show information for." },
        "messageInfoDateTimeFormat": { "type": "CometChatMessageInformationCalendarObject", "note": "Custom date format for receipt timestamps (read/delivered)." },
        "messageSentAtDateTimeFormat": { "type": "CometChatMessageInformationCalendarObject", "note": "Format for the sent-at timestamp on the message bubble preview." },
        "textFormatters": { "type": "CometChatTextFormatter[]", "note": "Text formatters for the message bubble preview." },
        "showScrollbar": { "type": "boolean", "default": false, "note": "Whether to show the scrollbar in the content area." },
        "className": { "type": "string", "note": "Optional custom className for the root element." }
      },
      "callbacks": {
        "onClose": { "type": "() => void", "note": "Called when the panel close button is clicked." },
        "onError": { "type": "(error: unknown) => void", "note": "Called when an SDK error occurs." }
      },
      "visibility": {
        "showScrollbar": { "type": "boolean", "default": "false", "note": "Whether to show the scrollbar in the content area." }
      }
    },
    "types": {
      "CometChatMessageInformationRootProps": "Root provider props",
      "CometChatMessageInformationHeaderProps": "Header sub-component props",
      "CometChatMessageInformationMessagePreviewProps": "Message preview sub-component props",
      "CometChatMessageInformationReceiptListProps": "Receipt list sub-component props",
      "CometChatUserReceiptInfo": "Combined user receipt info (user + readAt + deliveredAt)",
      "CometChatMessageInformationContextValue": "Context value for sub-components"
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatMessageInformation` is typically opened from the message context menu ("Message Information" option). It renders as a side panel showing the message preview and delivery/read receipt details.

<Info>
  **Live Preview** — interact with the message information panel.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-messages-message-information--default)
</Info>

<iframe title="CometChat Message Information — Default" />

For 1-on-1 chats, it shows simple Read and Delivered timestamps. For group chats, it shows a scrollable list of users with their individual read and delivered timestamps.

It offers **two usage modes**:

* **Flat API** — pass convenience props directly to `<CometChatMessageInformation />` for quick customization
* **Compound API** — use `<CometChatMessageInformation.Root>` with sub-components for full layout control

### Flat API (Simple)

```tsx theme={null}
import { CometChatMessageInformation } from "@cometchat/chat-uikit-react";

function MessageInfoPanel({ message, onClose }) {
  return (
    <CometChatMessageInformation
      message={message}
      onClose={onClose}
      headerView={<CustomHeader />}
    />
  );
}
```

### Flat API Convenience Props

When using `<CometChatMessageInformation />` directly (without `.Root`), these additional props are available:

| Prop              | Type        | Description                             |
| ----------------- | ----------- | --------------------------------------- |
| `headerView`      | `ReactNode` | Custom header (replaces default).       |
| `receiptListView` | `ReactNode` | Custom receipt list (replaces default). |
| `loadingView`     | `ReactNode` | Custom loading content.                 |
| `errorView`       | `ReactNode` | Custom error content.                   |
| `emptyView`       | `ReactNode` | Custom empty content.                   |

### Compound API (Advanced)

```tsx theme={null}
import { CometChatMessageInformation } from "@cometchat/chat-uikit-react";

function MessageInfoPanel({ message, onClose }) {
  return (
    <CometChatMessageInformation.Root
      message={message}
      onClose={onClose}
      onError={(err) => console.error(err)}
    >
      <CometChatMessageInformation.Header />
      <CometChatMessageInformation.MessagePreview />
      <CometChatMessageInformation.ReceiptList />
    </CometChatMessageInformation.Root>
  );
}
```

## Minimal Render

```tsx theme={null}
import { CometChatMessageInformation } from "@cometchat/chat-uikit-react";

function Demo({ message }) {
  return <CometChatMessageInformation.Root message={message} />;
}
```

Root CSS class: `.cometchat-message-information`

## Sub-Components

`CometChatMessageInformation` is a compound component with these sub-components:

| Sub-Component    | Purpose                                                                                                                                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Root`           | Context provider. Accepts `message`, `onClose`, `onError`, `messageInfoDateTimeFormat`, `messageSentAtDateTimeFormat`, `textFormatters`, `showScrollbar`, `className`. Renders default layout when no children provided. |
| `Header`         | Title ("Message Information") and close button.                                                                                                                                                                          |
| `MessagePreview` | Message bubble preview area.                                                                                                                                                                                             |
| `ReceiptList`    | Receipt display. Group: user list with avatars and timestamps. 1-on-1: Read/Delivered sections.                                                                                                                          |
| `LoadingState`   | Spinner loading indicator.                                                                                                                                                                                               |
| `ErrorState`     | Error message with retry button.                                                                                                                                                                                         |
| `EmptyState`     | Empty state for group messages with no receipts.                                                                                                                                                                         |

## Custom Layout

Compose only the sub-components you need:

```tsx theme={null}
<CometChatMessageInformation.Root message={message} onClose={handleClose}>
  <CometChatMessageInformation.Header />
  <CometChatMessageInformation.ReceiptList />
</CometChatMessageInformation.Root>
```

## Props

### Root

| Prop                          | Type                                        | Default                     | Description                                                     |
| ----------------------------- | ------------------------------------------- | --------------------------- | --------------------------------------------------------------- |
| `message`                     | `CometChat.BaseMessage`                     | —                           | **Required.** The message to show information for.              |
| `onClose`                     | `() => void`                                | —                           | Called when the close button is clicked.                        |
| `onError`                     | `(error: unknown) => void`                  | —                           | Called when an SDK error occurs.                                |
| `messageInfoDateTimeFormat`   | `CometChatMessageInformationCalendarObject` | `{ today: 'hh:mm A', ... }` | Custom date format for receipt timestamps (read/delivered).     |
| `messageSentAtDateTimeFormat` | `CometChatMessageInformationCalendarObject` | —                           | Format for the sent-at timestamp on the message bubble preview. |
| `textFormatters`              | `CometChatTextFormatter[]`                  | `[]`                        | Text formatters for the message bubble preview.                 |
| `showScrollbar`               | `boolean`                                   | `false`                     | Whether to show the scrollbar in the content area.              |
| `className`                   | `string`                                    | —                           | Additional CSS class.                                           |

## Keyboard Accessibility

| Key                 | Behavior                                            |
| ------------------- | --------------------------------------------------- |
| `Escape`            | Closes the panel, returns focus to trigger element. |
| `Tab` / `Shift+Tab` | Cycles focus within the panel (focus trap).         |
| `Enter` / `Space`   | Activates close button or retry button.             |

## CSS Variables

| Variable                           | Default   | Description                   |
| ---------------------------------- | --------- | ----------------------------- |
| `--cometchat-background-color-01`  | `#fff`    | Panel background              |
| `--cometchat-background-color-02`  | `#fafafa` | Message preview background    |
| `--cometchat-border-color-light`   | `#f5f5f5` | Border color                  |
| `--cometchat-text-color-primary`   | `#141414` | Title and name text           |
| `--cometchat-text-color-secondary` | `#666666` | Receipt labels and timestamps |
| `--cometchat-primary-color`        | `#6852D6` | Focus ring and retry button   |
| `--cometchat-icon-color-primary`   | `#141414` | Close icon color              |


# Message List
Source: https://www.cometchat.com/docs/ui-kit/react/components/message-list

Scrollable message feed with plugin-based bubble rendering, reactions, receipts, threads, and real-time updates.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatMessageList",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatMessageList } from \"@cometchat/chat-uikit-react\";",
    "description": "Scrollable message feed with plugin-based bubble rendering, reactions, receipts, threads, and real-time updates.",
    "cssRootClass": ".cometchat-message-list",
    "primaryOutput": {
      "prop": "onThreadRepliesClick",
      "type": "(message: CometChat.BaseMessage) => void"
    },
    "props": {
      "entity": {
        "user": {
          "type": "CometChat.User",
          "default": "undefined",
          "note": "For 1-on-1 chat. Mutually exclusive with group."
        },
        "group": {
          "type": "CometChat.Group",
          "default": "undefined",
          "note": "For group chat. Mutually exclusive with user."
        },
        "parentMessageId": {
          "type": "number",
          "default": "undefined",
          "note": "Enables thread mode — fetches replies to this message."
        }
      },
      "data": {
        "messagesRequestBuilder": {
          "type": "CometChat.MessagesRequestBuilder",
          "default": "SDK default (limit 30)",
          "note": "Pass the builder instance, not the result of .build()"
        },
        "reactionsRequestBuilder": {
          "type": "CometChat.ReactionsRequestBuilder",
          "default": "undefined"
        },
        "messageTypes": {
          "type": "string[]",
          "default": "Plugin registry types"
        },
        "messageCategories": {
          "type": "string[]",
          "default": "Plugin registry categories"
        },
        "goToMessageId": {
          "type": "number",
          "default": "undefined",
          "note": "Jump to a specific message (e.g., from search or deep link)"
        },
        "startFromUnreadMessages": {
          "type": "boolean",
          "default": false
        },
        "loadLastAgentConversation": {
          "type": "boolean",
          "default": false
        }
      },
      "visibility": {
        "hideReceipts": { "type": "boolean", "default": false },
        "hideStickyDate": { "type": "boolean", "default": false },
        "hideDateSeparator": { "type": "boolean", "default": false },
        "hideAvatar": { "type": "boolean", "default": false },
        "hideGroupActionMessages": { "type": "boolean", "default": false },
        "hideModerationView": { "type": "boolean", "default": false },
        "showScrollbar": { "type": "boolean", "default": false },
        "showSmartReplies": { "type": "boolean", "default": false },
        "showConversationStarters": { "type": "boolean", "default": false },
        "showMarkAsUnreadOption": { "type": "boolean", "default": false },
        "disableTruncation": { "type": "boolean", "default": false },
        "isAgentChat": { "type": "boolean", "default": false }
      },
      "optionToggles": {
        "hideReplyOption": { "type": "boolean", "default": false },
        "hideReplyInThreadOption": { "type": "boolean", "default": false },
        "hideEditMessageOption": { "type": "boolean", "default": false },
        "hideDeleteMessageOption": { "type": "boolean", "default": false },
        "hideCopyMessageOption": { "type": "boolean", "default": false },
        "hideReactionOption": { "type": "boolean", "default": false },
        "hideMessageInfoOption": { "type": "boolean", "default": false },
        "hideFlagMessageOption": { "type": "boolean", "default": false },
        "hideMessagePrivatelyOption": { "type": "boolean", "default": false },
        "hideTranslateMessageOption": { "type": "boolean", "default": false },
        "hideFlagRemarkField": { "type": "boolean", "default": false },
        "quickOptionsCount": { "type": "number", "default": 3 }
      },
      "dateFormatting": {
        "separatorDateTimeFormat": { "type": "CometChatDateFormatConfig" },
        "stickyDateTimeFormat": { "type": "CometChatDateFormatConfig" },
        "messageSentAtDateTimeFormat": { "type": "CometChatDateFormatConfig" },
        "messageInfoDateTimeFormat": { "type": "CometChatDateFormatConfig" }
      },
      "alignment": {
        "messageAlignment": {
          "type": "CometChatMessageListAlignment",
          "values": ["0 (left)", "1 (standard)"],
          "default": "1 (standard)"
        }
      },
      "sound": {
        "disableSoundForMessages": { "type": "boolean", "default": false },
        "customSoundForMessages": { "type": "string", "default": "built-in" }
      },
      "ai": {
        "smartRepliesKeywords": {
          "type": "string[]",
          "default": "['what','when','why','who','where','how','?']"
        },
        "smartRepliesDelayDuration": {
          "type": "number",
          "default": 10000
        }
      },
      "callbacks": {
        "onThreadRepliesClick": "(message: CometChat.BaseMessage) => void",
        "onAvatarClick": "(user: CometChat.User) => void",
        "onEditMessage": "(message: CometChat.BaseMessage) => void",
        "onReplyMessage": "(message: CometChat.BaseMessage) => void",
        "onReactionClick": "(reaction: CometChat.ReactionCount, message: CometChat.BaseMessage) => void",
        "onReactionListItemClick": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void",
        "onActiveChatChanged": "(data: { user?, group?, message?, unreadMessageCount? }) => void",
        "onMessageRead": "(message: CometChat.BaseMessage) => void",
        "onMessageDeleted": "(message: CometChat.BaseMessage) => void",
        "onConversationMarkedAsRead": "(conversation: CometChat.Conversation) => void",
        "onConversationUpdated": "(conversation: CometChat.Conversation) => void",
        "onError": "((error: CometChat.CometChatException) => void) | null"
      },
      "viewSlots": {
        "bubbleView": "(message: CometChat.BaseMessage, loggedInUser: CometChat.User) => ReactNode",
        "headerView": "ReactNode",
        "footerView": "ReactNode",
        "loadingView": "ReactNode",
        "emptyView": "ReactNode",
        "errorView": "ReactNode"
      }
    },
    "events": [
      {
        "name": "ui:message/read",
        "payload": "{ message }",
        "description": "Message marked as read"
      },
      {
        "name": "ui:message/deleted",
        "payload": "{ message }",
        "description": "Message deleted by user"
      },
      {
        "name": "ui:active-chat/changed",
        "payload": "{ user?, group?, message?, unreadMessageCount? }",
        "description": "Active chat context changed on init"
      },
      {
        "name": "ui:conversation/read",
        "payload": "{ conversationId }",
        "description": "Conversation marked as read"
      },
      {
        "name": "ui:conversation/updated",
        "payload": "{ conversation }",
        "description": "Conversation updated (mark-as-unread)"
      }
    ],
    "sdkListeners": [
      "onTextMessageReceived",
      "onMediaMessageReceived",
      "onCustomMessageReceived",
      "onInteractiveMessageReceived",
      "onTypingStarted",
      "onTypingEnded",
      "onMessagesDelivered",
      "onMessagesRead",
      "onMessagesDeliveredToAll",
      "onMessagesReadByAll",
      "onMessageEdited",
      "onMessageDeleted",
      "onTransientMessageReceived"
    ],
    "types": {
      "CometChatMessageListAlignment": {
        "left": 0,
        "standard": 1
      },
      "CometChatDateFormatConfig": {
        "today": "string | undefined",
        "yesterday": "string | undefined",
        "lastWeek": "string | undefined",
        "otherDays": "string | undefined",
        "relativeTime": {
          "minute": "string | undefined",
          "minutes": "string | undefined",
          "hour": "string | undefined",
          "hours": "string | undefined"
        }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatMessageList` is a scrollable message feed component. It renders messages for a given user or group conversation and emits thread navigation via `onThreadRepliesClick`. Wire it between `CometChatMessageHeader` and `CometChatMessageComposer` to build a standard chat panel.

<Info>
  **Live Preview** — interact with the default message list.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-messages-cometchat-message-list--default)
</Info>

<iframe title="CometChat Message List — Default" />

The component handles:

* Paginated message fetching with infinite scroll (older messages load on scroll-up)
* Plugin-based bubble rendering — each message type is rendered by a registered plugin
* Reactions with emoji picker and reaction list
* Read/delivery receipts (single and group)
* Thread reply indicators with reply count
* Real-time updates (new messages, edits, deletes, typing indicators)
* Smart replies — AI-generated quick reply suggestions based on incoming messages
* Conversation starters — AI-generated prompts when the conversation is empty
* Date separators and sticky floating date header
* Jump-to-message for search results and deep links
* Mark-as-unread support

> **Note:** `user` and `group` are mutually exclusive. Pass one or the other to specify the conversation context.

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react";

function ChatPanel({ user }: { user: CometChat.User }) {
  return (
    <CometChatMessageList
      user={user}
      onThreadRepliesClick={(message) => openThread(message)}
    />
  );
}
```

### Compound Composition

```tsx theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react";

function ChatPanel({ group }: { group: CometChat.Group }) {
  return (
    <CometChatMessageList.Root group={group}>
      <CometChatMessageList.LoadingState />
      <CometChatMessageList.ErrorState />
      <CometChatMessageList.EmptyState />
      <CometChatMessageList.Header />
      <CometChatMessageList.View />
      <CometChatMessageList.Footer />
      <CometChatMessageList.AIFooter />
    </CometChatMessageList.Root>
  );
}
```

### Full Layout Example

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

function ChatApp() {
  const [user, setUser] = useState<CometChat.User | undefined>();
  const [group, setGroup] = useState<CometChat.Group | undefined>();
  const [threadMessage, setThreadMessage] = useState<CometChat.BaseMessage | undefined>();

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setUser(entity as CometChat.User);
      setGroup(undefined);
    } else {
      setGroup(entity as CometChat.Group);
      setUser(undefined);
    }
    setThreadMessage(undefined);
  };

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>
      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        <CometChatMessageHeader user={user} group={group} />
        <CometChatMessageList
          user={user}
          group={group}
          onThreadRepliesClick={(message) => setThreadMessage(message)}
        />
        <CometChatMessageComposer user={user} group={group} />
      </div>
      {threadMessage && (
        <div style={{ width: 400, display: "flex", flexDirection: "column" }}>
          <CometChatMessageList
            user={user}
            group={group}
            parentMessageId={threadMessage.getId()}
          />
          <CometChatMessageComposer
            user={user}
            group={group}
            parentMessageId={threadMessage.getId()}
          />
        </div>
      )}
    </div>
  );
}
```

***

## Multi-Attachment Batch Grouping

When several attachments are sent together from the [composer's staging tray](/docs/ui-kit/react/components/message-composer#multi-attachment-staging-tray), they arrive as multiple media messages — one per media kind, in the fixed order **images → videos → audio → files** — that all share a single `batchId`. The message list detects consecutive messages carrying the same `batchId` **from the same sender** and renders them as one visually connected group instead of separate, independently-chromed bubbles.

<Info>
  **Live Preview** — interact with the mixed multi attachment message list.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble-batch-multi-attachment--incoming-batch-group)
</Info>

<iframe title="CometChat Message List — Mixed Multi attachment batch" />

### Batch position

Each message in a batch is assigned a `batchPosition` that the list applies to its message-bubble wrapper to adjust corner radius so the group reads as a single stack:

| Position | Meaning                                  | Corners                  |
| -------- | ---------------------------------------- | ------------------------ |
| `first`  | Top message of a multi-message batch     | Rounded top, flat bottom |
| `middle` | Interior message                         | Flat top and bottom      |
| `last`   | Bottom message of a multi-message batch  | Flat top, rounded bottom |
| `single` | Standalone message (not part of a batch) | All corners rounded      |

### Grouped chrome

Within a batch, the list renders shared chrome so the group looks like one logical message rather than several:

* The **avatar and sender name** render once, on the `first` message.
* **Delivery/read receipts** render once, on the `last` message.
* Interior spacing collapses so the bubbles sit tightly and read as a single stack.
* The **caption** (the composer's text), if any, is carried by the `last` message.

This is computed automatically — you don't configure anything. It applies whenever messages share a `batchId`, which the composer sets on every multi-attachment send.

***

## Filtering

Pass a `CometChat.MessagesRequestBuilder` to `messagesRequestBuilder` to control which messages load. Pass the builder instance — not the result of `.build()`. Refer to [MessagesRequestBuilder](/docs/sdk/javascript/message-filtering) for the full builder API.

```tsx theme={null}
<CometChatMessageList
  user={user}
  messagesRequestBuilder={
    new CometChat.MessagesRequestBuilder()
      .setLimit(50)
      .setCategories(["message"])
      .setTypes(["text", "image", "video"])
  }
/>
```

### Filter Recipes

| Recipe             | Code                                                                                   |
| ------------------ | -------------------------------------------------------------------------------------- |
| Only text messages | `new CometChat.MessagesRequestBuilder().setTypes(["text"])`                            |
| Only media         | `new CometChat.MessagesRequestBuilder().setTypes(["image", "video", "audio", "file"])` |
| Larger page size   | `new CometChat.MessagesRequestBuilder().setLimit(50)`                                  |
| Hide actions       | `new CometChat.MessagesRequestBuilder().setCategories(["message"])`                    |
| With tags          | `new CometChat.MessagesRequestBuilder().setTags(["important"])`                        |

***

## Actions and Events

### Callback Props

| Prop                         | Signature                                                                     | Fires when                                             |
| ---------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------ |
| `onThreadRepliesClick`       | `(message: CometChat.BaseMessage) => void`                                    | User clicks the thread reply indicator                 |
| `onAvatarClick`              | `(user: CometChat.User) => void`                                              | User clicks an avatar on an incoming message           |
| `onEditMessage`              | `(message: CometChat.BaseMessage) => void`                                    | User selects "Edit" from context menu                  |
| `onReplyMessage`             | `(message: CometChat.BaseMessage) => void`                                    | User selects "Reply" from context menu                 |
| `onReactionClick`            | `(reaction: CometChat.ReactionCount, message: CometChat.BaseMessage) => void` | User clicks a reaction count pill                      |
| `onReactionListItemClick`    | `(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void`      | User clicks an individual reactor in the reaction list |
| `onActiveChatChanged`        | `(data: { user?, group?, message?, unreadMessageCount? }) => void`            | Active chat context set on initial load                |
| `onMessageRead`              | `(message: CometChat.BaseMessage) => void`                                    | A message is marked as read                            |
| `onMessageDeleted`           | `(message: CometChat.BaseMessage) => void`                                    | A message is deleted                                   |
| `onConversationMarkedAsRead` | `(conversation: CometChat.Conversation) => void`                              | Conversation marked as read                            |
| `onConversationUpdated`      | `(conversation: CometChat.Conversation) => void`                              | Conversation updated (e.g., mark-as-unread)            |
| `onError`                    | `((error: CometChat.CometChatException) => void) \| null`                     | SDK error occurs                                       |

### Events Emitted

UI events this component publishes:

| Event                     | Payload                                            | Fires when                                                |
| ------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
| `ui:message/read`         | `{ message }`                                      | Message marked as read (auto on scroll-to-bottom)         |
| `ui:message/deleted`      | `{ message }`                                      | Message deleted by user via context menu                  |
| `ui:active-chat/changed`  | `{ user?, group?, message?, unreadMessageCount? }` | Active chat context set on initial load                   |
| `ui:conversation/read`    | `{ conversationId }`                               | Conversation marked as read (on init or scroll-to-bottom) |
| `ui:conversation/updated` | `{ conversation }`                                 | Conversation updated (e.g., mark-as-unread)               |

<Note>
  The "Edit" and "Reply" context menu options publish `ui:compose/edit` and `ui:compose/reply` events respectively. These are emitted by the message options system (plugins), not by the MessageList component directly. The MessageComposer subscribes to these events to enter edit/reply mode.
</Note>

### Events Received

UI events this component subscribes to (published by other components):

| Event                           | Payload                                 | Behavior                                             |
| ------------------------------- | --------------------------------------- | ---------------------------------------------------- |
| `ui:message/sent`               | `{ message, status }`                   | Appends sent message (optimistic flow from composer) |
| `ui:compose/edit`               | `{ message, status }`                   | Updates edited message in the list                   |
| `ui:group/member-added`         | `{ group, members, messages }`          | Appends group action message                         |
| `ui:group/member-kicked`        | `{ group, user, message }`              | Appends group action message                         |
| `ui:group/member-banned`        | `{ group, user, message }`              | Appends group action message                         |
| `ui:group/member-unbanned`      | `{ group, user, message }`              | Appends group action message                         |
| `ui:group/member-scope-changed` | `{ group, user, newScope }`             | Appends group action message                         |
| `ui:group/left`                 | `{ group }`                             | Appends group action message                         |
| `ui:group/ownership-changed`    | `{ group, newOwner, previousOwnerUid }` | Appends group action message                         |
| `ui:call/outgoing`              | `{ call }`                              | Appends call message                                 |
| `ui:call/accepted`              | `{ call }`                              | Appends call message                                 |
| `ui:call/rejected`              | `{ call }`                              | Appends call message                                 |
| `ui:call/ended`                 | `{ call? }`                             | Appends call message                                 |

### SDK Listeners (Automatic)

These SDK listeners are attached internally. The component updates its state automatically — no manual subscription needed:

* Message listeners: `onTextMessageReceived`, `onMediaMessageReceived`, `onCustomMessageReceived`, `onInteractiveMessageReceived`
* Typing: `onTypingStarted`, `onTypingEnded`
* Receipts: `onMessagesDelivered`, `onMessagesRead`, `onMessagesDeliveredToAll`, `onMessagesReadByAll`
* Edits & deletes: `onMessageEdited`, `onMessageDeleted`
* Transient: `onTransientMessageReceived`

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatMessageList
  user={user}
  headerView={<TypingIndicator />}
  footerView={<SmartRepliesBar />}
  emptyView={<EmptyConversation />}
  loadingView={<MessageSkeleton />}
  errorView={<ErrorBanner />}
  bubbleView={(message, loggedInUser) => <CustomBubble message={message} />}
/>
```

| Slot          | Signature                              | Replaces                                 |
| ------------- | -------------------------------------- | ---------------------------------------- |
| `bubbleView`  | `(message, loggedInUser) => ReactNode` | Entire bubble rendering for each message |
| `headerView`  | `ReactNode`                            | Header area above the scroll container   |
| `footerView`  | `ReactNode`                            | Footer area below the scroll container   |
| `loadingView` | `ReactNode`                            | Loading shimmer                          |
| `emptyView`   | `ReactNode`                            | Empty state                              |
| `errorView`   | `ReactNode`                            | Error state                              |

#### headerView

Custom view above the message list.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { useState, useEffect } from "react";
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatMessageList, CometChatButton } from "@cometchat/chat-uikit-react";

    function MessageListWithHeader() {
      const [chatUser, setChatUser] = useState<CometChat.User>();

      useEffect(() => {
        CometChat.getUser("uid").then((user) => setChatUser(user));
      }, []);

      return chatUser ? (
        <CometChatMessageList
          user={chatUser}
          headerView={
            <div className="header-view">
              <CometChatButton.Root>
                <CometChatButton.Text>Notes</CometChatButton.Text>
              </CometChatButton.Root>
              <CometChatButton.Root>
                <CometChatButton.Text>Pinned Message</CometChatButton.Text>
              </CometChatButton.Root>
              <CometChatButton.Root>
                <CometChatButton.Text>Saved Links</CometChatButton.Text>
              </CometChatButton.Root>
            </div>
          }
        />
      ) : null;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .header-view {
      display: flex;
      width: 100%;
      padding: 3px 16px;
      align-items: flex-start;
      gap: 5px;
      background: #edeafa;
    }

    .header-view .cometchat-button {
      width: auto;
      height: 32px;
      border-radius: 1000px;
      border: 1px solid #e8e8e8;
      background: #fafafa;
    }

    .header-view .cometchat-button__text {
      color: #6852d6;
      font: 400 12px/14.4px Roboto;
    }
    ```
  </Tab>
</Tabs>

#### footerView

Custom view below the message list.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatMessageList, CometChatButton } from "@cometchat/chat-uikit-react";

    function MessageListWithFooter({ chatUser }: { chatUser: CometChat.User }) {
      return (
        <CometChatMessageList
          user={chatUser}
          footerView={
            <div className="footer-view">
              <CometChatButton.Root>
                <CometChatButton.Text>Ice Breakers</CometChatButton.Text>
              </CometChatButton.Root>
              <CometChatButton.Root>
                <CometChatButton.Text>+1-212-456-7890</CometChatButton.Text>
              </CometChatButton.Root>
            </div>
          }
        />
      );
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .footer-view {
      display: flex;
      width: 100%;
      padding: 3px 16px;
      align-items: flex-start;
      gap: 5px;
      background: #edeafa;
    }
    ```
  </Tab>
</Tabs>

### Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

```tsx theme={null}
<CometChatMessageList.Root user={user}>
  {/* No Header — it won't render */}
  <CometChatMessageList.LoadingState />
  <CometChatMessageList.ErrorState />
  <CometChatMessageList.EmptyState />
  <CometChatMessageList.View />
  <CometChatMessageList.AIFooter />
</CometChatMessageList.Root>
```

Available sub-components:

| Sub-component    | Description                            | Props                       | Flat API equivalent |
| ---------------- | -------------------------------------- | --------------------------- | ------------------- |
| `Root`           | Context provider, data hook, container | All Root props + `children` | —                   |
| `View`           | Scrollable message feed                | `className`                 | —                   |
| `Header`         | Content above the feed                 | `children`, `className`     | `headerView`        |
| `Footer`         | Content below the feed                 | `children`, `className`     | `footerView`        |
| `ScrollToBottom` | Floating scroll button                 | `className`                 | —                   |
| `EmptyState`     | Empty state                            | `children`, `className`     | `emptyView`         |
| `ErrorState`     | Error state                            | `children`, `className`     | `errorView`         |
| `LoadingState`   | Loading shimmer                        | `children`, `className`     | `loadingView`       |
| `DateSeparator`  | Day separator                          | `className`                 | —                   |
| `AIFooter`       | Smart replies / starters               | `className`                 | —                   |

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-message-list {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-message-list__date-separator {
  --cometchat-text-color-secondary: #aaa;
}
```

***

## Props

All props are optional (though you must pass either `user` or `group` to render messages).

<Note>
  View slot props (`bubbleView`, `headerView`, `footerView`, `loadingView`, `emptyView`, `errorView`) are convenience props available only on the flat API. In compound composition mode, use the corresponding sub-components directly.
</Note>

***

### Entity

***

### user

The user entity for a 1-on-1 conversation. Mutually exclusive with `group`.

|         |                  |
| ------- | ---------------- |
| Type    | `CometChat.User` |
| Default | `undefined`      |

***

### group

The group entity for a group conversation. Mutually exclusive with `user`.

|         |                   |
| ------- | ----------------- |
| Type    | `CometChat.Group` |
| Default | `undefined`       |

***

### parentMessageId

Enables thread mode. When set, the component fetches and displays replies to the specified parent message instead of the main conversation feed.

|         |             |
| ------- | ----------- |
| Type    | `number`    |
| Default | `undefined` |

***

### Data

***

### messagesRequestBuilder

Custom request builder for fetching messages. Controls pagination, filtering, and sorting.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `CometChat.MessagesRequestBuilder` |
| Default | SDK default (limit 30)             |

***

### reactionsRequestBuilder

Custom request builder for fetching reactions on messages.

|         |                                     |
| ------- | ----------------------------------- |
| Type    | `CometChat.ReactionsRequestBuilder` |
| Default | `undefined`                         |

***

### messageTypes

Restrict which message types are fetched and displayed.

|         |                       |
| ------- | --------------------- |
| Type    | `string[]`            |
| Default | Plugin registry types |

***

### messageCategories

Restrict which message categories are fetched and displayed.

|         |                            |
| ------- | -------------------------- |
| Type    | `string[]`                 |
| Default | Plugin registry categories |

***

### goToMessageId

Jump to a specific message by ID (e.g., from search results or a deep link). The list scrolls to and highlights the target message.

|         |             |
| ------- | ----------- |
| Type    | `number`    |
| Default | `undefined` |

***

### startFromUnreadMessages

When `true`, the list scrolls to the first unread message on open instead of the bottom.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### loadLastAgentConversation

When `true`, loads the last agent conversation on initial render. Used for AI agent chat flows.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### Visibility

***

### hideReceipts

Hide message delivery/read receipts (double ticks) on message bubbles.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideStickyDate

Hide the sticky date header that floats at the top of the scroll area.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideDateSeparator

Hide date separators between calendar days in the message feed.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideAvatar

Hide the avatar on incoming messages in group conversations.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideGroupActionMessages

Filter out group action messages (member joined, left, kicked, etc.).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideModerationView

Hide the moderation footer beneath disapproved messages.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showScrollbar

Show the native scrollbar on the message list. When `false`, the scrollbar is hidden but scrolling still works.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showSmartReplies

Show AI-generated smart reply suggestions in the footer when the last received message matches keyword criteria.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showConversationStarters

Show AI-generated conversation starters in the footer when the message list is empty.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showMarkAsUnreadOption

Show the "Mark as Unread" option in the message context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### disableTruncation

Disable text truncation (read more / show less) in text bubbles. When `true`, full message text is always shown.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### isAgentChat

Whether this is an AI agent chat. Suppresses moderation UI and enables agent-specific behaviors.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### Option Toggles

***

### hideReplyOption

Hide the "Reply" option from the message context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideReplyInThreadOption

Hide the "Reply in Thread" option from the message context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideEditMessageOption

Hide the "Edit" option from the message context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideDeleteMessageOption

Hide the "Delete" option from the message context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideCopyMessageOption

Hide the "Copy" option from the message context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideReactionOption

Hide the "React" option from the message context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideMessageInfoOption

Hide the "Message Info" option from the message context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideFlagMessageOption

Hide the "Flag/Report" option from the message context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideMessagePrivatelyOption

Hide the "Message Privately" option from the message context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideTranslateMessageOption

Hide the "Translate" option from the message context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideFlagRemarkField

Hide the remark textarea in the flag/report message dialog.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### quickOptionsCount

Number of quick-action options shown inline next to the bubble before overflowing into the "More" menu.

|         |          |
| ------- | -------- |
| Type    | `number` |
| Default | `3`      |

***

### Date Formatting

***

### separatorDateTimeFormat

Custom date format for in-list day separators ("Today", "Yesterday", etc.).

|         |                             |
| ------- | --------------------------- |
| Type    | `CometChatDateFormatConfig` |
| Default | Built-in format             |

***

### stickyDateTimeFormat

Custom date format for the sticky date header floating above messages.

|         |                             |
| ------- | --------------------------- |
| Type    | `CometChatDateFormatConfig` |
| Default | Built-in format             |

***

### messageSentAtDateTimeFormat

Custom date format for the timestamp shown beside the message bubble.

|         |                             |
| ------- | --------------------------- |
| Type    | `CometChatDateFormatConfig` |
| Default | Built-in format             |

***

### messageInfoDateTimeFormat

Custom date format for timestamps in the MessageInformation sheet.

|         |                             |
| ------- | --------------------------- |
| Type    | `CometChatDateFormatConfig` |
| Default | Built-in format             |

***

### Alignment

***

### messageAlignment

Controls message bubble alignment. `0` aligns all messages to the left. `1` uses standard alignment (sent on right, received on left).

|         |                                 |
| ------- | ------------------------------- |
| Type    | `CometChatMessageListAlignment` |
| Default | `1` (standard)                  |

***

### Sound

***

### disableSoundForMessages

Disable the notification sound when new messages arrive.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### customSoundForMessages

Custom sound URL to play when new messages arrive (replaces the built-in sound).

|         |                             |
| ------- | --------------------------- |
| Type    | `string`                    |
| Default | Built-in notification sound |

***

### AI Features

***

### smartRepliesKeywords

Keywords that trigger smart replies when found in a received text message. If set to an empty array, smart replies show for every received text message.

|         |                                                       |
| ------- | ----------------------------------------------------- |
| Type    | `string[]`                                            |
| Default | `['what', 'when', 'why', 'who', 'where', 'how', '?']` |

***

### smartRepliesDelayDuration

Delay in milliseconds before showing smart replies after a qualifying message is received. Acts as a debounce — if another message arrives within this window, the timer resets.

|         |          |
| ------- | -------- |
| Type    | `number` |
| Default | `10000`  |

***

### Callbacks

***

### onThreadRepliesClick

Callback when the thread reply indicator is clicked on a message bubble.

|         |                                            |
| ------- | ------------------------------------------ |
| Type    | `(message: CometChat.BaseMessage) => void` |
| Default | `undefined`                                |

***

### onAvatarClick

Callback when an incoming message avatar is clicked.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `(user: CometChat.User) => void` |
| Default | `undefined`                      |

***

### onEditMessage

Callback when the "Edit" context menu option is clicked. Typically sets the message in edit mode in the composer.

|         |                                            |
| ------- | ------------------------------------------ |
| Type    | `(message: CometChat.BaseMessage) => void` |
| Default | `undefined`                                |

***

### onReplyMessage

Callback when the "Reply" context menu option is clicked. Typically sets the message as reply-to in the composer.

|         |                                            |
| ------- | ------------------------------------------ |
| Type    | `(message: CometChat.BaseMessage) => void` |
| Default | `undefined`                                |

***

### onReactionClick

Callback when a reaction count pill is clicked on a message.

|         |                                                                               |
| ------- | ----------------------------------------------------------------------------- |
| Type    | `(reaction: CometChat.ReactionCount, message: CometChat.BaseMessage) => void` |
| Default | `undefined`                                                                   |

***

### onReactionListItemClick

Callback when an individual reactor in the reaction list is clicked.

|         |                                                                          |
| ------- | ------------------------------------------------------------------------ |
| Type    | `(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void` |
| Default | `undefined`                                                              |

***

### onActiveChatChanged

Callback invoked on first load with the active chat context (user/group, last message, unread count).

|         |                                                                    |
| ------- | ------------------------------------------------------------------ |
| Type    | `(data: { user?, group?, message?, unreadMessageCount? }) => void` |
| Default | `undefined`                                                        |

***

### onMessageRead

Callback when a message is marked as read.

|         |                                            |
| ------- | ------------------------------------------ |
| Type    | `(message: CometChat.BaseMessage) => void` |
| Default | `undefined`                                |

***

### onMessageDeleted

Callback when a message is deleted.

|         |                                            |
| ------- | ------------------------------------------ |
| Type    | `(message: CometChat.BaseMessage) => void` |
| Default | `undefined`                                |

***

### onConversationMarkedAsRead

Callback when the conversation is marked as read.

|         |                                                  |
| ------- | ------------------------------------------------ |
| Type    | `(conversation: CometChat.Conversation) => void` |
| Default | `undefined`                                      |

***

### onConversationUpdated

Callback when mark-as-unread succeeds (conversation updated).

|         |                                                  |
| ------- | ------------------------------------------------ |
| Type    | `(conversation: CometChat.Conversation) => void` |
| Default | `undefined`                                      |

***

### onError

Callback when an SDK error occurs during fetch or real-time operations.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `null`                                                    |

***

### View Slots

***

### bubbleView

Replace the entire bubble rendering for each message. When provided, the default plugin-based BubbleRenderer is skipped entirely.

|         |                                                                               |
| ------- | ----------------------------------------------------------------------------- |
| Type    | `(message: CometChat.BaseMessage, loggedInUser: CometChat.User) => ReactNode` |
| Default | `undefined`                                                                   |

```tsx theme={null}
<CometChatMessageList
  user={user}
  bubbleView={(message, loggedInUser) => (
    <div className="my-bubble">
      {message.getText?.() || "Custom bubble"}
    </div>
  )}
/>
```

***

### headerView

Custom content rendered above the scroll container (e.g., typing indicator, pinned message).

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

### footerView

Custom content rendered below the scroll container (e.g., smart replies bar).

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

### loadingView

Custom loading state shown while messages are being fetched.

|         |                  |
| ------- | ---------------- |
| Type    | `ReactNode`      |
| Default | Built-in shimmer |

***

### emptyView

Custom empty state shown when there are no messages in the conversation.

|         |                      |
| ------- | -------------------- |
| Type    | `ReactNode`          |
| Default | Built-in empty state |

***

### errorView

Custom error state shown when message fetching fails.

|         |                      |
| ------- | -------------------- |
| Type    | `ReactNode`          |
| Default | Built-in error state |

***

## CSS Selectors

| Target                  | Selector                                       |
| ----------------------- | ---------------------------------------------- |
| Root container          | `.cometchat-message-list`                      |
| Header area             | `.cometchat-message-list__header`              |
| Footer area             | `.cometchat-message-list__footer`              |
| Scroll container        | `.cometchat-message-list__scroll-container`    |
| Date separator          | `.cometchat-message-list__date-separator`      |
| Floating sticky date    | `.cometchat-message-list__floating-date`       |
| New message divider     | `.cometchat-message-list__new-message-divider` |
| Scroll-to-bottom button | `.cometchat-message-list__scroll-to-bottom`    |
| Empty state             | `.cometchat-message-list__empty-state`         |
| Error state             | `.cometchat-message-list__error-state`         |
| Loading state           | `.cometchat-message-list__loading-state`       |

***

## Next Steps

<CardGroup>
  <Card title="Message Composer" icon="pen" href="/ui-kit/react/components/message-composer">
    Add a composer below the message list for sending messages
  </Card>

  <Card title="Thread Header" icon="comments" href="/ui-kit/react/components/thread-header">
    Display thread context above a threaded message list
  </Card>

  <Card title="Plugins Overview" icon="puzzle-piece" href="/ui-kit/react/plugins/overview">
    Learn how plugins register custom bubble renderers
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Notification Feed
Source: https://www.cometchat.com/docs/ui-kit/react/components/notification-feed

Full-screen notification feed component with category filtering, card rendering, real-time updates, and engagement reporting.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatNotificationFeed",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatNotificationFeed } from \"@cometchat/chat-uikit-react\";",
    "description": "Full-screen notification feed with category filtering, timestamp grouping, card rendering via @cometchat/cards-react, real-time updates, and automatic engagement reporting.",
    "cssRootClass": ".cometchat-notification-feed",
    "props": {
      "data": {
        "title": { "type": "string", "default": "\"Notifications\"" },
        "notificationFeedRequestBuilder": { "type": "NotificationFeedRequestBuilder", "default": "SDK default (20 per page)" },
        "notificationCategoriesRequestBuilder": { "type": "NotificationCategoriesRequestBuilder", "default": "SDK default (50 per page)" }
      },
      "callbacks": {
        "onItemClick": "(feedItem: NotificationFeedItem) => void",
        "onActionClick": "(feedItem: NotificationFeedItem, action: CardAction) => void",
        "onError": "(error: CometChat.CometChatException) => void",
        "onBackPress": "() => void"
      },
      "visibility": {
        "showHeader": { "type": "boolean", "default": true },
        "showBackButton": { "type": "boolean", "default": false },
        "showFilterChips": { "type": "boolean", "default": true }
      },
      "viewSlots": {
        "headerView": "ReactNode",
        "emptyView": "ReactNode",
        "errorView": "ReactNode",
        "loadingView": "ReactNode",
        "itemView": "(item: NotificationFeedItem) => ReactNode"
      },
      "cards": {
        "cardThemeMode": { "type": "\"auto\" | \"light\" | \"dark\"", "default": "\"auto\"" },
        "cardThemeOverride": { "type": "Record<string, unknown>", "default": "undefined" }
      }
    },
    "automaticBehaviors": [
      "Real-time updates via WebSocket listener",
      "Delivery reporting on fetch",
      "Read reporting on viewport visibility (IntersectionObserver)",
      "Unread count polling every 30 seconds",
      "Infinite scroll pagination",
      "Timestamp grouping (Today, Yesterday, day name, date)",
      "Category filter chips with unread badges",
      "Mark all read button"
    ],
    "additionalExports": {
      "useNotificationUnreadCount": "Hook for tracking unread count with shared polling"
    }
  }
  ```
</Accordion>

`CometChatNotificationFeed` displays a scrollable notification feed where each item is rendered as a card using `@cometchat/cards-react`. It handles fetching, pagination, category filtering, timestamp grouping, real-time updates, and read/delivered/engagement reporting automatically.

<Frame>
  <img />
</Frame>

<Info>
  **Live Preview** — interact with the notification feed component.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-notification-feed-cometchat-notification-feed--default)
</Info>

<iframe title="CometChat Notification Feed — Default" />

***

## Where It Fits

`CometChatNotificationFeed` is a full-screen component. Drop it into a page or route. It manages its own data fetching, state, and real-time listeners — you just handle navigation callbacks.

```tsx theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";

function NotificationsPage() {
  return (
    <CometChatNotificationFeed
      showBackButton={true}
      onBackPress={() => window.history.back()}
      onItemClick={(item) => {
        // Handle item click (e.g., open detail or deep link)
      }}
    />
  );
}
```

***

## Minimal Render

```tsx theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";

function NotificationsDemo() {
  return (
    <div style={{ width: "100%", height: "100vh" }}>
      <CometChatNotificationFeed />
    </div>
  );
}

export default NotificationsDemo;
```

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()` and a user logged in.

Root CSS class: `.cometchat-notification-feed`

***

## Filtering Feed Items

Control what loads using custom request builders:

```tsx theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function UnreadNotifications() {
  return (
    <CometChatNotificationFeed
      notificationFeedRequestBuilder={
        new CometChat.NotificationFeedRequestBuilder()
          .setLimit(30)
          .setReadState("unread")
          .setCategory("promotions")
          .build()
      }
    />
  );
}
```

### Filter Options

| Builder Method          | Description                          |
| ----------------------- | ------------------------------------ |
| `.setLimit(number)`     | Items per page (default 20, max 100) |
| `.setReadState(state)`  | `"read"`, `"unread"`, or `"all"`     |
| `.setCategory(string)`  | Filter by category label             |
| `.setChannelId(string)` | Filter by channel                    |
| `.setTags(string[])`    | Filter by tags                       |
| `.setDateFrom(string)`  | ISO 8601 date lower bound            |
| `.setDateTo(string)`    | ISO 8601 date upper bound            |

***

## Actions and Events

### Callback Props

#### onItemClick

Fires when a feed item card is clicked.

```tsx theme={null}
<CometChatNotificationFeed
  onItemClick={(item) => {
    console.log("Item clicked:", item.getId());
  }}
/>
```

#### onActionClick

Fires when an interactive element (button, link) inside a card is clicked. The `action` object contains the action type, parameters, and the element ID that triggered it.

```tsx theme={null}
<CometChatNotificationFeed
  onActionClick={(item, action) => {
    const { type, params, elementId } = action;
    switch (type) {
      case "openUrl":
        window.open(params.url as string, "_blank");
        break;
      case "chatWithUser":
        // Navigate to chat with params.uid
        break;
      case "chatWithGroup":
        // Navigate to group chat with params.guid
        break;
    }
  }}
/>
```

#### onError

Fires when an internal error occurs (network failure, SDK exception).

```tsx theme={null}
<CometChatNotificationFeed
  onError={(error) => {
    console.error("Feed error:", error.message);
  }}
/>
```

#### onBackPress

Fires when the back button in the header is clicked.

```tsx theme={null}
<CometChatNotificationFeed
  showBackButton={true}
  onBackPress={() => window.history.back()}
/>
```

### Automatic Behaviors

The component handles these automatically — no manual setup needed:

| Behavior             | Description                                                                |
| -------------------- | -------------------------------------------------------------------------- |
| Real-time updates    | New items appear at the top via WebSocket `NotificationFeedListener`       |
| Delivery reporting   | Items are reported as delivered when fetched                               |
| Read reporting       | Items are reported as read when visible in viewport (IntersectionObserver) |
| Unread count polling | Polls unread count every 30 seconds to update badges                       |
| Infinite scroll      | Fetches next page when scrolling near the bottom                           |
| Timestamp grouping   | Groups items as "Today", "Yesterday", day name, or date                    |
| Category filtering   | Filter chips row with per-category unread badges                           |
| Mark all read        | Header button to mark all notifications as read                            |

***

## Customization

### View Props

```tsx theme={null}
<CometChatNotificationFeed
  headerView={<MyCustomHeader />}
  emptyView={<EmptyState />}
  loadingView={<Skeleton />}
  errorView={<ErrorBanner />}
  itemView={(item) => <MyCustomCard item={item} />}
/>
```

| Slot          | Signature                                   | Replaces                       |
| ------------- | ------------------------------------------- | ------------------------------ |
| `headerView`  | `ReactNode`                                 | Entire header bar              |
| `loadingView` | `ReactNode`                                 | Loading state                  |
| `emptyView`   | `ReactNode`                                 | Empty state                    |
| `errorView`   | `ReactNode`                                 | Error state                    |
| `itemView`    | `(item: NotificationFeedItem) => ReactNode` | Individual feed item rendering |

### Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

```tsx theme={null}
<CometChatNotificationFeed.Root onItemClick={handleClick}>
  <CometChatNotificationFeed.Header />
  <CometChatNotificationFeed.FilterChips />
  <CometChatNotificationFeed.List />
</CometChatNotificationFeed.Root>
```

Available sub-components:

| Sub-component  | Description                           | Props                                                | Flat API equivalent |
| -------------- | ------------------------------------- | ---------------------------------------------------- | ------------------- |
| `Root`         | Context provider and container        | All Root props + `children`                          | —                   |
| `Header`       | Header bar with title + mark-all-read | `title`, `showBackButton`, `onBackPress`, `children` | `headerView`        |
| `FilterChips`  | Category filter chips                 | `children`                                           | —                   |
| `List`         | Scrollable feed list                  | `itemView`                                           | `itemView`          |
| `Item`         | Individual feed item                  | `item`, `cardThemeMode`, `cardThemeOverride`         | —                   |
| `EmptyState`   | Empty state                           | `children`                                           | `emptyView`         |
| `ErrorState`   | Error state                           | `children`                                           | `errorView`         |
| `LoadingState` | Loading state                         | `children`                                           | `loadingView`       |

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-notification-feed {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}
```

### CSS Classes

| Class                                            | Description                         |
| ------------------------------------------------ | ----------------------------------- |
| `.cometchat-notification-feed`                   | Root container                      |
| `.cometchat-notification-feed__header`           | Header bar                          |
| `.cometchat-notification-feed__header-title`     | Header title text                   |
| `.cometchat-notification-feed__header-back`      | Back button                         |
| `.cometchat-notification-feed__mark-all-read`    | Mark all read button                |
| `.cometchat-notification-feed__chips`            | Filter chips container              |
| `.cometchat-notification-feed__chip`             | Individual filter chip              |
| `.cometchat-notification-feed__chip--active`     | Active filter chip                  |
| `.cometchat-notification-feed__chip--inactive`   | Inactive filter chip                |
| `.cometchat-notification-feed__chip-badge`       | Chip unread badge                   |
| `.cometchat-notification-feed__content`          | Scrollable content area             |
| `.cometchat-notification-feed__item`             | Feed item container                 |
| `.cometchat-notification-feed__item--unread`     | Unread feed item                    |
| `.cometchat-notification-feed__unread-indicator` | Unread dot indicator                |
| `.cometchat-notification-feed__item-meta`        | Item metadata row (category + time) |
| `.cometchat-notification-feed__card-container`   | Card wrapper                        |
| `.cometchat-notification-feed__loading`          | Loading state                       |
| `.cometchat-notification-feed__empty`            | Empty state                         |
| `.cometchat-notification-feed__error`            | Error state                         |

***

## Props

All props are optional.

***

### title

Header title text.

|         |                   |
| ------- | ----------------- |
| Type    | `string`          |
| Default | `"Notifications"` |

***

### showHeader

Shows/hides the entire header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### showBackButton

Shows/hides the back button in the header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showFilterChips

Shows/hides the category filter chips row.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### notificationFeedRequestBuilder

Custom request builder for fetching feed items.

|         |                                            |
| ------- | ------------------------------------------ |
| Type    | `CometChat.NotificationFeedRequestBuilder` |
| Default | SDK default (20 per page)                  |

***

### notificationCategoriesRequestBuilder

Custom request builder for fetching categories.

|         |                                                  |
| ------- | ------------------------------------------------ |
| Type    | `CometChat.NotificationCategoriesRequestBuilder` |
| Default | SDK default (50 per page)                        |

***

### onItemClick

Callback fired when a feed item card is clicked.

|         |                                            |
| ------- | ------------------------------------------ |
| Type    | `(feedItem: NotificationFeedItem) => void` |
| Default | `undefined`                                |

***

### onActionClick

Callback fired when an interactive element inside a card is clicked.

|         |                                                                |
| ------- | -------------------------------------------------------------- |
| Type    | `(feedItem: NotificationFeedItem, action: CardAction) => void` |
| Default | `undefined`                                                    |

The `CardAction` object contains:

* `type` — Action type (e.g., `"openUrl"`, `"chatWithUser"`)
* `params` — Action parameters (e.g., `{ url: "..." }`, `{ uid: "..." }`)
* `elementId` — ID of the element that triggered the action

***

### onError

Callback fired when the component encounters an error.

|         |                                                 |
| ------- | ----------------------------------------------- |
| Type    | `(error: CometChat.CometChatException) => void` |
| Default | `undefined`                                     |

***

### onBackPress

Callback fired when the back button is pressed.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### cardThemeMode

Theme mode for the card renderer (`@cometchat/cards-react`).

|         |                               |
| ------- | ----------------------------- |
| Type    | `"auto" \| "light" \| "dark"` |
| Default | `"auto"`                      |

***

### cardThemeOverride

Custom theme override passed to the card renderer.

|         |                           |
| ------- | ------------------------- |
| Type    | `Record<string, unknown>` |
| Default | `undefined`               |

***

### headerView

Custom component replacing the entire header.

|         |                                                     |
| ------- | --------------------------------------------------- |
| Type    | `ReactNode`                                         |
| Default | Built-in header with title and mark-all-read button |

***

### loadingView

Custom component displayed during the initial loading state.

|         |                        |
| ------- | ---------------------- |
| Type    | `ReactNode`            |
| Default | Built-in loading state |

***

### errorView

Custom component displayed when an error occurs.

|         |                                        |
| ------- | -------------------------------------- |
| Type    | `ReactNode`                            |
| Default | Built-in error state with retry button |

***

### emptyView

Custom component displayed when there are no notifications.

|         |                                        |
| ------- | -------------------------------------- |
| Type    | `ReactNode`                            |
| Default | Built-in empty state with illustration |

***

### itemView

Custom renderer for each feed item.

|         |                                             |
| ------- | ------------------------------------------- |
| Type    | `(item: NotificationFeedItem) => ReactNode` |
| Default | Built-in card renderer                      |

***

## Additional Exports

### useNotificationUnreadCount

A React hook for tracking unread notification count. Uses a shared singleton — multiple components share one polling interval and WebSocket listener.

```tsx theme={null}
import { useNotificationUnreadCount } from "@cometchat/chat-uikit-react";

function NotificationIcon() {
  const { count, refresh, isLoading } = useNotificationUnreadCount();

  return (
    <button onClick={refresh}>
      🔔 {count > 0 && <span className="badge">{count}</span>}
    </button>
  );
}
```

#### Options

| Option            | Type   | Default   | Description                      |
| ----------------- | ------ | --------- | -------------------------------- |
| `category`        | string | undefined | Filter count by category         |
| `pollingInterval` | number | 30000     | Polling interval in milliseconds |

#### Return Value

| Field       | Type                  | Description                              |
| ----------- | --------------------- | ---------------------------------------- |
| `count`     | number                | Current unread count                     |
| `refresh`   | `() => Promise<void>` | Manually refresh the count               |
| `isLoading` | boolean               | Whether the initial fetch is in progress |

***

## Common Patterns

### Show only unread items

```tsx theme={null}
<CometChatNotificationFeed
  notificationFeedRequestBuilder={
    new CometChat.NotificationFeedRequestBuilder()
      .setReadState("unread")
      .build()
  }
/>
```

### Hide filter chips and header

```tsx theme={null}
<CometChatNotificationFeed
  showHeader={false}
  showFilterChips={false}
/>
```

### Embed in a sidebar

```tsx theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";

function NotificationsSidebar() {
  return (
    <div style={{ width: 400, height: "100vh", borderLeft: "1px solid #E0E0E0" }}>
      <CometChatNotificationFeed
        title="Updates"
        showBackButton={false}
      />
    </div>
  );
}
```

### Add notification badge to navigation

```tsx theme={null}
import { useState } from "react";
import {
  CometChatNotificationFeed,
  useNotificationUnreadCount,
} from "@cometchat/chat-uikit-react";

function App() {
  const [showFeed, setShowFeed] = useState(false);
  const { count } = useNotificationUnreadCount();

  return (
    <>
      <nav>
        <button onClick={() => setShowFeed(!showFeed)}>
          🔔 {count > 0 && <span className="badge">{count}</span>}
        </button>
      </nav>
      {showFeed && (
        <CometChatNotificationFeed
          onBackPress={() => setShowFeed(false)}
          showBackButton={true}
        />
      )}
    </>
  );
}
```

***

## Next Steps

<CardGroup>
  <Card title="Campaigns Feature" icon="bullhorn" href="/ui-kit/react/campaigns">
    Overview of how campaigns work end-to-end
  </Card>

  <Card title="SDK Campaigns API" icon="code" href="/sdk/javascript/campaigns">
    Low-level SDK APIs for feed items, categories, and engagement
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and appearance
  </Card>

  <Card title="Components" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>
</CardGroup>


# Outgoing Call
Source: https://www.cometchat.com/docs/ui-kit/react/components/outgoing-call

Displays the outgoing call screen with receiver info and a cancel button while waiting for the call to be answered.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatOutgoingCall",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatOutgoingCall } from \"@cometchat/chat-uikit-react\";",
    "description": "Displays the outgoing call screen with receiver info and a cancel button while waiting for the call to be answered.",
    "cssRootClass": ".cometchat-outgoing-call",
    "primaryOutput": {
      "prop": "onCallCanceled",
      "type": "() => void"
    },
    "props": {
      "data": {
        "call": {
          "type": "CometChat.Call",
          "required": true,
          "note": "The CometChat call object representing the outgoing call"
        }
      },
      "callbacks": {
        "onCallCanceled": "() => void",
        "onError": "((error: CometChat.CometChatException) => void) | null"
      },
      "sound": {
        "disableSoundForCalls": { "type": "boolean", "default": false },
        "customSoundForCalls": { "type": "string", "default": "built-in" }
      },
      "viewSlots": {
        "titleView": "ReactNode",
        "subtitleView": "ReactNode",
        "avatarView": "ReactNode",
        "cancelButtonView": "ReactNode"
      }
    },
    "events": [],
    "eventsReceived": [],
    "sdkListeners": [],
    "types": {}
  }
  ```
</Accordion>

## Overview

`CometChatOutgoingCall` is a purely presentational component that displays the outgoing call screen while waiting for the receiver to answer. It shows the receiver's name, avatar, a "Calling..." subtitle, and an end-call button.

<Info>
  **Live Preview** — interact with the default outgoing call screen.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-calls-cometchat-outgoing-call--default)
</Info>

<iframe title="CometChat Outgoing Call — Default" />

The component handles:

* Displaying receiver name and avatar from the `call` object
* "Calling..." subtitle text
* End-call/cancel button
* Outgoing call sound playback (looping while mounted, pauses on unmount)

> **Required prop:** The `call` prop is required. The component needs a valid `CometChat.Call` object to render receiver information.

> **Typical usage:** `CometChatOutgoingCall` is typically rendered by `CometChatMessageHeader` or `CometChatIncomingCall` internally when a call is initiated, but it can be used standalone.

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react";

function OutgoingCallScreen({ call }: { call: CometChat.Call }) {
  return (
    <CometChatOutgoingCall
      call={call}
      onCallCanceled={() => {
        console.log("Call canceled by user");
        // Cancel the call via SDK
        CometChat.rejectCall(call.getSessionId(), CometChat.CALL_STATUS.CANCELLED);
      }}
    />
  );
}
```

### Standalone Usage Example

```tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react";

function CallManager() {
  const [outgoingCall, setOutgoingCall] = useState<CometChat.Call | null>(null);

  const initiateCall = async (receiverUID: string) => {
    const call = new CometChat.Call(
      receiverUID,
      CometChat.CALL_TYPE.VIDEO,
      CometChat.RECEIVER_TYPE.USER
    );
    const initiatedCall = await CometChat.initiateCall(call);
    setOutgoingCall(initiatedCall);
  };

  const cancelCall = () => {
    if (outgoingCall) {
      CometChat.rejectCall(
        outgoingCall.getSessionId(),
        CometChat.CALL_STATUS.CANCELLED
      );
      setOutgoingCall(null);
    }
  };

  return (
    <div>
      {outgoingCall && (
        <CometChatOutgoingCall
          call={outgoingCall}
          onCallCanceled={cancelCall}
        />
      )}
    </div>
  );
}
```

***

## Actions and Events

### Callback Props

| Prop             | Signature                                                 | Fires when                        |
| ---------------- | --------------------------------------------------------- | --------------------------------- |
| `onCallCanceled` | `() => void`                                              | User clicks the cancel/end button |
| `onError`        | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs                  |

### Events Emitted

This component does not emit any UI events.

### Events Received

This component does not subscribe to any UI events from other components.

### SDK Listeners (Automatic)

This component does not attach any SDK listeners. It is purely presentational — the parent component is responsible for managing call state transitions (e.g., listening for `onOutgoingCallAccepted` or `onOutgoingCallRejected`).

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatOutgoingCall
  call={call}
  titleView={<span className="custom-title">{call.getReceiver().getName()}</span>}
  subtitleView={<span>Ringing...</span>}
  avatarView={<img src={call.getReceiver().getAvatar()} alt="avatar" />}
  cancelButtonView={<button onClick={handleCancel}>End Call</button>}
/>
```

| Slot               | Type        | Replaces          |
| ------------------ | ----------- | ----------------- |
| `titleView`        | `ReactNode` | Receiver name     |
| `subtitleView`     | `ReactNode` | "Calling..." text |
| `avatarView`       | `ReactNode` | Receiver avatar   |
| `cancelButtonView` | `ReactNode` | End-call button   |

#### titleView

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react";

    function OutgoingCallCustomTitle({ call }: { call: CometChat.Call }) {
      return (
        <CometChatOutgoingCall
          call={call}
          titleView={
            <div className="outgoing-call__title">
              {call.getCallInitiator().getName()} {" <> "} {call.getCallReceiver().getName()}
            </div>
          }
        />
      );
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .outgoing-call__title {
      color: #141414;
      text-align: center;
      font: 500 24px Roboto;
    }
    ```
  </Tab>
</Tabs>

#### subtitleView

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react";

    function OutgoingCallCustomSubtitle({ call }: { call: CometChat.Call }) {
      return (
        <CometChatOutgoingCall
          call={call}
          subtitleView={
            <div className="outgoing-call__subtitle">
              <div className="outgoing-call__subtitle-icon" />
              {"Calling..."}
            </div>
          }
        />
      );
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .outgoing-call__subtitle {
      display: flex;
      justify-content: center;
      align-items: flex-start;
      gap: 8px;
      color: #727272;
      text-align: center;
      font: 400 16px Roboto;
    }

    .outgoing-call__subtitle-icon {
      background: #a1a1a1;
      height: 24px;
      width: 24px;
    }
    ```
  </Tab>
</Tabs>

#### avatarView

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatOutgoingCall, CometChatAvatar } from "@cometchat/chat-uikit-react";

    function OutgoingCallCustomAvatar({ call }: { call: CometChat.Call }) {
      return (
        <CometChatOutgoingCall
          call={call}
          avatarView={
            <div className="outgoing-call__avatar">
              <CometChatAvatar.Root
                name={call.getCallReceiver()?.getName()}
                image={(call.getCallReceiver() as CometChat.User)?.getAvatar()}
              >
                <CometChatAvatar.Image />
                <CometChatAvatar.Initials />
              </CometChatAvatar.Root>
            </div>
          }
        />
      );
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .outgoing-call__avatar .cometchat-avatar {
      width: 160px;
      height: 160px;
      border-radius: 20px;
    }
    ```
  </Tab>
</Tabs>

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-outgoing-call {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-outgoing-call__button {
  background: var(--cometchat-error-color);
}
```

***

## Props

The `call` prop is required. All other props are optional.

***

### call

The CometChat call object representing the outgoing call. **Required.**

|          |                  |
| -------- | ---------------- |
| Type     | `CometChat.Call` |
| Required | Yes              |

***

### disableSoundForCalls

Disable the outgoing call sound.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### customSoundForCalls

Custom sound URL to play during the outgoing call (replaces the built-in sound).

|         |                              |
| ------- | ---------------------------- |
| Type    | `string`                     |
| Default | Built-in outgoing call sound |

***

### onCallCanceled

Callback when the user clicks the cancel/end button.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onError

Callback when an SDK error occurs.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `null`                                                    |

***

### titleView

Custom view that replaces the receiver name.

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

### subtitleView

Custom view that replaces the "Calling..." text.

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

### avatarView

Custom view that replaces the receiver avatar.

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

### cancelButtonView

Custom view that replaces the end-call button.

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

### className

Additional CSS class name applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target             | Selector                                    |
| ------------------ | ------------------------------------------- |
| Root container     | `.cometchat-outgoing-call`                  |
| Title container    | `.cometchat-outgoing-call__title-container` |
| Title              | `.cometchat-outgoing-call__title`           |
| Subtitle           | `.cometchat-outgoing-call__subtitle`        |
| Avatar             | `.cometchat-outgoing-call__avatar`          |
| Cancel button      | `.cometchat-outgoing-call__button`          |
| Cancel button icon | `.cometchat-outgoing-call__button-icon`     |

***

## Next Steps

<CardGroup>
  <Card title="Incoming Call" icon="phone-arrow-down-left" href="/ui-kit/react/components/incoming-call">
    Handle incoming call notifications with accept/decline actions
  </Card>

  <Card title="Call Logs" icon="clock-rotate-left" href="/ui-kit/react/components/call-logs">
    Browse call history and re-initiate calls
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Poll Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/poll-bubble

A self-extracting bubble that renders a poll with its question, selectable options, live vote counts, percentages, and voter avatars.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatPollBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatPollBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Self-extracting poll bubble. Derives the question, options, vote counts, totals, and the logged-in user's vote from the message metadata.",
    "cssRootClass": ".cometchat-poll-bubble",
    "selfExtracting": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.CustomMessage", "required": true, "note": "Contains poll data in its metadata; drives all extraction." },
        "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." },
        "disableInteraction": { "type": "boolean", "default": false },
        "onVoteSubmit": { "type": "(event: CometChatPollVoteEvent) => void" },
        "onVoteError": { "type": "(event: CometChatPollVoteErrorEvent) => void" },
        "className": { "type": "string" }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatPollBubble` renders a poll. It is **self-extracting**: pass the SDK custom `message` and the bubble derives the question, options, per-option vote counts, total votes, and the logged-in user's selected option entirely from the message metadata. Selecting an option submits a vote; the bar fills and counts/avatars update.

<Info>
  **Live Preview** — interact with the poll bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble--poll-message)
</Info>

<iframe title="CometChat Poll Bubble — Default" />

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatPollBubble } from "@cometchat/chat-uikit-react";

function PollMessage({ message }: { message: CometChat.CustomMessage }) {
  return (
    <CometChatPollBubble
      message={message}
      onVoteSubmit={(e) => console.log("Voted:", e.optionText)}
    />
  );
}
```

***

## Props

### message

The custom message containing poll data in its metadata. Drives all extraction. **Required.**

|          |                           |
| -------- | ------------------------- |
| Type     | `CometChat.CustomMessage` |
| Required | Yes                       |

***

### alignment

Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user.

|         |                     |
| ------- | ------------------- |
| Type    | `"left" \| "right"` |
| Default | derived             |

***

### disableInteraction

Disable all interaction (e.g. for a thread header preview).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### onVoteSubmit

Callback when a vote is submitted successfully.

|         |                                           |
| ------- | ----------------------------------------- |
| Type    | `(event: CometChatPollVoteEvent) => void` |
| Default | `undefined`                               |

***

### onVoteError

Callback when a vote submission fails.

|         |                                                |
| ------- | ---------------------------------------------- |
| Type    | `(event: CometChatPollVoteErrorEvent) => void` |
| Default | `undefined`                                    |

***

### className

Additional CSS class applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target              | Selector                                                                |
| ------------------- | ----------------------------------------------------------------------- |
| Root                | `.cometchat-poll-bubble`                                                |
| Incoming / outgoing | `.cometchat-poll-bubble--incoming` / `.cometchat-poll-bubble--outgoing` |
| Option              | `.cometchat-poll-bubble__option`                                        |
| Option text         | `.cometchat-poll-bubble__option-text`                                   |
| Option count        | `.cometchat-poll-bubble__option-count`                                  |
| Option progress bar | `.cometchat-poll-bubble__option-progress-bar`                           |
| Option radio        | `.cometchat-poll-bubble__option-radio`                                  |
| Voter avatars       | `.cometchat-poll-bubble__option-avatars`                                |

***

## Next Steps

<CardGroup>
  <Card title="Polls Plugin" icon="square-poll-vertical" href="/ui-kit/react/plugins/overview#built-in-plugins">
    Plugin behavior, context menu, and conversation preview
  </Card>

  <Card title="Sticker Bubble" icon="face-smile" href="/ui-kit/react/components/sticker-bubble">
    Render sticker messages
  </Card>

  <Card title="Message Bubble" icon="comment" href="/ui-kit/react/components/message-bubble">
    The wrapper that hosts bubble content
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Reaction List
Source: https://www.cometchat.com/docs/ui-kit/react/components/reaction-list

Standalone panel showing who reacted to a message, with emoji tab filtering, pagination, and optimistic removal for the current user.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatReactionList",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatReactionList } from \"@cometchat/chat-uikit-react\";",
    "description": "Standalone panel showing who reacted to a message, with emoji tab filtering, pagination, and optimistic removal for the current user.",
    "cssRootClass": ".cometchat-reaction-list",
    "primaryOutput": {
      "prop": "onItemClick",
      "type": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void"
    },
    "props": {
      "data": {
        "message": { "type": "CometChat.BaseMessage", "note": "Required. The message to show reactions for." },
        "reactionsRequestBuilder": { "type": "CometChat.ReactionsRequestBuilder" }
      },
      "callbacks": {
        "onItemClick": { "type": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void", "note": "Fires only for current user's reactions (to remove)." },
        "onEmpty": { "type": "() => void", "note": "Fires when all reactions are removed. Parent should close the panel." },
        "onError": { "type": "(error: unknown) => void" }
      }
    },
    "types": {
      "CometChatReactionListRootProps": "Root provider props",
      "CometChatReactionListTabsProps": "Emoji tab bar props",
      "CometChatReactionListItemsProps": "Scrollable reactor list props",
      "CometChatReactionListLoadingStateProps": "Shimmer loading state props",
      "CometChatReactionListErrorStateProps": "Error state props",
      "CometChatReactionListEmptyStateProps": "Empty state props",
      "CometChatReactionListContextValue": "Full context value"
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatReactionList` is a **standalone** component — it manages its own state and does not depend on `CometChatReactions.Root` context. It is distinct from `CometChatReactions.List`, which is a sub-component of `CometChatReactions`.

<Info>
  **Live Preview** — interact with the reaction list component.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-misc-reaction-list--default)
</Info>

<iframe title="CometChat Reaction List — Default" />

Use `CometChatReactionList` when you want to show a dedicated panel (e.g., inside a popover or bottom sheet) listing all users who reacted to a message, with tab filtering by emoji and the ability for the current user to remove their own reaction.

The parent component (typically `CometChatMessageList`) owns the SDK reaction add/remove calls and passes an updated `message` prop when reactions change.

```tsx lines theme={null}
import { CometChatReactionList } from "@cometchat/chat-uikit-react";

function ReactionPanel({ message, onClose }) {
  return (
    <CometChatReactionList
      message={message}
      onItemClick={(reaction, msg) => {
        // Parent calls SDK to remove the reaction
        CometChat.removeReaction(String(msg.getId()), reaction.getReaction());
      }}
      onEmpty={onClose}
    />
  );
}
```

## Minimal Render

```tsx lines theme={null}
import { CometChatReactionList } from "@cometchat/chat-uikit-react";

function Demo({ message }) {
  return <CometChatReactionList message={message} />;
}
```

Root CSS class: `.cometchat-reaction-list`

## Sub-Components

`CometChatReactionList` is a compound component with these sub-components:

| Sub-Component  | Purpose                                                                                 |
| -------------- | --------------------------------------------------------------------------------------- |
| `Root`         | Context provider. Receives message and config. Renders default layout when no children. |
| `Tabs`         | Emoji tab bar — "All" tab plus one tab per unique emoji. Keyboard navigable.            |
| `Items`        | Scrollable list of users who reacted. IntersectionObserver pagination.                  |
| `LoadingState` | Shimmer loading placeholder. Self-hides when not loading.                               |
| `ErrorState`   | Error message with retry button. Self-hides when not in error state.                    |
| `EmptyState`   | Empty message. Self-hides when not empty.                                               |

### Custom Layout

Compose sub-components to customize the layout:

```tsx lines theme={null}
<CometChatReactionList.Root message={message} onItemClick={handleRemove}>
  <CometChatReactionList.Tabs />
  <CometChatReactionList.LoadingState />
  <CometChatReactionList.ErrorState />
  <CometChatReactionList.EmptyState />
  <CometChatReactionList.Items />
</CometChatReactionList.Root>
```

### Custom Header

Add a custom header above the tabs:

```tsx lines theme={null}
<CometChatReactionList.Root message={message}>
  <div className="my-header">Reactions</div>
  <CometChatReactionList.Tabs />
  <CometChatReactionList.Items />
</CometChatReactionList.Root>
```

## Actions and Events

### Callback Props

#### onItemClick

Called when a reaction item is clicked. Only fires for the **current user's own reactions** — non-current-user items are read-only. The parent should call the SDK to remove the reaction.

```tsx lines theme={null}
<CometChatReactionList
  message={message}
  onItemClick={(reaction, msg) => {
    CometChat.removeReaction(String(msg.getId()), reaction.getReaction())
      .then(() => console.log("Reaction removed"))
      .catch(console.error);
  }}
/>
```

#### onEmpty

Called when all reactions are removed (after optimistic removal). The parent should close the panel.

```tsx lines theme={null}
const [showPanel, setShowPanel] = useState(true);

{showPanel && (
  <CometChatReactionList
    message={message}
    onEmpty={() => setShowPanel(false)}
  />
)}
```

#### onError

Called when an error occurs during reaction fetching.

```tsx lines theme={null}
<CometChatReactionList
  message={message}
  onError={(error) => console.error("Reaction list error:", error)}
/>
```

## Behavior Details

### Emoji Tabs

* "All" tab shows every reactor across all emojis.
* Per-emoji tabs show only reactors for that emoji.
* Tab counts update optimistically when the current user removes a reaction.
* Keyboard navigation: `ArrowLeft` / `ArrowRight` to move between tabs, `Enter` / `Space` to select.

### Reactor Items

* Each item shows: avatar, name (or "You" for the current user), "Click to remove" hint (current user only), and the emoji.
* Current user items: `cursor: pointer`, `tabIndex={0}`, clickable via `Enter` / `Space`.
* Non-current-user items: `cursor: default`, `tabIndex={-1}`, not interactive.

### Pagination

Reactions are fetched in pages (default limit: 30). An `IntersectionObserver` sentinel at the bottom of the list triggers `fetchMore()` when the user scrolls near the bottom.

### Optimistic Removal

When the current user clicks their reaction:

1. The reaction is removed from the list immediately (optimistic update).
2. `onItemClick` is called so the parent can call the SDK.
3. If no reactions remain, `onEmpty` is called.

The component does **not** call the SDK itself — the parent owns that responsibility.

### Custom Request Builder

Pass a custom `ReactionsRequestBuilder` to control the fetch limit or other parameters:

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";

const builder = new CometChat.ReactionsRequestBuilder().setLimit(50);

<CometChatReactionList
  message={message}
  reactionsRequestBuilder={builder}
/>
```

## CSS Architecture

The component uses CSS custom properties provided by the UI Kit.

### Key Selectors

| Target              | Selector                                            |
| ------------------- | --------------------------------------------------- |
| Root                | `.cometchat-reaction-list`                          |
| Tabs bar            | `.cometchat-reaction-list__tabs`                    |
| Tab button          | `.cometchat-reaction-list__tabs-tab`                |
| Tab (active)        | `.cometchat-reaction-list__tabs-tab--active`        |
| Tab emoji           | `.cometchat-reaction-list__tabs-tab-emoji`          |
| Tab emoji (active)  | `.cometchat-reaction-list__tabs-tab-emoji--active`  |
| Tab count           | `.cometchat-reaction-list__tabs-tab-count`          |
| Tab count (active)  | `.cometchat-reaction-list__tabs-tab-count--active`  |
| Items list          | `.cometchat-reaction-list__list`                    |
| List item           | `.cometchat-reaction-list__list-item`               |
| Item (current user) | `.cometchat-reaction-list__list-item--current-user` |
| Item (read-only)    | `.cometchat-reaction-list__list-item--readonly`     |
| Item avatar         | `.cometchat-reaction-list__item-avatar`             |
| Item name           | `.cometchat-reaction-list__item-name`               |
| Item hint           | `.cometchat-reaction-list__item-hint`               |
| Item emoji          | `.cometchat-reaction-list__item-emoji`              |
| Shimmer             | `.cometchat-reaction-list__shimmer`                 |
| Error               | `.cometchat-reaction-list__error`                   |
| Retry button        | `.cometchat-reaction-list__retry-button`            |
| Empty               | `.cometchat-reaction-list__empty`                   |
| Loading more        | `.cometchat-reaction-list__loading-more`            |
| Spinner             | `.cometchat-reaction-list__spinner`                 |

### Example: Custom styling

```css lines title="App.css" theme={null}
/* Wider panel */
.cometchat-reaction-list {
  width: 320px;
}

/* Custom active tab color */
.cometchat-reaction-list__tabs-tab--active {
  border-bottom-color: var(--my-brand-color);
}

.cometchat-reaction-list__tabs-tab-emoji--active,
.cometchat-reaction-list__tabs-tab-count--active {
  color: var(--my-brand-color);
}
```

## Props

All props are optional unless noted otherwise.

***

### message

The SDK message object to show reactions for. **Required.**

|         |                         |
| ------- | ----------------------- |
| Type    | `CometChat.BaseMessage` |
| Default | —                       |

***

### reactionsRequestBuilder

Custom request builder for fetching reactor details. Controls limit and other fetch parameters.

|         |                                                        |
| ------- | ------------------------------------------------------ |
| Type    | `CometChat.ReactionsRequestBuilder`                    |
| Default | `new CometChat.ReactionsRequestBuilder().setLimit(30)` |

***

### onItemClick

Called when the current user clicks their own reaction item (to remove it). Not called for other users' reactions.

|         |                                                                          |
| ------- | ------------------------------------------------------------------------ |
| Type    | `(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void` |
| Default | `undefined`                                                              |

***

### onEmpty

Called when all reactions are removed. The parent should close the panel.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onError

Error callback for reaction fetching failures.

|         |                            |
| ------- | -------------------------- |
| Type    | `(error: unknown) => void` |
| Default | `undefined`                |

***

### children

Custom sub-components. When omitted, renders the default layout (Tabs + LoadingState + ErrorState + EmptyState + Items).

|         |                |
| ------- | -------------- |
| Type    | `ReactNode`    |
| Default | Default layout |

***

### className

Optional custom CSS class for the root container.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

## Accessibility

* Root has `role="dialog"` and `aria-label="Reaction list"`.
* Tab bar has `role="tablist"` with `aria-label="Reaction filters"`.
* Each tab has `role="tab"` and `aria-selected`.
* Items container has `role="list"` with a descriptive `aria-label`.
* Each item has `role="listitem"` and `aria-label` describing the user, emoji, and hint.
* Current user items have `tabIndex={0}` and respond to `Enter` / `Space`.
* Read-only items have `tabIndex={-1}`.
* All interactive elements have `:focus-visible` styles.
* Shimmer respects `prefers-reduced-motion`.
* Spinner respects `prefers-reduced-motion`.
* High contrast mode supported via `@media (prefers-contrast: high)`.


# Reactions
Source: https://www.cometchat.com/docs/ui-kit/react/components/reactions

Displays emoji reaction chips on message bubbles with hover tooltips, a full reactor list, and overflow handling.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatReactions",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatReactions } from \"@cometchat/chat-uikit-react\";",
    "description": "Displays emoji reaction chips on message bubbles with hover tooltips, a full reactor list, and overflow handling.",
    "cssRootClass": ".cometchat-reactions",
    "primaryOutput": {
      "prop": "onReactionClick",
      "type": "(emoji: string, message: CometChat.BaseMessage) => void"
    },
    "props": {
      "data": {
        "message": { "type": "CometChat.BaseMessage", "note": "Required. The message to show reactions for." },
        "alignment": { "type": "'left' | 'right' | 'center'", "default": "'left'" },
        "reactionsRequestBuilder": { "type": "CometChat.ReactionsRequestBuilder" }
      },
      "callbacks": {
        "onReactionClick": { "type": "(emoji: string, message: CometChat.BaseMessage) => void" },
        "onReactorClick": { "type": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void" },
        "onError": { "type": "(error: unknown) => void" }
      },
      "config": {
        "hoverDebounceTime": { "type": "number", "note": "Debounce (ms) before showing the hover tooltip." }
      }
    },
    "types": {
      "CometChatReactionsRootProps": "Root provider props",
      "CometChatReactionsBarProps": "Reaction chips bar props",
      "CometChatReactionsChipProps": "Single reaction chip props",
      "CometChatReactionsInfoProps": "Hover tooltip props",
      "CometChatReactionsOverflowProps": "Overflow button props"
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatReactions` renders below message bubbles to show emoji reactions. It is typically used inside `CometChatMessageBubble` as the footer view. The parent (usually `CometChatMessageList`) owns the reaction add/remove SDK calls and passes the updated message down.

<Info>
  **Live Preview** — interact with the reactions component.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-misc-reactions--default)
</Info>

<iframe title="CometChat Reactions — Default" />

```tsx lines theme={null}
import { CometChatReactions } from "@cometchat/chat-uikit-react";

function MessageBubbleFooter({ message, onReactionClick }) {
  return (
    <CometChatReactions.Root
      message={message}
      alignment="right"
      onReactionClick={onReactionClick}
    />
  );
}
```

## Minimal Render

```tsx lines theme={null}
import { CometChatReactions } from "@cometchat/chat-uikit-react";

function Demo({ message }) {
  return <CometChatReactions.Root message={message} />;
}
```

Root CSS class: `.cometchat-reactions`

## Sub-Components

`CometChatReactions` is a compound component with these sub-components:

| Sub-Component | Purpose                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------ |
| `Root`        | Context provider. Receives message and config.                                             |
| `Bar`         | Reaction chips container with `role="group"`. Auto-calculates overflow via ResizeObserver. |
| `Chip`        | Single reaction button with emoji, count, and `aria-pressed`.                              |
| `Info`        | Hover tooltip showing who reacted with a specific emoji.                                   |
| `Overflow`    | "+N more" button for overflow reactions.                                                   |

### Custom Layout

Compose sub-components to customize the layout:

```tsx lines theme={null}
<CometChatReactions.Root message={message}>
  <CometChatReactions.Bar maxVisible={5} />
</CometChatReactions.Root>
```

<Note>
  For a standalone reactor list (the full list of who reacted, with tab filtering and pagination), use the dedicated [`CometChatReactionList`](/docs/ui-kit/react/components/reaction-list) component — it is separate from `CometChatReactions`.
</Note>

## Actions and Events

### Callback Props

#### onReactionClick

Called when a reaction chip is clicked. The parent (MessageList) handles the SDK call for adding/removing the reaction.

```tsx lines theme={null}
<CometChatReactions.Root
  message={message}
  onReactionClick={(emoji, msg) => {
    console.log(`Toggled ${emoji} on message ${msg.getId()}`);
  }}
/>
```

#### onReactorClick

Called when a user in the reaction list is clicked. Useful for removing own reactions.

```tsx lines theme={null}
<CometChatReactions.Root
  message={message}
  onReactorClick={(reaction, msg) => {
    console.log(`Clicked reactor: ${reaction.getReactedBy().getName()}`);
  }}
/>
```

#### onError

Called when an error occurs during reactor detail fetching.

```tsx lines theme={null}
<CometChatReactions.Root
  message={message}
  onError={(error) => console.error("Reaction error:", error)}
/>
```

## CSS Architecture

The component uses CSS custom properties provided by the UI Kit.

### Key Selectors

| Target            | Selector                                      |
| ----------------- | --------------------------------------------- |
| Root              | `.cometchat-reactions`                        |
| Bar               | `.cometchat-reactions__bar`                   |
| Chip              | `.cometchat-reactions__chip`                  |
| Chip (active)     | `.cometchat-reactions__chip--active`          |
| Chip emoji        | `.cometchat-reactions__chip-emoji`            |
| Chip count        | `.cometchat-reactions__chip-count`            |
| Overflow          | `.cometchat-reactions__overflow`              |
| Info tooltip      | `.cometchat-reactions__info`                  |
| Info content      | `.cometchat-reactions__info-content`          |
| List              | `.cometchat-reactions__list`                  |
| List tabs         | `.cometchat-reactions__list-tabs`             |
| List tab (active) | `.cometchat-reactions__list-tabs-tab--active` |
| List items        | `.cometchat-reactions__list-items`            |

### Example: Custom chip styling

```css lines title="App.css" theme={null}
.cometchat-reactions__chip {
  border-radius: 8px;
  border-color: var(--cometchat-border-color-default);
}

.cometchat-reactions__chip--active {
  background: var(--cometchat-extended-primary-color-200);
}
```

## Props

All props are optional unless noted otherwise.

***

### message

The SDK message object to show reactions for. **Required.**

|         |                         |
| ------- | ----------------------- |
| Type    | `CometChat.BaseMessage` |
| Default | —                       |

***

### alignment

Bubble alignment for positioning the overflow popover.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `'left' \| 'right' \| 'center'` |
| Default | `'left'`                        |

***

### reactionsRequestBuilder

Custom request builder for fetching reactor details.

|         |                                     |
| ------- | ----------------------------------- |
| Type    | `CometChat.ReactionsRequestBuilder` |
| Default | `undefined`                         |

***

### hoverDebounceTime

Debounce delay (in milliseconds) before the hover tooltip (`Info`) appears when hovering a reaction chip.

|         |             |
| ------- | ----------- |
| Type    | `number`    |
| Default | `undefined` |

***

### onReactionClick

Called when a reaction chip is clicked. Parent handles the SDK call.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `(emoji: string, message: CometChat.BaseMessage) => void` |
| Default | `undefined`                                               |

***

### onReactorClick

Called when a user in the reaction list is clicked.

|         |                                                                          |
| ------- | ------------------------------------------------------------------------ |
| Type    | `(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void` |
| Default | `undefined`                                                              |

***

### onError

Error callback for reactor detail fetching failures.

|         |                            |
| ------- | -------------------------- |
| Type    | `(error: unknown) => void` |
| Default | `undefined`                |

***

### children

Custom sub-components. When omitted, renders the default Bar layout.

|         |                              |
| ------- | ---------------------------- |
| Type    | `ReactNode`                  |
| Default | `<CometChatReactions.Bar />` |

***

### className

Optional custom CSS class for the root container.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

## CSS Selectors

| Target            | Selector                                      |
| ----------------- | --------------------------------------------- |
| Root              | `.cometchat-reactions`                        |
| Bar               | `.cometchat-reactions__bar`                   |
| Chip              | `.cometchat-reactions__chip`                  |
| Chip (active)     | `.cometchat-reactions__chip--active`          |
| Chip emoji        | `.cometchat-reactions__chip-emoji`            |
| Chip count        | `.cometchat-reactions__chip-count`            |
| Overflow button   | `.cometchat-reactions__overflow`              |
| Overflow count    | `.cometchat-reactions__overflow-count`        |
| Info tooltip      | `.cometchat-reactions__info`                  |
| Info content      | `.cometchat-reactions__info-content`          |
| Info emoji        | `.cometchat-reactions__info-emoji`            |
| Info title        | `.cometchat-reactions__info-title`            |
| Info description  | `.cometchat-reactions__info-description`      |
| Info loading      | `.cometchat-reactions__info-loading`          |
| Info error        | `.cometchat-reactions__info-error`            |
| List container    | `.cometchat-reactions__list`                  |
| List tabs         | `.cometchat-reactions__list-tabs`             |
| List tab          | `.cometchat-reactions__list-tabs-tab`         |
| List tab (active) | `.cometchat-reactions__list-tabs-tab--active` |
| List items        | `.cometchat-reactions__list-items`            |
| List item         | `.cometchat-reactions__list-item`             |
| List error        | `.cometchat-reactions__list-error`            |
| List shimmer      | `.cometchat-reactions__list-shimmer`          |


# Search
Source: https://www.cometchat.com/docs/ui-kit/react/components/search

Unified search across conversations and messages with filter chips, scoped search, and customizable result views.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatSearch",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatSearch } from \"@cometchat/chat-uikit-react\";",
    "description": "Unified search across conversations and messages with filter chips, scoped search, and customizable result views.",
    "cssRootClass": ".cometchat-search",
    "primaryOutput": {
      "prop": "onConversationClicked",
      "type": "(event: CometChatSearchConversationClickEvent) => void"
    },
    "props": {
      "data": {
        "searchIn": {
          "type": "CometChatSearchScope[]",
          "default": "[] (both conversations and messages)",
          "note": "Empty array shows both sections"
        },
        "searchFilters": {
          "type": "CometChatSearchFilter[]",
          "default": "all available filters"
        },
        "initialSearchFilter": {
          "type": "CometChatSearchFilter",
          "default": "undefined"
        },
        "defaultSearchText": {
          "type": "string",
          "default": "undefined"
        },
        "uid": {
          "type": "string",
          "default": "undefined",
          "note": "Scope search to a specific user's conversation"
        },
        "guid": {
          "type": "string",
          "default": "undefined",
          "note": "Scope search to a specific group's conversation"
        },
        "lastMessageDateTimeFormat": {
          "type": "CometChatDateFormatConfig",
          "default": "DD/MM/YYYY for all date ranges in search context"
        },
        "messageSentAtDateTimeFormat": {
          "type": "CometChatDateFormatConfig",
          "default": "undefined"
        },
        "conversationsRequestBuilder": {
          "type": "CometChat.ConversationsRequestBuilder",
          "default": "SDK default",
          "note": "Pass the builder instance, not the result of .build()"
        },
        "messagesRequestBuilder": {
          "type": "CometChat.MessagesRequestBuilder",
          "default": "SDK default",
          "note": "Pass the builder instance, not the result of .build()"
        },
        "textFormatters": {
          "type": "CometChatTextFormatter[]",
          "default": "undefined"
        }
      },
      "callbacks": {
        "onBack": "() => void",
        "onConversationClicked": "(event: CometChatSearchConversationClickEvent) => void",
        "onMessageClicked": "(event: CometChatSearchMessageClickEvent) => void",
        "onError": "((error: CometChat.CometChatException) => void) | null"
      },
      "visibility": {
        "hideBackButton": { "type": "boolean", "default": false },
        "hideUserStatus": { "type": "boolean", "default": false },
        "hideGroupType": { "type": "boolean", "default": false },
        "hideReceipts": { "type": "boolean", "default": false }
      },
      "viewSlots": {
        "initialView": "ReactNode",
        "loadingView": "ReactNode",
        "emptyView": "ReactNode",
        "errorView": "ReactNode",
        "conversationItemView": "(conversation: CometChat.Conversation) => ReactNode",
        "conversationLeadingView": "(conversation: CometChat.Conversation) => ReactNode",
        "conversationTitleView": "(conversation: CometChat.Conversation) => ReactNode",
        "conversationSubtitleView": "(conversation: CometChat.Conversation) => ReactNode",
        "conversationTrailingView": "(conversation: CometChat.Conversation) => ReactNode",
        "messageItemView": "(message: CometChat.BaseMessage) => ReactNode",
        "messageLeadingView": "(message: CometChat.BaseMessage) => ReactNode",
        "messageTitleView": "(message: CometChat.BaseMessage) => ReactNode",
        "messageSubtitleView": "(message: CometChat.BaseMessage) => ReactNode",
        "messageTrailingView": "(message: CometChat.BaseMessage) => ReactNode",
        "conversationOptions": "(conversation: CometChat.Conversation) => CometChatSearchConversationOption[]"
      }
    },
    "events": [],
    "sdkListeners": [],
    "types": {
      "CometChatSearchScope": "'conversations' | 'messages'",
      "CometChatSearchFilter": "'messages' | 'conversations' | 'unread' | 'groups' | 'photos' | 'videos' | 'links' | 'files' | 'audio'",
      "CometChatSearchConversationClickEvent": {
        "conversation": "CometChat.Conversation",
        "searchKeyword": "string"
      },
      "CometChatSearchMessageClickEvent": {
        "message": "CometChat.BaseMessage",
        "searchKeyword": "string"
      },
      "CometChatSearchConversationOption": {
        "id": "string",
        "title": "string",
        "iconURL": "string | undefined",
        "onClick": "(conversation: CometChat.Conversation) => void"
      },
      "CometChatDateFormatConfig": {
        "today": "string | undefined",
        "yesterday": "string | undefined",
        "lastWeek": "string | undefined",
        "otherDays": "string | undefined",
        "relativeTime": {
          "minute": "string | undefined",
          "minutes": "string | undefined",
          "hour": "string | undefined",
          "hours": "string | undefined"
        }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatSearch` is a unified search component. It searches across conversations and messages, displaying results in separate sections with filter chips for scoping. It emits the selected result via `onConversationClicked` or `onMessageClicked` — both include the `searchKeyword` in the event payload. Wire it to `CometChatConversations` or `CometChatMessageList` to navigate to the matched result.

<Info>
  **Live Preview** — interact with the default search component.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-cometchatsearch--default)
</Info>

<iframe title="CometChat Search — Default" />

The component handles:

* Dual-section results (conversations + messages)
* Filter chips for scoping (messages, conversations, unread, groups, photos, videos, links, files, audio)
* Scoped search via `uid` or `guid`
* Custom request builders for both conversations and messages
* Customizable result item views

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatSearch } from "@cometchat/chat-uikit-react";

function SearchPanel() {
  return (
    <CometChatSearch
      onConversationClicked={(event) => {
        // event.conversation — the matched conversation
        // event.searchKeyword — the search term used
        navigateToConversation(event.conversation);
      }}
      onMessageClicked={(event) => {
        // event.message — the matched message
        // event.searchKeyword — the search term used
        scrollToMessage(event.message);
      }}
    />
  );
}
```

### Compound Composition

```tsx theme={null}
import { CometChatSearch } from "@cometchat/chat-uikit-react";

function SearchPanel() {
  return (
    <CometChatSearch.Root
      onConversationClicked={handleConversationClick}
      onMessageClicked={handleMessageClick}
    >
      <CometChatSearch.ConversationsList />
      <CometChatSearch.MessagesList />
    </CometChatSearch.Root>
  );
}
```

### Scoped Search Example

```tsx theme={null}
import { CometChatSearch } from "@cometchat/chat-uikit-react";

function ConversationSearch({ userId }: { userId: string }) {
  return (
    <CometChatSearch
      uid={userId}
      searchIn={["messages"]}
      onMessageClicked={(event) => {
        scrollToMessage(event.message);
      }}
      onBack={() => closeSearch()}
    />
  );
}
```

### Full Layout Example

```tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatConversations,
  CometChatSearch,
  CometChatMessageList,
} from "@cometchat/chat-uikit-react";

function ChatApp() {
  const [showSearch, setShowSearch] = useState(false);
  const [user, setUser] = useState<CometChat.User | undefined>();
  const [group, setGroup] = useState<CometChat.Group | undefined>();

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        {showSearch ? (
          <CometChatSearch
            onConversationClicked={(event) => {
              const entity = event.conversation.getConversationWith();
              if (event.conversation.getConversationType() === "user") {
                setUser(entity as CometChat.User);
                setGroup(undefined);
              } else {
                setGroup(entity as CometChat.Group);
                setUser(undefined);
              }
              setShowSearch(false);
            }}
            onBack={() => setShowSearch(false)}
          />
        ) : (
          <CometChatConversations
            onSearchBarClicked={() => setShowSearch(true)}
            onItemClick={(conversation) => {
              const entity = conversation.getConversationWith();
              if (conversation.getConversationType() === "user") {
                setUser(entity as CometChat.User);
                setGroup(undefined);
              } else {
                setGroup(entity as CometChat.Group);
                setUser(undefined);
              }
            }}
          />
        )}
      </div>
      <div style={{ flex: 1 }}>
        <CometChatMessageList user={user} group={group} />
      </div>
    </div>
  );
}
```

***

## Filtering

### Search Scope

Control which result sections appear using `searchIn`:

```tsx theme={null}
{/* Only show conversation results */}
<CometChatSearch searchIn={["conversations"]} />

{/* Only show message results */}
<CometChatSearch searchIn={["messages"]} />

{/* Both (default) */}
<CometChatSearch searchIn={[]} />
```

### Filter Chips

Control which filter chips are available:

```tsx theme={null}
<CometChatSearch
  searchFilters={["messages", "conversations", "unread", "photos"]}
  initialSearchFilter="messages"
/>
```

### Scoped Search

Scope the search to a specific user or group conversation:

```tsx theme={null}
{/* Search within a specific user's conversation */}
<CometChatSearch uid="user-123" />

{/* Search within a specific group's conversation */}
<CometChatSearch guid="group-456" />
```

### Custom Request Builders

Pass custom request builders for fine-grained control:

```tsx theme={null}
<CometChatSearch
  conversationsRequestBuilder={
    new CometChat.ConversationsRequestBuilder()
      .setLimit(15)
      .setConversationType("user")
  }
  messagesRequestBuilder={
    new CometChat.MessagesRequestBuilder()
      .setLimit(20)
      .setSearchKeyword("hello")
  }
/>
```

***

## Actions and Events

### Callback Props

| Prop                    | Signature                                                 | Fires when                        |
| ----------------------- | --------------------------------------------------------- | --------------------------------- |
| `onConversationClicked` | `(event: CometChatSearchConversationClickEvent) => void`  | User clicks a conversation result |
| `onMessageClicked`      | `(event: CometChatSearchMessageClickEvent) => void`       | User clicks a message result      |
| `onBack`                | `() => void`                                              | Back button is clicked            |
| `onError`               | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs                  |

### Events Emitted

None.

### Events Received

None.

### SDK Listeners (Automatic)

None — the component fetches results on search input change and does not subscribe to real-time SDK listeners.

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatSearch
  initialView={<RecentSearches />}
  emptyView={<NoResults />}
  loadingView={<SearchSkeleton />}
  errorView={<SearchError />}
  conversationItemView={(conversation) => (
    <MyCustomConversationResult conversation={conversation} />
  )}
  messageItemView={(message) => (
    <MyCustomMessageResult message={message} />
  )}
/>
```

| Slot                       | Signature                     | Replaces                                |
| -------------------------- | ----------------------------- | --------------------------------------- |
| `initialView`              | `ReactNode`                   | Pre-search state (before user types)    |
| `loadingView`              | `ReactNode`                   | Loading shimmer                         |
| `emptyView`                | `ReactNode`                   | Empty state (no results)                |
| `errorView`                | `ReactNode`                   | Error state                             |
| `conversationItemView`     | `(conversation) => ReactNode` | Entire conversation result row          |
| `conversationLeadingView`  | `(conversation) => ReactNode` | Avatar section of conversation result   |
| `conversationTitleView`    | `(conversation) => ReactNode` | Title of conversation result            |
| `conversationSubtitleView` | `(conversation) => ReactNode` | Subtitle of conversation result         |
| `conversationTrailingView` | `(conversation) => ReactNode` | Trailing section of conversation result |
| `messageItemView`          | `(message) => ReactNode`      | Entire message result row               |
| `messageLeadingView`       | `(message) => ReactNode`      | Avatar section of message result        |
| `messageTitleView`         | `(message) => ReactNode`      | Title of message result                 |
| `messageSubtitleView`      | `(message) => ReactNode`      | Subtitle of message result              |
| `messageTrailingView`      | `(message) => ReactNode`      | Trailing section of message result      |

#### messageItemView

Replace the entire message list item in search results.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatSearch } from "@cometchat/chat-uikit-react";

    function SearchCustomMessageItem() {
      const getMessageItemView = (message: CometChat.BaseMessage) => (
        <div className="cometchat-search__message-list-item">
          <div className="cometchat-search__message-list-item-sender">
            {message.getSender()?.getName()}:
          </div>
          <div className="cometchat-search__message-list-item-text">
            {message instanceof CometChat.TextMessage
              ? (message as CometChat.TextMessage).getText()
              : message.getType()}
          </div>
        </div>
      );

      return <CometChatSearch messageItemView={getMessageItemView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-search__message-list-item {
      background: var(--cometchat-extended-primary-color-100);
      border-bottom: 1px solid var(--cometchat-border-color-highlight);
      padding: var(--cometchat-padding-3) var(--cometchat-padding-4);
      display: flex;
      justify-content: flex-start;
      gap: var(--cometchat-padding-2);
    }

    .cometchat-search__message-list-item-sender {
      color: var(--cometchat-text-color-highlight);
      font: var(--cometchat-font-body-regular);
    }

    .cometchat-search__message-list-item-text {
      color: var(--cometchat-text-color-secondary);
      font: var(--cometchat-font-body-regular);
    }
    ```
  </Tab>
</Tabs>

#### messageLeadingView

Replace the message avatar / left section.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatSearch } from "@cometchat/chat-uikit-react";

    function SearchCustomMessageLeading() {
      const getMessageLeadingView = (message: CometChat.BaseMessage) => (
        <div className="cometchat-search__message-list-item-leading-view">
          <img src="ICON_URL" alt="" />
        </div>
      );

      return <CometChatSearch messageLeadingView={getMessageLeadingView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-search__message-list-item-leading-view {
      height: 48px;
      width: 48px;
      border-radius: var(--cometchat-radius-2);
      background: var(--cometchat-extended-primary-color-500);
      display: flex;
      align-items: center;
      justify-content: center;
    }

    .cometchat-search__message-list-item-leading-view img {
      height: 32px;
      width: 32px;
    }
    ```
  </Tab>
</Tabs>

#### messageTitleView

Replace the message title text.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatSearch } from "@cometchat/chat-uikit-react";

    function SearchCustomMessageTitle() {
      const getMessageTitleView = (message: CometChat.BaseMessage) => (
        <div className="cometchat-search__message-list-item-title">
          <div className="cometchat-search__message-list-item-title-text">
            {message.getSender()?.getName()}
          </div>
          <span>|</span>
          <div className="cometchat-search__message-list-item-title-role">
            {message.getSender().getRole() ?? "Pro User"}
          </div>
        </div>
      );

      return <CometChatSearch messageTitleView={getMessageTitleView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-search__message-list-item-title {
      display: flex;
      align-items: center;
      gap: var(--cometchat-spacing-1);
    }

    .cometchat-search__message-list-item-title-text {
      font: var(--cometchat-font-heading4-medium);
      color: var(--cometchat-text-color-secondary);
    }

    .cometchat-search__message-list-item-title-role {
      font: var(--cometchat-font-heading4-medium);
      color: var(--cometchat-text-color-highlight);
      text-decoration: underline;
    }
    ```
  </Tab>
</Tabs>

#### messageSubtitleView

Replace the message subtitle text.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatSearch } from "@cometchat/chat-uikit-react";

    function SearchCustomMessageSubtitle() {
      const getMessageSubtitleView = (message: CometChat.BaseMessage) => (
        <div className="cometchat-search__message-list-item-subtitle">
          <div className="cometchat-search__message-list-item-subtitle-sender">
            {message.getSender()?.getName()}:
          </div>
          <div className="cometchat-search__message-list-item-subtitle-text">
            {message instanceof CometChat.TextMessage
              ? (message as CometChat.TextMessage).getText()
              : message.getType()}
          </div>
        </div>
      );

      return <CometChatSearch messageSubtitleView={getMessageSubtitleView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-search__message-list-item-subtitle {
      background: var(--cometchat-extended-primary-color-100);
      padding: var(--cometchat-padding-1);
      display: flex;
      justify-content: flex-start;
      gap: var(--cometchat-padding-2);
      width: 100%;
    }

    .cometchat-search__message-list-item-subtitle-sender {
      color: var(--cometchat-text-color-highlight);
      font: var(--cometchat-font-body-regular);
    }

    .cometchat-search__message-list-item-subtitle-text {
      color: var(--cometchat-text-color-secondary);
      font: var(--cometchat-font-body-regular);
    }
    ```
  </Tab>
</Tabs>

### Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide that section:

```tsx theme={null}
<CometChatSearch.Root onConversationClicked={handleClick}>
  {/* Only show conversations — no messages section */}
  <CometChatSearch.ConversationsList />
</CometChatSearch.Root>
```

Available sub-components:

| Sub-component       | Description                    | Props                       | Flat API equivalent |
| ------------------- | ------------------------------ | --------------------------- | ------------------- |
| `Root`              | Context provider and container | All Root props + `children` | —                   |
| `ConversationsList` | Conversation results section   | `className`                 | —                   |
| `MessagesList`      | Message results section        | `className`                 | —                   |

<Note>
  The flat API and Root accept the same props — all view slots are directly on Root. There are no separate convenience props.
</Note>

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-search {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-search__filters {
  gap: 8px;
}
```

***

## Props

All props are optional.

<Note>
  The flat API and Root accept the same props — all view slots are directly on Root. There are no separate convenience props.
</Note>

***

### searchIn

Which result sections to show. Empty array (default) shows both conversations and messages.

|         |                          |
| ------- | ------------------------ |
| Type    | `CometChatSearchScope[]` |
| Default | `[]` (both)              |

***

### searchFilters

Filter chips to display in the filter bar.

|         |                           |
| ------- | ------------------------- |
| Type    | `CometChatSearchFilter[]` |
| Default | All available filters     |

***

### initialSearchFilter

Pre-select a filter chip on mount.

|         |                         |
| ------- | ----------------------- |
| Type    | `CometChatSearchFilter` |
| Default | `undefined`             |

***

### defaultSearchText

Pre-populate the search input with this text.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### uid

Scope search to a specific user's conversation. When set, conversation filters are hidden.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### guid

Scope search to a specific group's conversation. When set, conversation filters are hidden.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### hideBackButton

Hide the back button in the header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideUserStatus

Hide user online/offline status indicators in conversation results.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideGroupType

Hide group type badge in conversation results.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideReceipts

Hide message delivery/read receipts in conversation results.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### textFormatters

Text formatters applied to conversation subtitles.

|         |                            |
| ------- | -------------------------- |
| Type    | `CometChatTextFormatter[]` |
| Default | `undefined`                |

***

### lastMessageDateTimeFormat

Custom date/time format for the last message timestamp in conversation results.

|         |                                                    |
| ------- | -------------------------------------------------- |
| Type    | `CometChatDateFormatConfig`                        |
| Default | `DD/MM/YYYY` for all date ranges in search context |

***

### messageSentAtDateTimeFormat

Custom date/time format for the sent-at timestamp in message results.

|         |                             |
| ------- | --------------------------- |
| Type    | `CometChatDateFormatConfig` |
| Default | `undefined`                 |

***

### conversationsRequestBuilder

Custom request builder for conversation search. Pass the builder instance — not the result of `.build()`.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `CometChat.ConversationsRequestBuilder` |
| Default | SDK default                             |

***

### messagesRequestBuilder

Custom request builder for message search. Pass the builder instance — not the result of `.build()`.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `CometChat.MessagesRequestBuilder` |
| Default | SDK default                        |

***

### conversationOptions

Function that returns context menu options for each conversation result item.

|         |                                                                                 |
| ------- | ------------------------------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => CometChatSearchConversationOption[]` |
| Default | `undefined`                                                                     |

```tsx theme={null}
<CometChatSearch
  conversationOptions={(conversation) => [
    {
      id: "open",
      title: "Open",
      onClick: (conv) => navigateToConversation(conv),
    },
  ]}
/>
```

***

### onBack

Callback when the back button is clicked.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onConversationClicked

Callback when a conversation result item is clicked. The event includes the search keyword.

|         |                                                          |
| ------- | -------------------------------------------------------- |
| Type    | `(event: CometChatSearchConversationClickEvent) => void` |
| Default | `undefined`                                              |

***

### onMessageClicked

Callback when a message result item is clicked. The event includes the search keyword.

|         |                                                     |
| ------- | --------------------------------------------------- |
| Type    | `(event: CometChatSearchMessageClickEvent) => void` |
| Default | `undefined`                                         |

***

### onError

Callback when an SDK error occurs during search.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `null`                                                    |

***

## CSS Selectors

| Target                | Selector                                   |
| --------------------- | ------------------------------------------ |
| Root container        | `.cometchat-search`                        |
| Header                | `.cometchat-search__header`                |
| Search bar            | `.cometchat-search__search-bar`            |
| Filter chips          | `.cometchat-search__filters`               |
| Results container     | `.cometchat-search__results`               |
| Conversations section | `.cometchat-search__conversations-section` |
| Messages section      | `.cometchat-search__messages-section`      |
| Initial state         | `.cometchat-search__initial-state`         |
| Empty state           | `.cometchat-search__empty-state`           |
| Error state           | `.cometchat-search__error-state`           |
| Loading state         | `.cometchat-search__loading-state`         |

***

## Next Steps

<CardGroup>
  <Card title="Conversations" icon="comments" href="/ui-kit/react/components/conversations">
    Display the conversation list alongside search
  </Card>

  <Card title="Message List" icon="list" href="/ui-kit/react/components/message-list">
    Navigate to matched messages in the message list
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Sticker Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/sticker-bubble

A self-extracting bubble that renders a sticker image from a sticker custom message.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatStickerBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatStickerBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Self-extracting sticker bubble. Extracts the sticker image URL and name from the message metadata.",
    "cssRootClass": ".cometchat-sticker-bubble",
    "selfExtracting": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.CustomMessage", "required": true, "note": "The sticker custom message; drives extraction of the image URL and name." },
        "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." },
        "className": { "type": "string" }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatStickerBubble` renders a sticker. It is **self-extracting**: pass the SDK custom `message` and the bubble extracts the sticker image URL and name from its metadata, so it works standalone.

<Info>
  **Live Preview** — interact with the sticker bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble--sticker-message)
</Info>

<iframe title="CometChat Sticker Bubble — Default" />

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatStickerBubble } from "@cometchat/chat-uikit-react";

function StickerMessage({ message }: { message: CometChat.CustomMessage }) {
  return <CometChatStickerBubble message={message} />;
}
```

***

## Props

### message

The sticker custom message. The bubble extracts the image URL and name from its metadata. **Required.**

|          |                           |
| -------- | ------------------------- |
| Type     | `CometChat.CustomMessage` |
| Required | Yes                       |

***

### alignment

Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user.

|         |                     |
| ------- | ------------------- |
| Type    | `"left" \| "right"` |
| Default | derived             |

***

### className

Additional CSS class applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target              | Selector                                                                      |
| ------------------- | ----------------------------------------------------------------------------- |
| Root                | `.cometchat-sticker-bubble`                                                   |
| Incoming / outgoing | `.cometchat-sticker-bubble--incoming` / `.cometchat-sticker-bubble--outgoing` |
| Sticker image       | `.cometchat-sticker-bubble__image`                                            |

***

## Next Steps

<CardGroup>
  <Card title="Stickers Plugin" icon="face-smile" href="/ui-kit/react/plugins/overview#built-in-plugins">
    Plugin behavior, keyboard, and conversation preview
  </Card>

  <Card title="Poll Bubble" icon="square-poll-vertical" href="/ui-kit/react/components/poll-bubble">
    Render poll messages
  </Card>

  <Card title="Message Bubble" icon="comment" href="/ui-kit/react/components/message-bubble">
    The wrapper that hosts bubble content
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Text Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/text-bubble

A self-extracting bubble that renders text messages with markdown, mentions, clickable URLs, link previews, and read-more truncation.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatTextBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatTextBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Self-extracting text bubble. Renders message text through the formatter pipeline (markdown, mentions, URLs), with optional read-more truncation.",
    "cssRootClass": ".cometchat-text-bubble",
    "selfExtracting": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.BaseMessage", "note": "When set (and text omitted), the bubble extracts content via message.getText() and configures mention formatting." },
        "text": { "type": "string", "note": "Explicit text override (used for media captions). At least one of text / message should be set." },
        "isSentByMe": { "type": "boolean", "default": true },
        "textFormatters": { "type": "CometChatTextFormatter[]" },
        "disableTruncation": { "type": "boolean", "default": false },
        "className": { "type": "string" }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatTextBubble` renders a text message. It is **self-extracting**: pass the SDK `message` and the bubble reads the text via `message.getText()` and configures mention formatting from the message itself, so it works standalone. It also accepts an explicit `text` override, which is how media bubbles render their captions through it.

Text is run through the formatter pipeline — markdown (`**bold**`, `_italic_`, `~~strike~~`, `` `code` ``, lists, blockquotes), `<@uid:xxx>` mentions resolved to styled chips, and bare URLs converted to clickable links. Long messages are truncated with a "Read more" toggle unless `disableTruncation` is set.

<Info>
  **Live Preview** — interact with the text bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble-text--default)
</Info>

<iframe title="CometChat Text Bubble — Default" />

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatTextBubble } from "@cometchat/chat-uikit-react";

function TextMessage({ message }: { message: CometChat.BaseMessage }) {
  return <CometChatTextBubble message={message} />;
}
```

Render explicit text (e.g. a caption) instead of extracting from a message:

```tsx theme={null}
<CometChatTextBubble text="Photo caption" isSentByMe />
```

***

## Props

### message

The message to render. When `text` is omitted, the bubble extracts the content and mention formatting from it.

|         |                         |
| ------- | ----------------------- |
| Type    | `CometChat.BaseMessage` |
| Default | `undefined`             |

***

### text

Explicit text to display. Overrides `message.getText()` when provided.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### isSentByMe

Whether the message was sent by the logged-in user (affects styling).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### textFormatters

Text formatters to apply (mentions, URLs, custom syntax).

|         |                            |
| ------- | -------------------------- |
| Type    | `CometChatTextFormatter[]` |
| Default | `undefined`                |

***

### disableTruncation

Disable the read-more / show-less truncation.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### className

Additional CSS class applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target              | Selector                                                                |
| ------------------- | ----------------------------------------------------------------------- |
| Root                | `.cometchat-text-bubble`                                                |
| Incoming / outgoing | `.cometchat-text-bubble--incoming` / `.cometchat-text-bubble--outgoing` |
| Single emoji        | `.cometchat-text-bubble--single-emoji`                                  |
| Text content        | `.cometchat-text-bubble__text`                                          |
| Mention chip        | `.cometchat-text-bubble__mention`                                       |
| Link                | `.cometchat-link`                                                       |
| Read-more button    | `.cometchat-text-bubble__read-more-button`                              |
| Link preview        | `.cometchat-text-bubble__link-preview`                                  |

***

## Next Steps

<CardGroup>
  <Card title="Text Plugin" icon="font" href="/ui-kit/react/plugins/overview#built-in-plugins">
    Plugin behavior, context menu, and conversation preview
  </Card>

  <Card title="Text Formatters" icon="code" href="/ui-kit/react/plugins/text-formatters">
    Build custom mention / URL / markdown formatters
  </Card>

  <Card title="Message Bubble" icon="comment" href="/ui-kit/react/components/message-bubble">
    The wrapper that hosts bubble content
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Thread Header
Source: https://www.cometchat.com/docs/ui-kit/react/components/thread-header

Displays the parent message bubble and reply count for threaded conversations.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatThreadHeader",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatThreadHeader } from \"@cometchat/chat-uikit-react\";",
    "description": "Displays the parent message bubble and reply count for threaded conversations.",
    "cssRootClass": ".cometchat-thread-header",
    "primaryOutput": {
      "prop": "onClose",
      "type": "() => void"
    },
    "props": {
      "data": {
        "parentMessage": {
          "type": "CometChat.BaseMessage",
          "required": true,
          "note": "The parent message of the thread"
        },
        "separatorDateTimeFormat": {
          "type": "CometChatDateFormatConfig",
          "default": "undefined"
        },
        "messageSentAtDateTimeFormat": {
          "type": "CometChatDateFormatConfig",
          "default": "undefined"
        }
      },
      "visibility": {
        "hideReceipts": { "type": "boolean", "default": false },
        "hideDate": { "type": "boolean", "default": false },
        "hideReplyCount": { "type": "boolean", "default": false },
        "showScrollbar": { "type": "boolean", "default": false }
      },
      "callbacks": {
        "onClose": "() => void",
        "onSubtitleClicked": "() => void",
        "onParentDeleted": "() => void",
        "onError": "((error: CometChat.CometChatException) => void) | null"
      },
      "viewSlots": {
        "headerView": "ReactNode",
        "messageBubbleView": "ReactNode",
        "subtitleView": "ReactNode"
      }
    },
    "events": {
      "emitted": [],
      "received": [
        {
          "name": "ui:message/sent",
          "payload": "{ message, status: 'success' }",
          "description": "Increments reply count when current user sends a reply"
        },
        {
          "name": "ui:compose/edit",
          "payload": "{ message, status: 'success' }",
          "description": "Updates parent bubble when edited"
        },
        {
          "name": "ui:message/deleted",
          "payload": "{ message }",
          "description": "Triggers onParentDeleted"
        }
      ]
    },
    "sdkListeners": [
      "onTextMessageReceived",
      "onMediaMessageReceived",
      "onCustomMessageReceived",
      "onInteractiveMessageReceived",
      "onMessageEdited",
      "onMessageDeleted"
    ],
    "types": {
      "CometChatDateFormatConfig": {
        "today": "string | undefined",
        "yesterday": "string | undefined",
        "lastWeek": "string | undefined",
        "otherDays": "string | undefined",
        "relativeTime": {
          "minute": "string | undefined",
          "minutes": "string | undefined",
          "hour": "string | undefined",
          "hours": "string | undefined"
        }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatThreadHeader` displays the parent message bubble and reply count for threaded conversations. It renders a top bar with the thread title, sender name, and close button, followed by the parent message bubble and a real-time reply count divider. Wire it above a `CometChatMessageList` (with `parentMessageId`) and `CometChatMessageComposer` to build a complete thread view.

<Info>
  **Live Preview** — interact with the default thread header.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-messages-thread-header--default)
</Info>

<iframe title="CometChat Thread Header — Default" />

The component handles:

* Rendering the parent message as a bubble
* Real-time reply count updates via SDK listeners
* Parent message edit/delete detection
* Close button and keyboard (Escape) dismissal

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatThreadHeader } from "@cometchat/chat-uikit-react";

function ThreadPanel({
  parentMessage,
  onClose,
}: {
  parentMessage: CometChat.BaseMessage;
  onClose: () => void;
}) {
  return (
    <CometChatThreadHeader
      parentMessage={parentMessage}
      onClose={onClose}
    />
  );
}
```

### Compound Composition

```tsx theme={null}
import { CometChatThreadHeader } from "@cometchat/chat-uikit-react";

function ThreadPanel({
  parentMessage,
  onClose,
}: {
  parentMessage: CometChat.BaseMessage;
  onClose: () => void;
}) {
  return (
    <CometChatThreadHeader.Root parentMessage={parentMessage} onClose={onClose}>
      <CometChatThreadHeader.TopBar>
        <CometChatThreadHeader.Title />
        <CometChatThreadHeader.SenderName />
        <CometChatThreadHeader.CloseButton />
      </CometChatThreadHeader.TopBar>
      <CometChatThreadHeader.ParentBubble />
      <CometChatThreadHeader.ReplyCount />
    </CometChatThreadHeader.Root>
  );
}
```

### Full Layout Example

```tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatThreadHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

function ThreadView({
  parentMessage,
  user,
  group,
  onClose,
}: {
  parentMessage: CometChat.BaseMessage;
  user?: CometChat.User;
  group?: CometChat.Group;
  onClose: () => void;
}) {
  const parentMessageId = parentMessage.getId();

  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
      <CometChatThreadHeader
        parentMessage={parentMessage}
        onClose={onClose}
        onParentDeleted={onClose}
      />
      <CometChatMessageList
        user={user}
        group={group}
        parentMessageId={parentMessageId}
      />
      <CometChatMessageComposer
        user={user}
        group={group}
        parentMessageId={parentMessageId}
      />
    </div>
  );
}
```

***

## Filtering

This component does not support request builders or filtering. It renders a single parent message and its reply count.

***

## Actions and Events

### Callback Props

| Prop                | Signature                                                 | Fires when                                      |
| ------------------- | --------------------------------------------------------- | ----------------------------------------------- |
| `onClose`           | `() => void`                                              | Close button clicked or Escape pressed          |
| `onSubtitleClicked` | `() => void`                                              | Sender name / subtitle is clicked               |
| `onParentDeleted`   | `() => void`                                              | Parent message is deleted (thread should close) |
| `onError`           | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs                                |

### Events Emitted

This component does not emit UI events.

### Events Received

UI events this component subscribes to (published by other components):

| Event                | Payload                          | Behavior                                                              |
| -------------------- | -------------------------------- | --------------------------------------------------------------------- |
| `ui:message/sent`    | `{ message, status: 'success' }` | Increments reply count when current user sends a reply in this thread |
| `ui:compose/edit`    | `{ message, status: 'success' }` | Updates the parent bubble when the parent message is edited           |
| `ui:message/deleted` | `{ message }`                    | Triggers `onParentDeleted` when the parent message is deleted         |

### SDK Listeners (Automatic)

These SDK listeners are attached internally. The component updates its state automatically — no manual subscription needed:

* Message listeners: `onTextMessageReceived`, `onMediaMessageReceived`, `onCustomMessageReceived`, `onInteractiveMessageReceived` — increments reply count when other users send replies
* Edits: `onMessageEdited` — updates parent bubble when edited by another user
* Deletes: `onMessageDeleted` — triggers `onParentDeleted` when deleted by another user

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatThreadHeader
  parentMessage={parentMessage}
  onClose={onClose}
  headerView={<MyCustomTopBar />}
  messageBubbleView={<MyCustomBubble message={parentMessage} />}
  subtitleView={<span>Custom subtitle</span>}
/>
```

| Slot                | Type        | Replaces                                       |
| ------------------- | ----------- | ---------------------------------------------- |
| `headerView`        | `ReactNode` | Entire top bar (title + sender + close button) |
| `messageBubbleView` | `ReactNode` | Parent message bubble                          |
| `subtitleView`      | `ReactNode` | Subtitle below the title                       |

#### messageBubbleView

Replace the parent message bubble with a custom view.

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatThreadHeader } from "@cometchat/chat-uikit-react";

function CustomBubbleThread({ parentMessage }: { parentMessage: CometChat.BaseMessage }) {
  return (
    <CometChatThreadHeader
      parentMessage={parentMessage}
      messageBubbleView={<div className="custom-bubble">Custom bubble view</div>}
    />
  );
}
```

### Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

```tsx theme={null}
<CometChatThreadHeader.Root parentMessage={parentMessage} onClose={onClose}>
  <CometChatThreadHeader.TopBar>
    <CometChatThreadHeader.Title />
    <CometChatThreadHeader.CloseButton />
    {/* No SenderName — it won't render */}
  </CometChatThreadHeader.TopBar>
  <CometChatThreadHeader.ParentBubble />
  {/* No ReplyCount — it won't render */}
</CometChatThreadHeader.Root>
```

Available sub-components:

| Sub-component  | Description                    | Props                                                            | Flat API equivalent |
| -------------- | ------------------------------ | ---------------------------------------------------------------- | ------------------- |
| `Root`         | Context provider and container | All Root props + `children`                                      | —                   |
| `TopBar`       | Top bar container              | `children`, `className`                                          | `headerView`        |
| `Title`        | Thread title text              | `title`, `className`                                             | —                   |
| `SenderName`   | Parent message sender          | `className`                                                      | —                   |
| `CloseButton`  | Close button                   | `className`                                                      | —                   |
| `ParentBubble` | Parent message bubble          | `disableInteraction`, `messageSentAtDateTimeFormat`, `className` | `messageBubbleView` |
| `ReplyCount`   | Reply count with divider       | `showDivider`, `className`                                       | —                   |

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-thread-header {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-thread-header__top-bar {
  border-bottom: 1px solid var(--cometchat-border-color-light);
}
```

***

## Props

`parentMessage` is **required**. All other props are optional.

<Note>
  View slot props (`headerView`, `messageBubbleView`, `subtitleView`) are convenience props available only on the flat API. In compound composition mode, use the corresponding sub-components directly.
</Note>

***

### parentMessage

The parent message of the thread. Required.

|          |                         |
| -------- | ----------------------- |
| Type     | `CometChat.BaseMessage` |
| Required | Yes                     |

***

### hideReceipts

Hide message delivery/read receipts on the parent bubble.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideDate

Hide the date chip shown above the parent bubble.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideReplyCount

Hide the reply count section below the parent bubble.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### separatorDateTimeFormat

Custom date/time format for the date chip shown above the parent bubble.

|         |                             |
| ------- | --------------------------- |
| Type    | `CometChatDateFormatConfig` |
| Default | `undefined`                 |

***

### messageSentAtDateTimeFormat

Custom date/time format for the sent-at timestamp on the parent message bubble.

|         |                             |
| ------- | --------------------------- |
| Type    | `CometChatDateFormatConfig` |
| Default | `undefined`                 |

***

### showScrollbar

Show the native scrollbar on the bubble wrapper area.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### onClose

Callback when the close button is clicked or Escape is pressed.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onSubtitleClicked

Callback when the sender name / subtitle is clicked (navigate to parent in main list).

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onParentDeleted

Callback when the parent message is deleted (thread should close).

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onError

Callback when an SDK error occurs.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `null`                                                    |

***

### headerView

Custom content to replace the entire top bar (title + sender name + close button).

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

### messageBubbleView

Custom content to replace the parent message bubble rendering.

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

### subtitleView

Custom subtitle view below the title.

|         |             |
| ------- | ----------- |
| Type    | `ReactNode` |
| Default | `undefined` |

***

## CSS Selectors

| Target              | Selector                                         |
| ------------------- | ------------------------------------------------ |
| Root container      | `.cometchat-thread-header`                       |
| Top bar             | `.cometchat-thread-header__top-bar`              |
| Content area        | `.cometchat-thread-header__content`              |
| Title               | `.cometchat-thread-header__title`                |
| Sender name         | `.cometchat-thread-header__sender-name`          |
| Close button        | `.cometchat-thread-header__close-button-wrapper` |
| Bubble wrapper      | `.cometchat-thread-header__bubble-wrapper`       |
| Body timestamp      | `.cometchat-thread-header__body-timestamp`       |
| Reply count         | `.cometchat-thread-header__reply-count`          |
| Reply count divider | `.cometchat-thread-header__reply-count-divider`  |

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="comments" href="/ui-kit/react/components/message-list">
    Display threaded replies below the parent message
  </Card>

  <Card title="Message Composer" icon="keyboard" href="/ui-kit/react/components/message-composer">
    Compose replies in the thread
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Users
Source: https://www.cometchat.com/docs/ui-kit/react/components/users

Searchable, scrollable list of users with selection support and real-time presence updates.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatUsers",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatUsers } from \"@cometchat/chat-uikit-react\";",
    "description": "Searchable, scrollable list of users with selection support and real-time presence updates.",
    "cssRootClass": ".cometchat-users",
    "primaryOutput": {
      "prop": "onItemClick",
      "type": "(user: CometChat.User) => void"
    },
    "props": {
      "data": {
        "usersRequestBuilder": {
          "type": "CometChat.UsersRequestBuilder",
          "default": "SDK default (30 per page)",
          "note": "Pass the builder instance, not the result of .build()"
        },
        "searchRequestBuilder": {
          "type": "CometChat.UsersRequestBuilder",
          "default": "undefined"
        },
        "searchKeyword": {
          "type": "string",
          "default": "undefined"
        },
        "activeUser": {
          "type": "CometChat.User",
          "default": "undefined"
        },
        "sectionHeaderKey": {
          "type": "keyof CometChat.User",
          "default": "undefined"
        }
      },
      "callbacks": {
        "onItemClick": "(user: CometChat.User) => void",
        "onSelect": "(user: CometChat.User, selected: boolean) => void",
        "onError": "((error: CometChat.CometChatException) => void) | null",
        "onEmpty": "() => void"
      },
      "visibility": {
        "hideUserStatus": { "type": "boolean", "default": false },
        "hideSearch": { "type": "boolean", "default": false },
        "showSectionHeader": { "type": "boolean", "default": true },
        "showSelectedUsersPreview": { "type": "boolean", "default": false },
        "showScrollbar": { "type": "boolean", "default": false }
      },
      "selection": {
        "selectionMode": {
          "type": "CometChatUsersSelectionMode",
          "values": ["'none'", "'single'", "'multiple'"],
          "default": "'none'"
        }
      },
      "viewSlots": {
        "itemView": "(user: CometChat.User) => ReactNode",
        "leadingView": "(user: CometChat.User) => ReactNode",
        "titleView": "(user: CometChat.User) => ReactNode",
        "subtitleView": "(user: CometChat.User) => ReactNode",
        "trailingView": "(user: CometChat.User) => ReactNode",
        "headerView": "ReactNode",
        "loadingView": "ReactNode",
        "emptyView": "ReactNode",
        "errorView": "ReactNode",
        "options": "(user: CometChat.User) => CometChatUserOption[]"
      }
    },
    "events": [],
    "eventsReceived": [
      {
        "name": "ui:user/blocked",
        "payload": "{ user: CometChat.User }",
        "description": "Updates user in the list (shows blocked state)"
      },
      {
        "name": "ui:user/unblocked",
        "payload": "{ user: CometChat.User }",
        "description": "Updates user in the list (removes blocked state)"
      }
    ],
    "sdkListeners": [
      "onUserOnline",
      "onUserOffline"
    ],
    "types": {
      "CometChatUserOption": {
        "id": "string",
        "title": "string",
        "iconURL": "string | undefined",
        "onClick": "(user: CometChat.User) => void"
      },
      "CometChatUsersSelectionMode": "'none' | 'single' | 'multiple'"
    }
  }
  ```
</Accordion>

## Overview

`CometChatUsers` is a list component that renders all available users in the app. It emits the selected `CometChat.User` via `onItemClick`. Wire it to `CometChatMessages` or use it as a user picker in flows like "new conversation" or "add members to group."

<Info>
  **Live Preview** — interact with the default users list.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-users-cometchat-users--default)
</Info>

<iframe title="CometChat Users — Default" />

The component handles:

* Paginated fetching with infinite scroll
* Real-time presence updates (online/offline)
* Search filtering
* Alphabetical section headers
* Selection mode (single/multiple) with optional preview chips

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react";

function UserPicker() {
  return (
    <CometChatUsers
      onItemClick={(user) => {
        console.log("Selected user:", user.getName());
      }}
    />
  );
}
```

### Compound Composition

```tsx theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react";

function UserPicker() {
  return (
    <CometChatUsers.Root onItemClick={handleClick}>
      <CometChatUsers.Header title="Users" />
      <CometChatUsers.SearchBar placeholder="Search users..." />
      <CometChatUsers.LoadingState />
      <CometChatUsers.ErrorState />
      <CometChatUsers.EmptyState>
        <p>No users found.</p>
      </CometChatUsers.EmptyState>
      <CometChatUsers.List />
    </CometChatUsers.Root>
  );
}
```

### New Conversation Example

```tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatUsers,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

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

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        <CometChatUsers onItemClick={(u) => setUser(u)} activeUser={user} />
      </div>
      {user && (
        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
          <CometChatMessageHeader user={user} />
          <CometChatMessageList user={user} />
          <CometChatMessageComposer user={user} />
        </div>
      )}
    </div>
  );
}
```

***

## Filtering

Pass a `CometChat.UsersRequestBuilder` to `usersRequestBuilder` to control which users load. Pass the builder instance — not the result of `.build()`. Refer to [UsersRequestBuilder](/docs/sdk/javascript/retrieve-users) for the full builder API.

```tsx theme={null}
<CometChatUsers
  usersRequestBuilder={
    new CometChat.UsersRequestBuilder()
      .setLimit(15)
      .setStatus("online")
  }
/>
```

### Search

The component includes a built-in search bar. When the user types, it fetches matching users from the server. For custom search behavior, pass a `searchRequestBuilder`:

```tsx theme={null}
<CometChatUsers
  searchRequestBuilder={
    new CometChat.UsersRequestBuilder().setLimit(30).setSearchKeyword("")
  }
/>
```

### Filter Recipes

| Recipe            | Code                                                         |
| ----------------- | ------------------------------------------------------------ |
| Only online users | `new CometChat.UsersRequestBuilder().setStatus("online")`    |
| Only friends      | `new CometChat.UsersRequestBuilder().friendsOnly(true)`      |
| Limit page size   | `new CometChat.UsersRequestBuilder().setLimit(10)`           |
| By role           | `new CometChat.UsersRequestBuilder().setRoles(["admin"])`    |
| With tags         | `new CometChat.UsersRequestBuilder().setTags(["vip"])`       |
| Hide blocked      | `new CometChat.UsersRequestBuilder().hideBlockedUsers(true)` |

***

## Actions and Events

### Callback Props

| Prop          | Signature                                                 | Fires when                                |
| ------------- | --------------------------------------------------------- | ----------------------------------------- |
| `onItemClick` | `(user: CometChat.User) => void`                          | User clicks a user item                   |
| `onSelect`    | `(user: CometChat.User, selected: boolean) => void`       | User selected/deselected (selection mode) |
| `onError`     | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs                          |
| `onEmpty`     | `() => void`                                              | List is empty after initial fetch         |

### Events Emitted

This component does not emit any UI events.

### Events Received

UI events this component subscribes to (published by other components):

| Event               | Payload    | Behavior                                         |
| ------------------- | ---------- | ------------------------------------------------ |
| `ui:user/blocked`   | `{ user }` | Updates user in the list (shows blocked state)   |
| `ui:user/unblocked` | `{ user }` | Updates user in the list (removes blocked state) |

### SDK Listeners (Automatic)

These SDK listeners are attached internally. The component updates its state automatically — no manual subscription needed:

* Presence: `onUserOnline`, `onUserOffline`

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatUsers
  headerView={<MyCustomHeader />}
  itemView={(user) => <MyCustomUserItem user={user} />}
  emptyView={<EmptyState />}
  loadingView={<Skeleton />}
  errorView={<ErrorBanner />}
/>
```

| Slot           | Signature             | Replaces         |
| -------------- | --------------------- | ---------------- |
| `itemView`     | `(user) => ReactNode` | Entire user row  |
| `leadingView`  | `(user) => ReactNode` | Avatar section   |
| `titleView`    | `(user) => ReactNode` | User name        |
| `subtitleView` | `(user) => ReactNode` | Status text      |
| `trailingView` | `(user) => ReactNode` | Trailing content |
| `headerView`   | `ReactNode`           | Header area      |
| `loadingView`  | `ReactNode`           | Loading shimmer  |
| `emptyView`    | `ReactNode`           | Empty state      |
| `errorView`    | `ReactNode`           | Error state      |

#### itemView

Replace the entire list item row.

Default:

<Frame>
  <img />
</Frame>

Customized:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatUsers } from "@cometchat/chat-uikit-react";

    function UsersDemo() {
      const getItemView = (user: CometChat.User) => {
        const status = user.getStatus();

        return (
          <div
            className={`cometchat-users__list-item cometchat-users__list-item-${status}
              ${status === "online" ? "cometchat-users__list-item-active" : ""}
              `}
          >
            <span>{user.getName()}</span>
            <span>{user.getStatus()}</span>
          </div>
        );
      };

      return <CometChatUsers itemView={getItemView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-users__list-item {
      display: flex;
      align-items: center;
      gap: 8px;
      padding: 8px 16px;
    }

    .cometchat-users__list-item-active {
      background: rgba(9, 194, 111, 0.1);
    }
    ```
  </Tab>
</Tabs>

#### leadingView

Replace the avatar / left section.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatUsers, CometChatAvatar } from "@cometchat/chat-uikit-react";

    function LeadingViewUsers() {
      const getLeadingView = (user: CometChat.User) => {
        return (
          <div className="users__leading-view">
            <CometChatAvatar.Root image={user.getAvatar()} name={user.getName()}>
              <CometChatAvatar.Image />
              <CometChatAvatar.Initials />
            </CometChatAvatar.Root>
          </div>
        );
      };

      return <CometChatUsers leadingView={getLeadingView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .cometchat-users .users__leading-view .cometchat-avatar {
      border-radius: 8px;
      height: 48px;
      width: 48px;
    }

    .users__leading-view {
      position: relative;
    }
    ```
  </Tab>
</Tabs>

#### titleView

Replace the name / title text. Role badge inline example.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatUsers } from "@cometchat/chat-uikit-react";

    function TitleViewUsers() {
      const getTitleView = (user: CometChat.User) => {
        return (
          <div className="users__title-view">
            <span className="users__title-view-name">{user.getName()}</span>
            <span className="users__title-view-type">{user.getRole()}</span>
          </div>
        );
      };

      return <CometChatUsers titleView={getTitleView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .users__title-view {
      display: flex;
      align-items: center;
      gap: 4px;
      align-self: stretch;
    }

    .users__title-view-name {
      overflow: hidden;
      color: #141414;
      text-overflow: ellipsis;
      font: 500 16px Roboto;
    }

    .users__title-view-type {
      color: #fff;
      font: 600 8px Roboto;
      display: flex;
      height: 15px;
      padding: 1px 3px;
      justify-content: center;
      align-items: center;
      border-radius: 7px;
      background: #09c26f;
    }
    ```
  </Tab>
</Tabs>

#### subtitleView

Replace the subtitle text for each user.

Default:

<Frame>
  <img />
</Frame>

Customized:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatUsers } from "@cometchat/chat-uikit-react";

    function SubtitleViewUsers() {
      const getSubtitleView = (user: CometChat.User) => {
        return (
          <div className="users-subtitle">
            {user.getStatusMessage() || user.getStatus()}
          </div>
        );
      };

      return <CometChatUsers subtitleView={getSubtitleView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .users-subtitle {
      overflow: hidden;
      color: #727272;
      text-overflow: ellipsis;
      white-space: nowrap;
      font: 400 14px Roboto;
    }
    ```
  </Tab>
</Tabs>

#### trailingView

Replace the right section.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatUsers } from "@cometchat/chat-uikit-react";

    function TrailingViewUsers() {
      const getTrailingView = (user: CometChat.User) => {
        const tag = user.getTags()?.[0] ?? "";
        return (
          <div className="users__trailing-view">
            <span className="users__trailing-view-text">{tag}</span>
          </div>
        );
      };

      return <CometChatUsers trailingView={getTrailingView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css theme={null}
    .users__trailing-view {
      display: flex;
      width: 33px;
      padding: 5px 3px;
      flex-direction: column;
      justify-content: center;
      align-items: center;
      gap: 3px;
      border-radius: 4px;
      background: #6852d6;
    }

    .users__trailing-view-text {
      font: 600 8px Inter;
      color: white;
    }
    ```
  </Tab>
</Tabs>

### Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

```tsx theme={null}
<CometChatUsers.Root onItemClick={handleClick}>
  {/* No Header or SearchBar — they won't render */}
  <CometChatUsers.List />
</CometChatUsers.Root>
```

Available sub-components:

| Sub-component     | Description                    | Props                                                      | Flat API equivalent |
| ----------------- | ------------------------------ | ---------------------------------------------------------- | ------------------- |
| `Root`            | Context provider and container | All Root props + `children`                                | —                   |
| `List`            | Scrollable user list           | `itemView`                                                 | `itemView`          |
| `Item`            | Individual user row            | `leadingView`, `titleView`, `subtitleView`, `trailingView` | Per-item view props |
| `Header`          | Header area                    | `title`, `children`                                        | `headerView`        |
| `SearchBar`       | Search input                   | `placeholder`                                              | —                   |
| `SectionHeader`   | Alphabetical section header    | `letter`                                                   | —                   |
| `EmptyState`      | Empty state                    | `children`                                                 | `emptyView`         |
| `ErrorState`      | Error state                    | `children`                                                 | `errorView`         |
| `LoadingState`    | Loading shimmer                | `children`                                                 | `loadingView`       |
| `SelectedPreview` | Selected users chip bar        | `chipView`                                                 | —                   |

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-users {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-users__item--active {
  background: var(--cometchat-primary-color);
}
```

***

## Props

All props are optional.

<Note>
  View slot props (`headerView`, `loadingView`, `emptyView`, `errorView`, `itemView`, `leadingView`, `titleView`, `subtitleView`, `trailingView`) are convenience props available only on the flat API. The search input is the `SearchBar` sub-component (with a `placeholder` prop), not a view slot. In compound composition mode, use the corresponding sub-components directly.
</Note>

***

### usersRequestBuilder

Custom request builder for fetching users. Controls pagination, filtering, and sorting.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `CometChat.UsersRequestBuilder` |
| Default | SDK default (limit 30)          |

***

### searchRequestBuilder

Custom request builder used specifically when the user searches. Separate from the main builder.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `CometChat.UsersRequestBuilder` |
| Default | `undefined`                     |

***

### searchKeyword

Initial search keyword to pre-filter users on mount.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### hideUserStatus

Hide the online/offline status indicator on user avatars.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideSearch

Hide the search bar entirely.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showSectionHeader

Show alphabetical section headers (A, B, C…) in the user list.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### showSelectedUsersPreview

Show a preview strip of selected user chips above the list (useful in multi-select mode).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showScrollbar

Show the native scrollbar on the user list.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### selectionMode

Enable selection mode for single or multi-select operations.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `'none' \| 'single' \| 'multiple'` |
| Default | `'none'`                           |

***

### activeUser

The currently active/highlighted user. The matching item receives an active visual state.

|         |                  |
| ------- | ---------------- |
| Type    | `CometChat.User` |
| Default | `undefined`      |

***

### sectionHeaderKey

The property of `CometChat.User` used to group users into sections (e.g., first letter of name).

|         |                        |
| ------- | ---------------------- |
| Type    | `keyof CometChat.User` |
| Default | `undefined`            |

***

### options

Function that returns context menu options for each user item (shown on hover/swipe).

|         |                                                   |
| ------- | ------------------------------------------------- |
| Type    | `(user: CometChat.User) => CometChatUserOption[]` |
| Default | `undefined`                                       |

```tsx theme={null}
<CometChatUsers
  options={(user) => [
    {
      id: "block",
      title: "Block User",
      iconURL: blockIcon,
      onClick: (u) => blockUser(u),
    },
    {
      id: "info",
      title: "View Profile",
      iconURL: infoIcon,
      onClick: (u) => openProfile(u),
    },
  ]}
/>
```

***

### onItemClick

Callback when a user item is clicked.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `(user: CometChat.User) => void` |
| Default | `undefined`                      |

***

### onSelect

Callback when a user is selected or deselected (only fires in selection mode).

|         |                                                     |
| ------- | --------------------------------------------------- |
| Type    | `(user: CometChat.User, selected: boolean) => void` |
| Default | `undefined`                                         |

***

### onError

Callback when an SDK error occurs during fetch or real-time operations.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `null`                                                    |

***

### onEmpty

Callback when the user list is empty after the initial fetch completes.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

## CSS Selectors

| Target         | Selector                           |
| -------------- | ---------------------------------- |
| Root container | `.cometchat-users`                 |
| Header         | `.cometchat-users__header`         |
| Search bar     | `.cometchat-users__search-bar`     |
| List container | `.cometchat-users__list`           |
| User item      | `.cometchat-users__item`           |
| Active item    | `.cometchat-users__item--active`   |
| Section header | `.cometchat-users__section-header` |
| Empty state    | `.cometchat-users__empty-state`    |
| Error state    | `.cometchat-users__error-state`    |
| Loading state  | `.cometchat-users__loading-state`  |

***

## Next Steps

<CardGroup>
  <Card title="Conversations" icon="comments" href="/ui-kit/react/components/conversations">
    View recent conversations for the logged-in user
  </Card>

  <Card title="Groups" icon="users" href="/ui-kit/react/components/groups">
    Browse and join groups
  </Card>

  <Card title="Message List" icon="comment-dots" href="/ui-kit/react/components/message-list">
    Display messages for the selected user
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


# Video Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/video-bubble

A batch-aware bubble that renders one or more video attachments with adaptive grid layouts, poster thumbnails, and a fullscreen viewer.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatVideosBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatVideosBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Batch-aware video bubble. Extracts video attachments and caption from a MediaMessage; renders adaptive grid layouts with poster thumbnails and opens a fullscreen viewer.",
    "cssRootClass": ".cometchat-videos-bubble",
    "selfExtracting": true,
    "multiAttachment": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of attachments and caption." },
        "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." },
        "textFormatters": { "type": "CometChatTextFormatter[]" },
        "onVideoClicked": { "type": "(attachment, index) => void" },
        "className": { "type": "string" }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatVideosBubble` renders the video attachment(s) of a media message with batch-aware styling. It is **self-extracting**: pass the SDK `message` and the bubble derives its attachments, caption, and alignment itself. The message list uses it automatically for video messages.

Key capabilities:

* **Adaptive grid layouts** — single video, 2-column, 2×2 grid, and overflow (+N) based on attachment count
* **Poster thumbnails** — auto-generated from the `thumbnail-generation` extension or first frame
* **Duration overlay** — displays video duration on each tile
* **Play icon overlay** — visual indicator on each video tile
* **Fullscreen viewer** — click any video to open in fullscreen player
* **Batch grouping** — rendered as one connected group when several media messages are sent together (handled by the [message list](/docs/ui-kit/react/components/message-list#multi-attachment-batch-grouping))

<Info>
  **Live Preview** — interact with the video bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble-videos--grid-2-videos)
</Info>

<iframe title="CometChat Video Bubble — 2 Videos Grid" />

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatVideosBubble } from "@cometchat/chat-uikit-react";

function VideoMessage({ message }: { message: CometChat.MediaMessage }) {
  return <CometChatVideosBubble message={message} />;
}
```

***

## Grid Layouts

The bubble automatically selects a layout based on the number of video attachments:

| Attachment Count | Layout         | Description                                  |
| ---------------- | -------------- | -------------------------------------------- |
| 1                | `single`       | Full-width single video with poster          |
| 2                | `grid` (2-col) | Side-by-side video tiles                     |
| 3                | `grid` (three) | 2-col grid with one spanning                 |
| 4                | `grid-2x2`     | 2×2 even grid                                |
| 5+               | `overflow`     | 2×2 grid with last tile showing "+N" overlay |

Each tile shows a poster thumbnail, play icon, and duration badge.

<iframe title="CometChat Video Bubble — Grid With Caption" />

***

## Props

### message

The video message. The bubble extracts its attachments and caption from it. **Required.**

|          |                          |
| -------- | ------------------------ |
| Type     | `CometChat.MediaMessage` |
| Required | Yes                      |

***

### alignment

Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user.

|         |                     |
| ------- | ------------------- |
| Type    | `"left" \| "right"` |
| Default | derived             |

***

### textFormatters

Text formatters applied to the caption (mentions, URLs).

|         |                            |
| ------- | -------------------------- |
| Type    | `CometChatTextFormatter[]` |
| Default | `undefined`                |

***

### onVideoClicked

Callback fired when a video tile is clicked.

|         |                                                                        |
| ------- | ---------------------------------------------------------------------- |
| Type    | `(attachment: CometChatVideosBubbleAttachment, index: number) => void` |
| Default | `undefined`                                                            |

***

### className

Additional CSS class applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## CSS Selectors

| Target             | Selector                                     |
| ------------------ | -------------------------------------------- |
| Root               | `.cometchat-videos-bubble`                   |
| Incoming variant   | `.cometchat-videos-bubble--incoming`         |
| Outgoing variant   | `.cometchat-videos-bubble--outgoing`         |
| Single layout      | `.cometchat-videos-bubble--single`           |
| Grid container     | `.cometchat-videos-bubble__grid`             |
| 2-column grid      | `.cometchat-videos-bubble__grid--two-col`    |
| 3-video grid       | `.cometchat-videos-bubble__grid--three`      |
| 2×2 grid           | `.cometchat-videos-bubble__grid--2x2`        |
| Overflow grid      | `.cometchat-videos-bubble__grid--overflow`   |
| Video tile         | `.cometchat-videos-bubble__tile`             |
| Poster thumbnail   | `.cometchat-videos-bubble__thumbnail`        |
| Play icon          | `.cometchat-videos-bubble__play-icon`        |
| Duration badge     | `.cometchat-videos-bubble__duration`         |
| Placeholder        | `.cometchat-videos-bubble__placeholder`      |
| Overflow tile      | `.cometchat-videos-bubble__overflow-tile`    |
| Overflow overlay   | `.cometchat-videos-bubble__overflow-overlay` |
| Overflow text (+N) | `.cometchat-videos-bubble__overflow-text`    |
| Container          | `.cometchat-videos-bubble__container`        |
| Caption            | `.cometchat-videos-bubble__caption`          |

***

## Next Steps

<CardGroup>
  <Card title="Image Bubble" icon="image" href="/ui-kit/react/components/image-bubble">
    Batch-aware image bubble with grid layouts
  </Card>

  <Card title="Audio Bubble" icon="music" href="/ui-kit/react/components/audio-bubble">
    Batch-aware audio bubble with player cards
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/react/components/message-list">
    Multi-attachment batch grouping in the list
  </Card>

  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/react/components/message-composer">
    Multi-attachment staging tray
  </Card>
</CardGroup>


# Voice Note Bubble
Source: https://www.cometchat.com/docs/ui-kit/react/components/voice-note-bubble

A dedicated bubble for recorded voice notes with waveform playback, rendered when audio messages carry the voice_note metadata tag.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatVoiceNoteBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatVoiceNoteBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Voice note bubble. Renders for audio messages explicitly tagged audioType='voice_note'. Renders the CometChatAudioBubble waveform player internally. Always standalone (no grid).",
    "cssRootClass": ".cometchat-audio-bubble",
    "selfExtracting": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Must have metadata audioType='voice_note'." },
        "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." },
        "textFormatters": { "type": "CometChatTextFormatter[]" },
        "className": { "type": "string" }
      }
    }
  }
  ```
</Accordion>

## Overview

`CometChatVoiceNoteBubble` renders audio messages that were recorded via the composer's voice recorder. It renders using the `CometChatAudioBubble` waveform player (documented [below](#the-waveform-player)), giving voice notes a compact play/pause + waveform UI.

This bubble renders whenever an audio message carries `audioType: "voice_note"` in its metadata. Voice notes are always standalone — they never participate in batch grid layouts or multi-attachment grouping.

<Note>
  **Routing logic.** The audio plugin automatically routes messages based on metadata:

  * `audioType: "voice_note"` → `CometChatVoiceNoteBubble` (this component)
  * No `audioType` (attached audio files) → [Audio Bubble](/docs/ui-kit/react/components/audio-bubble) (`CometChatAudiosBubble`)

  You don't need to configure this — it's handled automatically by the plugin system.
</Note>

Key characteristics:

* **Waveform playback** — play/pause, seekable progress bar, elapsed/total time
* **Always standalone** — voice notes are never grouped or batched with other messages
* **Metadata-driven** — only used when the message has `audioType: "voice_note"` in metadata
* **Waveform player** — renders with the `CometChatAudioBubble` player and its CSS selectors

<Info>
  **Live Preview** — interact with the voice note bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble-voice-note--default)
</Info>

<iframe title="CometChat Voice Note Bubble — Default" />

***

## Usage

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatVoiceNoteBubble } from "@cometchat/chat-uikit-react";

function VoiceNoteMessage({ message }: { message: CometChat.MediaMessage }) {
  return <CometChatVoiceNoteBubble message={message} />;
}
```

***

## How Voice Notes Are Tagged

When a user records audio via the composer's voice recorder, the UIKit stamps `audioType: "voice_note"` into the message metadata before sending:

```json theme={null}
{
  "metadata": {
    "audioType": "voice_note"
  }
}
```

Audio files attached via the attachment menu do **not** receive this tag — they render as the [Audio Bubble](/docs/ui-kit/react/components/audio-bubble) (`CometChatAudiosBubble`) instead.

***

## Props

### message

The audio message (voice note). The bubble renders it with the `CometChatAudioBubble` waveform player. **Required.**

|          |                          |
| -------- | ------------------------ |
| Type     | `CometChat.MediaMessage` |
| Required | Yes                      |

***

### alignment

Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user.

|         |                     |
| ------- | ------------------- |
| Type    | `"left" \| "right"` |
| Default | derived             |

***

### textFormatters

Text formatters applied to any caption.

|         |                            |
| ------- | -------------------------- |
| Type    | `CometChatTextFormatter[]` |
| Default | `undefined`                |

***

### className

Additional CSS class applied to the root element.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

## The Waveform Player

Voice notes render with the `CometChatAudioBubble` waveform player — a compact single-audio player with play/pause controls, a waveform progress bar, elapsed/total time, and a download control. It self-extracts the audio attachment from the `message`, so it can also be used standalone to render a single audio waveform.

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatAudioBubble } from "@cometchat/chat-uikit-react";

function Waveform({ message }: { message: CometChat.MediaMessage }) {
  return <CometChatAudioBubble message={message} />;
}
```

The player accepts the same core props — `message` (required), `alignment`, and `className`.

<Info>
  Attached audio **files** (not voice notes) render as stacked player cards via `CometChatAudiosBubble` — see the [Audio Bubble](/docs/ui-kit/react/components/audio-bubble) page.
</Info>

***

## CSS Selectors

The voice note renders with the `CometChatAudioBubble` waveform player, which uses these selectors:

| Target                | Selector                                                                |
| --------------------- | ----------------------------------------------------------------------- |
| Root                  | `.cometchat-audio-bubble`                                               |
| Sender / receiver     | `.cometchat-audio-bubble--sender` / `.cometchat-audio-bubble--receiver` |
| Container             | `.cometchat-audio-bubble__container`                                    |
| Play button           | `.cometchat-audio-bubble__play-button`                                  |
| Pause button          | `.cometchat-audio-bubble__pause-button`                                 |
| Waveform              | `.cometchat-audio-bubble__waveform`                                     |
| Progress (background) | `.cometchat-audio-bubble__progress-bg`                                  |
| Progress (foreground) | `.cometchat-audio-bubble__progress-fg`                                  |
| Time                  | `.cometchat-audio-bubble__time`                                         |
| Download button       | `.cometchat-audio-bubble__download-button`                              |
| Caption               | `.cometchat-audio-bubble__caption`                                      |

***

## Next Steps

<CardGroup>
  <Card title="Audio Bubble" icon="music" href="/ui-kit/react/components/audio-bubble">
    Batch-aware bubble for attached audio files
  </Card>

  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/react/components/message-composer">
    Voice recorder and multi-attachment staging
  </Card>

  <Card title="Image Bubble" icon="image" href="/ui-kit/react/components/image-bubble">
    Batch-aware image bubble with grid layouts
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/react/components/message-list">
    Multi-attachment batch grouping in the list
  </Card>
</CardGroup>


# Core
Source: https://www.cometchat.com/docs/ui-kit/react/core-features

Overview of CometChat React UI Kit core features, including messaging, media sharing, receipts, presence, reactions, search, and moderation.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
  | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Package          | `@cometchat/chat-uikit-react`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
  | Required setup   | Wrap app in `CometChatProvider` with valid credentials — must complete before rendering any component                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
  | Core features    | Instant Messaging, Media Sharing, Read Receipts, Mark as Unread, Typing Indicator, User Presence, Reactions, Mentions, Quoted Reply, Search, Threaded Conversations, Moderation, Report Message, Group Chat                                                                                                                                                                                                                                                                                                                                                        |
  | Key components   | `CometChatConversations` → [Conversations](/docs/ui-kit/react/components/conversations), `CometChatMessageList` → [Message List](/docs/ui-kit/react/components/message-list), `CometChatMessageComposer` → [Message Composer](/docs/ui-kit/react/components/message-composer), `CometChatMessageHeader` → [Message Header](/docs/ui-kit/react/components/message-header), `CometChatUsers` → [Users](/docs/ui-kit/react/components/users), `CometChatGroups` → [Groups](/docs/ui-kit/react/components/groups), `CometChatGroupMembers` → [Group Members](/docs/ui-kit/react/components/group-members) |
  | CSS class prefix | `.cometchat-`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
  | Theming          | Override CSS variables on `.cometchat` class. See [Theming](/docs/ui-kit/react/theming)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
</Accordion>

The UI Kit components work together to deliver a complete chat experience. The sections below map each core feature to the components that power it.

## Instant Messaging

At the heart of CometChat's functionality is the ability to support real-time text messaging. Users can send and receive instant messages, fostering quick and efficient communication.

<Frame>
  <img />
</Frame>

| Components                                                    | Functionality                                                                                                                                          |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Message Composer](/docs/ui-kit/react/components/message-composer) | The [Message Composer](/docs/ui-kit/react/components/message-composer) is a Component that enables users to write and send a variety of messages.           |
| [Message List](/docs/ui-kit/react/components/message-list)         | The [Message List](/docs/ui-kit/react/components/message-list) is a Component that renders a list of messages sent and messages received using Text Bubble. |

## Media Sharing

CometChat supports sharing images, videos, audio files, and documents within conversations.

Share multiple attachments in a single send — click the attachment button to open a multi-select picker, or drag-and-drop and paste files straight into the composer. The picks stage in a preview tray above the input box with per-file upload progress, remove, and retry, and send together with an optional caption — all out of the box.

<Frame>
  <img />
</Frame>

| Components                                                                                  | Functionality                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Message Composer](/docs/ui-kit/react/components/message-composer#multi-attachment-staging-tray) | An attachment menu for sharing media files, plus a multi-select staging tray that uploads files before send with per-file progress, remove, and retry. The composer text becomes the batch caption. |
| [Message List](/docs/ui-kit/react/components/message-list#multi-attachment-batch-grouping)       | Renders media message bubbles — Image, Video, Audio, and File — and groups a multi-attachment send as one visually connected batch.                                                                 |

## Read Receipts

CometChat's Read Receipts feature provides visibility into the message status, letting users know when a message has been delivered and read. This brings clarity to the communication and ensures users are informed about the status of their messages.

<Frame>
  <img />
</Frame>

| Components                                              | Functionality                                                                                                                                                                                                                                                            |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Conversations](/docs/ui-kit/react/components/conversations) | [Conversations](/docs/ui-kit/react/components/conversations) is a component that renders conversation list item. Conversation item also displays the delivery status of the last message providing users with real-time updates on the status of their messages.              |
| [Message List](/docs/ui-kit/react/components/message-list)   | [Message List](/docs/ui-kit/react/components/message-list) is a component that renders different types of message bubbles. Read receipt status is an integral part of all message bubbles, no matter the type and provides real-time updates about the status of the message. |
| Message Information                                     | Message Information component provides transparency into the status of each sent message, giving the sender insights into whether their message has been delivered and read.                                                                                             |

## Mark as Unread

Mark as Unread feature allows users to manually mark messages as unread, helping them keep track of important conversations they want to revisit later. When enabled, the message list can automatically start from the first unread message, making it easier to pick up where you left off.

<Frame>
  <img />
</Frame>

| Components                                              | Functionality                                                                                                                                                                   |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Message List](/docs/ui-kit/react/components/message-list)   | [Message List](/docs/ui-kit/react/components/message-list) provides the "Mark as unread" option in message actions and supports starting from the first unread message when enabled. |
| [Conversations](/docs/ui-kit/react/components/conversations) | [Conversations](/docs/ui-kit/react/components/conversations) component listens to conversation updates and reflects the updated unread count in real-time.                           |

## Typing Indicator

The Typing Indicator feature in CometChat shows when a user is typing a response in real-time, fostering a more interactive and engaging chat environment. This feature enhances the real-time communication experience, making conversations feel more natural and fluid.

<Frame>
  <img />
</Frame>

| Components                                                | Functionality                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Conversations](/docs/ui-kit/react/components/conversations)   | [Conversations](/docs/ui-kit/react/components/conversations) is a component that renders conversation list item. Conversations item also shows real-time typing status indicators. This means that if a user in a one-on-one chat or a participant in a group chat is currently typing a message.                        |
| [Message Header](/docs/ui-kit/react/components/message-header) | [Message Header](/docs/ui-kit/react/components/message-header) that renders details of User or Groups in ToolBar. The Message Header also handles the typing indicator functionality. When a user or a member in a group is typing, the Message Header dynamically updates to display a `typing...` status in real-time. |

## User Presence

CometChat's User Presence feature allows users to see whether their contacts are online, offline. This helps users know the best time to initiate a conversation and sets expectations about response times.

<Frame>
  <img />
</Frame>

| Components                                                | Functionality                                                                                                                                                             |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Conversations](/docs/ui-kit/react/components/conversations)   | [Conversations](/docs/ui-kit/react/components/conversations) is a component that renders conversation list item. Conversations item also shows user presence information.      |
| [Message Header](/docs/ui-kit/react/components/message-header) | [Message Header](/docs/ui-kit/react/components/message-header) that renders details of user/group. The Message Header also handles user presence information.                  |
| [Users](/docs/ui-kit/react/components/users)                   | [Users](/docs/ui-kit/react/components/users) renders the list of available users with presence information.                                                                    |
| [Group Members](/docs/ui-kit/react/components/group-members)   | [Group Members](/docs/ui-kit/react/components/group-members) renders list of users available in the group. The Group Members component also handles user presence information. |

## Reactions

CometChat's Reactions feature adds a layer of expressiveness to your chat application by allowing users to react to messages. With reactions, users can convey a range of emotions or express their thoughts on a particular message without typing out a full response, enhancing their user experience and fostering greater engagement.

<Frame>
  <img />
</Frame>

| Components                                            | Functionality                                                                                                                                                                                                                    |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Message List](/docs/ui-kit/react/components/message-list) | [Message List](/docs/ui-kit/react/components/message-list) is a component that renders different types of message bubbles. Reactions are an integral part and offer a more engaging, expressive way for users to respond to messages. |

## Mentions

Mentions is a robust feature provided by CometChat that enhances the interactivity and clarity of group or 1-1 chats by allowing users to directly address or refer to specific individuals in a conversation. The feature also supports group mentions like @all, enabling users to quickly notify all members in a group chat simultaneously.

<Frame>
  <img />
</Frame>

| Components                                                    | Functionality                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Conversations](/docs/ui-kit/react/components/conversations)       | [Conversations](/docs/ui-kit/react/components/conversations) component provides an enhanced user experience by integrating the Mentions feature. This means that from the conversation list itself, users can see where they or someone else have been specifically mentioned. |
| [Message Composer](/docs/ui-kit/react/components/message-composer) | [Message Composer](/docs/ui-kit/react/components/message-composer) is a component that allows users to craft and send various types of messages, including the usage of the mentions feature for direct addressing within the conversation.                                    |
| [Message List](/docs/ui-kit/react/components/message-list)         | [Message List](/docs/ui-kit/react/components/message-list) is a component that displays a list of sent and received messages. It also supports the rendering of Mentions, enhancing the readability and interactivity of conversations.                                        |

## Rich Text Formatting

Rich Text Formatting allows users to style their messages with bold, italic, underline, strikethrough, code, links, lists, and blockquotes. This brings richer expression to conversations and helps users emphasize key points, making communication clearer and more engaging.

<Frame>
  <img />
</Frame>

| Components                                                    | Functionality                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Message Composer](/docs/ui-kit/react/components/message-composer) | [Message Composer](/docs/ui-kit/react/components/message-composer) with `enableRichTextEditor` provides a built-in rich text editor with formatting toolbar, floating selection toolbar, and keyboard shortcuts for bold, italic, underline, strikethrough, code, links, lists, and blockquotes. |
| [Message List](/docs/ui-kit/react/components/message-list)         | [Message List](/docs/ui-kit/react/components/message-list) renders formatted messages with the appropriate styling applied, displaying bold, italic, underline, strikethrough, code, links, lists, and blockquote formatting as intended by the sender.                                          |

## Threaded Conversations

The Threaded Conversations feature enables users to respond directly to a specific message in a chat. This keeps conversations organized and enhances the user experience by maintaining context, especially in group chats.

<Frame>
  <img />
</Frame>

| Components                                                        | Functionality                                                                                                                             |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [Threaded Message Preview](/docs/ui-kit/react/guide-threaded-messages) | [Threaded Message Preview](/docs/ui-kit/react/guide-threaded-messages) component displays the parent message along with the number of replies. |

## Quoted Replies

Quoted Replies is a robust feature provided by CometChat that enables users to quickly reply to specific messages by selecting the "Reply" option from a message's action menu. This enhances context, keeps conversations organized, and improves overall chat experience in both 1-1 and group chats.

<Frame>
  <img />
</Frame>

| Components                                                    | Functionality                                                                                                                                                                                                                 |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Message List](/docs/ui-kit/react/components/message-list)         | [Message List](/docs/ui-kit/react/components/message-list) supports replying to messages via the "Reply" option. Users can select "Reply" on a message to open the composer with the quoted reply pre-filled, maintaining context. |
| [Message Composer](/docs/ui-kit/react/components/message-composer) | [Message Composer](/docs/ui-kit/react/components/message-composer) shows the quoted reply above the input field, providing context for the response.                                                                               |

## Group Chat

CometChat facilitates Group Chats, allowing users to have conversations with multiple participants simultaneously. This feature is crucial for team collaborations, group discussions, social communities, and more.

<Frame>
  <img />
</Frame>

See the [Groups](/docs/ui-kit/react/components/groups) component page for details.

## Moderation

CometChat's Message Moderation feature helps maintain a safe and respectful chat environment by automatically filtering and managing inappropriate content. Messages can be automatically blocked or flagged based on predefined rules, ensuring harmful content is handled before it reaches users.

<Frame>
  <img />
</Frame>

<Note>
  Learn more about setting up moderation rules and managing content in the [Moderation](/docs/moderation/overview) documentation.
</Note>

| Components                                            | Functionality                                                                                                                                            |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Message List](/docs/ui-kit/react/components/message-list) | [Message List](/docs/ui-kit/react/components/message-list) automatically handles moderated messages, displaying blocked content based on moderation settings. |

The **[Report Message](#report-message)** feature enables users to flag messages for review by moderators.

## Report Message

The Report Message feature allows users to report inappropriate or harmful messages within the chat. Users can choose from predefined reasons and provide additional remarks for detailed context. This feature helps maintain a safe and respectful chat environment.

<Note>
  Learn more about how flagged messages are handled, reviewed, and moderated in the [Flagged Messages](/docs/moderation/flagged-messages) documentation.
</Note>

<Frame>
  <img />
</Frame>

| Components                                            | Functionality                                                                                                                                                                                        |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Message List](/docs/ui-kit/react/components/message-list) | [Message List](/docs/ui-kit/react/components/message-list) provides the "Report Message" option in the message actions menu, allowing users to initiate the reporting process for inappropriate messages. |

## Conversation and Advanced Search

Conversation and Advanced Search is a powerful feature provided by CometChat that enables users to quickly find conversations, messages, and media across chats in real time. It supports filters, scopes, and custom actions, allowing users to locate content efficiently while keeping the chat experience smooth and intuitive.

<Frame>
  <img />
</Frame>

| Components                                                | Functionality                                                                                                                                                                                                 |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Search](/docs/ui-kit/react/components/search)                 | [Search](/docs/ui-kit/react/components/search) allows users to search across conversations and messages in real time. Users can click on a result to open the conversation or jump directly to a specific message. |
| [Message Header](/docs/ui-kit/react/components/message-header) | [Message Header](/docs/ui-kit/react/components/message-header) shows the search button in the chat header, allowing users to search within a conversation.                                                         |
| [Message List](/docs/ui-kit/react/components/message-list)     | [Message List](/docs/ui-kit/react/components/message-list) shows the selected message when clicked from search results and highlights it in the message list.                                                      |
| [Conversations](/docs/ui-kit/react/components/conversations)   | [Conversations](/docs/ui-kit/react/components/conversations) displays the search input.                                                                                                                            |

See the [Groups](/docs/ui-kit/react/components/groups) component page for details.

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all available UI Kit components
  </Card>

  <Card title="Theme" icon="palette" href="/ui-kit/react/theming">
    Customize the look and feel of your chat UI
  </Card>

  <Card title="Call Features" icon="phone" href="/ui-kit/react/call-features">
    Add audio and video calling
  </Card>

  <Card title="AI Features" icon="robot" href="/ui-kit/react/ai-features">
    Explore AI-powered chat capabilities
  </Card>
</CardGroup>


# Event System
Source: https://www.cometchat.com/docs/ui-kit/react/event-system

Unified pub/sub event system that merges SDK listener events with local UI events for cross-component communication.

<Accordion title="AI Integration Quick Reference">
  | Field           | Value                                                                                               |
  | --------------- | --------------------------------------------------------------------------------------------------- |
  | Subscribe hook  | `useCometChatEvents((event) => { ... })`                                                            |
  | Publish hook    | `const publish = usePublishEvent()`                                                                 |
  | Provider        | `CometChatEventsProvider` (mounted automatically by `CometChatProvider` after login)                |
  | Event prefix    | SDK events: `message/`, `receipt/`, `user/`, `group/`, `call/`, `connection/`                       |
  | UI event prefix | `ui:message/`, `ui:compose/`, `ui:group/`, `ui:call/`, `ui:thread/`, `ui:conversation/`, `ui:card/` |
</Accordion>

## Overview

The v7 event system merges CometChat SDK listener events (from the network) with local UI events (from component actions) into a single pub/sub bus. Components subscribe to events they care about and publish events when they perform actions that other components need to know about.

This replaces v6's RxJS-based `CometChatMessageEvents`, `CometChatGroupEvents`, etc. with a single unified system.

***

## How It Works

```mermaid theme={null}
flowchart LR
  subgraph CometChatEventsProvider
    SDK["SDK Listeners\n(message, user, group, call, connection)"]
    UI["UI Events\n(publish())"]
    Bus["Event Bus"]
    Subs["subscribers.forEach()"]

    SDK --> Bus
    UI --> Bus
    Bus --> Subs
  end
```

1. **SDK listeners** are attached when `CometChatEventsProvider` mounts (after login)
2. When the SDK fires a listener callback, it's converted to a typed event and emitted to all subscribers
3. Components can also **publish** UI events for local cross-component communication
4. All subscribers receive all events — filter by `event.type` in your handler

***

## Subscribing to Events

Use the `useCometChatEvents` hook to subscribe:

```tsx theme={null}
import { useCometChatEvents } from "@cometchat/chat-uikit-react";

function MyComponent() {
  useCometChatEvents((event) => {
    switch (event.type) {
      case "message/text-received":
        console.log("New message:", event.message.getText());
        break;
      case "user/online":
        console.log("User online:", event.user.getName());
        break;
      case "ui:message/sent":
        console.log("Message sent:", event.message.getId());
        break;
    }
  });

  return <div>...</div>;
}
```

The hook automatically subscribes on mount and unsubscribes on unmount. No cleanup needed.

***

## Publishing UI Events

Use the `usePublishEvent` hook to publish events that other components can react to:

```tsx theme={null}
import { usePublishEvent } from "@cometchat/chat-uikit-react";

function MyComponent() {
  const publish = usePublishEvent();

  const handleSend = (message: CometChat.BaseMessage) => {
    publish({
      type: "ui:message/sent",
      message,
      status: CometChatMessageStatus.success,
    });
  };

  return <button onClick={() => handleSend(msg)}>Send</button>;
}
```

Only `ui:` prefixed events can be published by components. SDK events are emitted internally by the provider.

***

## SDK Events

These events originate from the CometChat SDK (network). They fire when other users perform actions.

### Message Events

| Event Type                     | Payload                           | When                                       |
| ------------------------------ | --------------------------------- | ------------------------------------------ |
| `message/text-received`        | `{ message: TextMessage }`        | Text message received                      |
| `message/media-received`       | `{ message: MediaMessage }`       | Media message received                     |
| `message/custom-received`      | `{ message: CustomMessage }`      | Custom message received                    |
| `message/interactive-received` | `{ message: InteractiveMessage }` | Interactive message received               |
| `message/card-received`        | `{ message: BaseMessage }`        | Card message (`category: "card"`) received |
| `message/edited`               | `{ message: BaseMessage }`        | Message was edited                         |
| `message/deleted`              | `{ message: BaseMessage }`        | Message was deleted                        |
| `message/moderated`            | `{ message: BaseMessage }`        | Message was moderated                      |

### Receipt Events

| Event Type                 | Payload                       | When                             |
| -------------------------- | ----------------------------- | -------------------------------- |
| `receipt/delivered`        | `{ receipt: MessageReceipt }` | Message delivered to recipient   |
| `receipt/read`             | `{ receipt: MessageReceipt }` | Message read by recipient        |
| `receipt/delivered-to-all` | `{ receipt: MessageReceipt }` | Message delivered to all (group) |
| `receipt/read-by-all`      | `{ receipt: MessageReceipt }` | Message read by all (group)      |

### Reaction Events

| Event Type         | Payload                    | When                            |
| ------------------ | -------------------------- | ------------------------------- |
| `reaction/added`   | `{ event: ReactionEvent }` | Reaction added to a message     |
| `reaction/removed` | `{ event: ReactionEvent }` | Reaction removed from a message |

### Typing Events

| Event Type       | Payload                          | When                |
| ---------------- | -------------------------------- | ------------------- |
| `typing/started` | `{ indicator: TypingIndicator }` | User started typing |
| `typing/ended`   | `{ indicator: TypingIndicator }` | User stopped typing |

### User Events

| Event Type     | Payload          | When              |
| -------------- | ---------------- | ----------------- |
| `user/online`  | `{ user: User }` | User came online  |
| `user/offline` | `{ user: User }` | User went offline |

### Group Events

| Event Type                   | Payload                                                     | When                  |
| ---------------------------- | ----------------------------------------------------------- | --------------------- |
| `group/member-joined`        | `{ action, joinedUser, joinedGroup }`                       | Member joined a group |
| `group/member-left`          | `{ action, leftUser, leftGroup }`                           | Member left a group   |
| `group/member-kicked`        | `{ action, kickedUser, kickedBy, kickedFrom }`              | Member was kicked     |
| `group/member-banned`        | `{ action, bannedUser, bannedBy, bannedFrom }`              | Member was banned     |
| `group/member-unbanned`      | `{ action, unbannedUser, unbannedBy, unbannedFrom }`        | Member was unbanned   |
| `group/member-added`         | `{ action, addedBy, addedUser, addedTo }`                   | Member was added      |
| `group/member-scope-changed` | `{ action, changedUser, newScope, oldScope, changedGroup }` | Member scope changed  |

### Call Events

| Event Type       | Payload          | When                        |
| ---------------- | ---------------- | --------------------------- |
| `call/incoming`  | `{ call: Call }` | Incoming call received      |
| `call/accepted`  | `{ call: Call }` | Outgoing call was accepted  |
| `call/rejected`  | `{ call: Call }` | Outgoing call was rejected  |
| `call/cancelled` | `{ call: Call }` | Incoming call was cancelled |
| `call/ended`     | `{ call: Call }` | Call ended                  |

### Connection Events

| Event Type                | Payload | When                   |
| ------------------------- | ------- | ---------------------- |
| `connection/connected`    | —       | WebSocket connected    |
| `connection/disconnected` | —       | WebSocket disconnected |

***

## UI Events

These events are published by UI Kit components for local cross-component communication within the same tab.

### Message Lifecycle

| Event Type           | Payload               | Published by               |
| -------------------- | --------------------- | -------------------------- |
| `ui:message/sent`    | `{ message, status }` | MessageComposer            |
| `ui:message/deleted` | `{ message }`         | MessageList (after delete) |
| `ui:message/read`    | `{ message }`         | MessageList (mark as read) |

### Composer Commands

| Event Type                     | Payload                                 | Published by                         |
| ------------------------------ | --------------------------------------- | ------------------------------------ |
| `ui:compose/edit`              | `{ message, status, parentMessageId? }` | MessageList (edit option)            |
| `ui:compose/reply`             | `{ message, status, parentMessageId? }` | MessageList (reply option)           |
| `ui:compose/text`              | `{ text }`                              | Smart replies, conversation starters |
| `ui:compose/recording-started` | `{ composerInstanceId }`                | MessageComposer (voice recording)    |

### Conversation State

| Event Type                | Payload                                            | Published by                  |
| ------------------------- | -------------------------------------------------- | ----------------------------- |
| `ui:conversation/read`    | `{ conversationId }`                               | MessageList                   |
| `ui:conversation/updated` | `{ conversation }`                                 | MessageList                   |
| `ui:conversation/deleted` | `{ conversation }`                                 | Conversations (delete action) |
| `ui:active-chat/changed`  | `{ user?, group?, message?, unreadMessageCount? }` | MessageList (on load)         |

### User & Group Actions

| Event Type                      | Payload                                 | Published by  |
| ------------------------------- | --------------------------------------- | ------------- |
| `ui:user/blocked`               | `{ user }`                              | MessageHeader |
| `ui:user/unblocked`             | `{ user }`                              | MessageHeader |
| `ui:group/created`              | `{ group }`                             | Groups        |
| `ui:group/left`                 | `{ group }`                             | GroupMembers  |
| `ui:group/deleted`              | `{ group }`                             | Groups        |
| `ui:group/member-kicked`        | `{ message, user, group }`              | GroupMembers  |
| `ui:group/member-banned`        | `{ message, user, group }`              | GroupMembers  |
| `ui:group/member-unbanned`      | `{ message?, user, group }`             | GroupMembers  |
| `ui:group/member-scope-changed` | `{ message, user, group, newScope }`    | GroupMembers  |
| `ui:group/ownership-changed`    | `{ group, newOwner, previousOwnerUid }` | GroupMembers  |

### Thread

| Event Type         | Payload             | Published by                |
| ------------------ | ------------------- | --------------------------- |
| `ui:thread/opened` | `{ parentMessage }` | MessageList (thread option) |
| `ui:thread/closed` | —                   | ThreadHeader                |

### Call Actions

| Event Type         | Payload                  | Published by                 |
| ------------------ | ------------------------ | ---------------------------- |
| `ui:call/outgoing` | `{ call }`               | MessageHeader (call buttons) |
| `ui:call/rejected` | `{ call }`               | IncomingCall                 |
| `ui:call/ended`    | `{ call? }`              | OngoingCall                  |
| `ui:call/accepted` | `{ call }`               | IncomingCall                 |
| `ui:call/join`     | `{ sessionId, message }` | CallLogs                     |

### Navigation

| Event Type     | Payload             | Published by                           |
| -------------- | ------------------- | -------------------------------------- |
| `ui:open-chat` | `{ user?, group? }` | MessageList (message privately option) |

### Card Actions

| Event Type       | Payload               | Published by                                                                    |
| ---------------- | --------------------- | ------------------------------------------------------------------------------- |
| `ui:card/action` | `{ message, action }` | [Card Bubble](/docs/ui-kit/react/components/card-bubble) (user clicks a card action) |

Published when a user clicks an action (button, link, etc.) inside a card message bubble. The kit performs no behavior — it forwards the raw `action` and its `message` to your app, so you own all action handling. This is the only channel that can reach a kit-instantiated card (e.g. a nested agent card) where no prop is reachable.

### Panels

| Event Type      | Payload               | Published by |
| --------------- | --------------------- | ------------ |
| `ui:panel/show` | `{ position, panel }` | AI features  |
| `ui:panel/hide` | `{ position }`        | AI features  |

***

## Differences from v6

| v6                                                                                     | v7                                                                     |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Multiple RxJS Subject classes (`CometChatMessageEvents`, `CometChatGroupEvents`, etc.) | Single unified event bus                                               |
| `CometChatMessageEvents.ccMessageSent.next(...)`                                       | `publish({ type: 'ui:message/sent', ... })`                            |
| `CometChatMessageEvents.ccMessageSent.subscribe(...)`                                  | `useCometChatEvents((e) => { if (e.type === 'ui:message/sent') ... })` |
| Manual listener management                                                             | Automatic — provider handles all SDK listeners                         |
| RxJS dependency                                                                        | No external dependencies                                               |


# Extensions
Source: https://www.cometchat.com/docs/ui-kit/react/extensions

Overview of CometChat extensions for React UI Kit, including engagement, collaboration, security, support, and smart chat features.

<Accordion title="AI Integration Quick Reference">
  | Field                | Value                                                                                                                                                                                                                                                      |
  | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package              | `@cometchat/chat-uikit-react`                                                                                                                                                                                                                              |
  | Required setup       | Wrap app in `CometChatProvider` with valid credentials + Extensions enabled in [CometChat Dashboard](/docs/fundamentals/extensions-overview)                                                                                                                    |
  | Extension categories | User Experience, User Engagement, Collaboration, Security, Customer Support, Smart Chat Features                                                                                                                                                           |
  | Key components       | `CometChatMessageComposer` → [Message Composer](/docs/ui-kit/react/components/message-composer) (Stickers, Polls, Whiteboard, Document), `CometChatMessageList` → [Message List](/docs/ui-kit/react/components/message-list) (Translation, Link Preview, Thumbnails) |
  | Activation           | Enable each extension from the CometChat Dashboard — UI Kit auto-integrates them, no additional code required                                                                                                                                              |
</Accordion>

## Overview

CometChat UI Kit includes built-in support for extensions that add interactive, secure, and efficient features to chat. Extensions are activated from the [CometChat Dashboard](https://app.cometchat.com/) and auto-integrate into UI Kit components.

<Note>
  Ensure your app is wrapped in `CometChatProvider` with valid credentials. Extensions must be activated from the [CometChat Dashboard](/docs/fundamentals/extensions-overview).
</Note>

## Built-in Extensions

The grouping below mirrors the CometChat Dashboard.

### User Experience

#### Bitly

Shortens long URLs in text messages using Bitly. See [Bitly Extension](/docs/fundamentals/bitly).

#### Link Preview

Displays a summary (title, description, thumbnail) for URLs shared in chat. See [Link Preview Extension](/docs/fundamentals/link-preview).

Auto-integrates into the Message Bubble of [MessageList](/docs/ui-kit/react/components/message-list) when activated.

<Frame>
  <img />
</Frame>

#### Message Shortcuts

Sends predefined messages using short codes (e.g., `!hb` expands to `Happy birthday!`). See [Message Shortcuts Extension](/docs/fundamentals/message-shortcuts).

#### Pin Message

Pins important messages in a conversation for easy access. See [Pin Message Extension](/docs/fundamentals/pin-message).

#### Rich Media Preview

Generates rich preview panels for URLs using iFramely. See [Rich Media Preview Extension](/docs/fundamentals/rich-media-preview).

#### Save Message

Bookmarks messages for later reference. Saved messages are private to the user. See [Save Message Extension](/docs/fundamentals/save-message).

#### Thumbnail Generation

Creates smaller preview images for shared images, reducing bandwidth. See [Thumbnail Generation Extension](/docs/fundamentals/thumbnail-generation).

Auto-integrates into the Message Bubble of [MessageList](/docs/ui-kit/react/components/message-list) when activated.

<Frame>
  <img />
</Frame>

#### TinyURL

URL shortening using TinyURL. See [TinyURL Extension](/docs/fundamentals/tinyurl).

#### Voice Transcription

Converts audio messages to text. See [Voice Transcription Extension](/docs/fundamentals/voice-transcription).

### User Engagement

#### Giphy

Search and share GIFs from Giphy. See [Giphy Extension](/docs/fundamentals/giphy).

#### Message Translation

Translates messages into the local locale. See [Message Translation Extension](/docs/fundamentals/message-translation).

Auto-integrates into the message options menu of [MessageList](/docs/ui-kit/react/components/message-list) when activated.

<Frame>
  <img />
</Frame>

#### Polls

Creates polls in group discussions with predefined answer options. See [Polls Extension](/docs/fundamentals/polls).

Auto-integrates into the Action Sheet of [Message Composer](/docs/ui-kit/react/components/message-composer) when activated.

<Frame>
  <img />
</Frame>

#### Reminders

Sets reminders for messages or creates personal reminders. A bot sends a notification when due. See [Reminders Extension](/docs/fundamentals/reminders).

#### Stickers

Sends pre-designed stickers in chat. See [Sticker Extension](/docs/fundamentals/stickers).

Auto-integrates into [Message Composer](/docs/ui-kit/react/components/message-composer) when activated.

<Frame>
  <img />
</Frame>

#### Stipop

Integrates Stipop's sticker library. See [Stipop Extension](/docs/fundamentals/stickers-stipop).

#### Tenor

Search and share GIFs from Tenor. See [Tenor Extension](/docs/fundamentals/tenor).

### Collaboration

#### Collaborative Document

Shared document editing for real-time collaboration. See [Collaborative Document Extension](/docs/fundamentals/collaborative-document).

Auto-integrates into the Action Sheet of [Message Composer](/docs/ui-kit/react/components/message-composer) when activated.

<Frame>
  <img />
</Frame>

#### Collaborative Whiteboard

Real-time shared whiteboard for drawing and brainstorming. See [Collaborative Whiteboard Extension](/docs/fundamentals/collaborative-whiteboard).

Auto-integrates into the Action Sheet of [Message Composer](/docs/ui-kit/react/components/message-composer) when activated.

<Frame>
  <img />
</Frame>

### Security

#### Disappearing Messages

Messages auto-delete after a specified interval. Works for 1:1 and group messages. See [Disappearing Messages Extension](/docs/fundamentals/disappearing-messages).

### Customer Support

#### Chatwoot

Routes user messages to Chatwoot for customer support. See [Chatwoot Extension](/docs/fundamentals/chatwoot).

#### Intercom

Integrates Intercom for in-app customer support. See [Intercom Extension](/docs/fundamentals/intercom).

### Smart Chat Features

#### Conversation Starter

AI-generated opening messages for new chats. See [Conversation Starter](/docs/fundamentals/ai-user-copilot/conversation-starter) and [AI Features](/docs/ui-kit/react/ai-features).

#### Smart Replies

AI-generated response suggestions based on conversation context. See [Smart Replies](/docs/fundamentals/ai-user-copilot/smart-replies) and [AI Features](/docs/ui-kit/react/ai-features).

#### Conversation Summary

AI-generated recap of long conversations. See [Conversation Summary](/docs/fundamentals/ai-user-copilot/conversation-summary) and [AI Features](/docs/ui-kit/react/ai-features).

***

## Next Steps

<CardGroup>
  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/react/components/message-composer">
    Customize the composer where most extensions appear
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/react/components/message-list">
    Customize the message list for extension-rendered content
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/react/core-features">
    Core chat features like messaging and reactions
  </Card>

  <Card title="AI Features" icon="robot" href="/ui-kit/react/ai-features">
    AI-powered chat capabilities
  </Card>
</CardGroup>


# Block/Unblock User
Source: https://www.cometchat.com/docs/ui-kit/react/guide-block-unblock-user

Let users block and unblock others directly within chat to control unwanted communication.

## Goal

By the end of this guide you will have a chat interface where users can block and unblock other users, with a confirmation dialog before blocking, the composer automatically hidden for blocked users, and an unblock prompt displayed in its place — all coordinated through UI events so every component stays in sync.

## Prerequisites

* Completed the [Integration Guide](/docs/ui-kit/react/integration-react) guide
* A running `CometChatProvider` setup with valid credentials
* An existing one-on-one chat screen using `CometChatMessageList` and `CometChatMessageComposer`

## Components Used

| Component / API            | Purpose                                |
| :------------------------- | :------------------------------------- |
| `CometChatConfirmDialog`   | Compound dialog for block confirmation |
| `CometChatMessageList`     | Displays messages in the conversation  |
| `CometChatMessageComposer` | Text input for sending messages        |
| `useCometChatEvents`       | Subscribe to UI events                 |
| `usePublishEvent`          | Publish UI events                      |
| `CometChat.blockUsers()`   | SDK method to block a user             |
| `CometChat.unblockUsers()` | SDK method to unblock a user           |
| `ui:user/blocked`          | UI event fired after blocking          |
| `ui:user/unblocked`        | UI event fired after unblocking        |

## Step 1: Block User

Call `CometChat.blockUsers()` with the target UID. On success, update the user object and publish the `ui:user/blocked` event so other components (thread panel, details panel) can react.

*File: ChatView\.tsx*

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { usePublishEvent } from "@cometchat/chat-uikit-react";

const publish = usePublishEvent();

async function handleBlock(user: CometChat.User) {
  try {
    await CometChat.blockUsers([user.getUid()]);
    user.setBlockedByMe(true);
    setIsBlocked(true);
    setShowBlockDialog(false);
    publish({ type: "ui:user/blocked", user });
  } catch (error) {
    console.error("Error blocking user:", error);
  }
}
```

## Step 2: Unblock User

Call `CometChat.unblockUsers()` to reverse the block. Publish `ui:user/unblocked` so all listening components restore their normal state.

*File: ChatView\.tsx*

```tsx theme={null}
async function handleUnblock(user: CometChat.User) {
  try {
    await CometChat.unblockUsers([user.getUid()]);
    user.setBlockedByMe(false);
    setIsBlocked(false);
    publish({ type: "ui:user/unblocked", user });
  } catch (error) {
    console.error("Error unblocking user:", error);
  }
}
```

## Step 3: Confirmation Dialog

Show a `CometChatConfirmDialog` before blocking. Render it conditionally based on a `showBlockDialog` state flag.

*File: ChatView\.tsx*

```tsx theme={null}
import { useState } from "react";
import { CometChatConfirmDialog } from "@cometchat/chat-uikit-react";

const [showBlockDialog, setShowBlockDialog] = useState(false);

// In your JSX:
{showBlockDialog && (
  <CometChatConfirmDialog.Root isOpen={true} onClose={() => setShowBlockDialog(false)}>
    <CometChatConfirmDialog.Icon />
    <CometChatConfirmDialog.Content
      title="Block Contact"
      messageText="Are you sure you want to block this user? They won't be able to send you messages."
    />
    <CometChatConfirmDialog.Actions
      confirmButtonText="Block"
      onConfirm={() => handleBlock(user)}
      onCancel={() => setShowBlockDialog(false)}
    />
  </CometChatConfirmDialog.Root>
)}
```

## Step 4: Listen for Block/Unblock Events

Use `useCometChatEvents` to subscribe to block/unblock events. This keeps the composer visibility in sync even when the block action originates from a different component (e.g., a details panel).

*File: ChatView\.tsx*

```tsx theme={null}
import { useCometChatEvents } from "@cometchat/chat-uikit-react";
import type { CometChatEvent } from "@cometchat/chat-uikit-react";

useCometChatEvents(
  (event: CometChatEvent) => {
    if (!user) return;

    if (event.type === "ui:user/blocked" && event.user.getUid() === user.getUid()) {
      setIsBlocked(true);
    }
    if (event.type === "ui:user/unblocked" && event.user.getUid() === user.getUid()) {
      setIsBlocked(false);
    }
  },
  [user?.getUid()]
);
```

## Step 5: Blocked Composer State

Conditionally render the composer or a blocked prompt based on the `isBlocked` state. The blocked prompt includes an inline unblock action.

*File: ChatView\.tsx*

```tsx theme={null}
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react";

// In your JSX:
{!isBlocked ? (
  <CometChatMessageComposer user={user} />
) : (
  <div style={{ padding: "16px", textAlign: "center", background: "#f5f5f5" }}>
    <p>Cannot send a message to a blocked user.</p>
    <span
      onClick={() => handleUnblock(user)}
      role="button"
      tabIndex={0}
      style={{ color: "#3399ff", cursor: "pointer" }}
    >
      Click to unblock.
    </span>
  </div>
)}
```

## Complete Example

*File: ChatView\.tsx*

```tsx theme={null}
import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatMessageHeader,
  CometChatConfirmDialog,
  usePublishEvent,
  useCometChatEvents,
} from "@cometchat/chat-uikit-react";
import type { CometChatEvent } from "@cometchat/chat-uikit-react";

function ChatView({ targetUid }: { targetUid: string }) {
  const [user, setUser] = useState<CometChat.User | null>(null);
  const [isBlocked, setIsBlocked] = useState(false);
  const [showBlockDialog, setShowBlockDialog] = useState(false);
  const publish = usePublishEvent();

  useEffect(() => {
    async function fetchUser() {
      try {
        const fetchedUser = await CometChat.getUser(targetUid);
        setUser(fetchedUser);
        setIsBlocked(fetchedUser.getBlockedByMe());
      } catch (error) {
        console.error("Error fetching user:", error);
      }
    }
    fetchUser();
  }, [targetUid]);

  useCometChatEvents(
    (event: CometChatEvent) => {
      if (!user) return;
      if (event.type === "ui:user/blocked" && event.user.getUid() === user.getUid()) {
        setIsBlocked(true);
      }
      if (event.type === "ui:user/unblocked" && event.user.getUid() === user.getUid()) {
        setIsBlocked(false);
      }
    },
    [user?.getUid()]
  );

  async function handleBlock() {
    if (!user) return;
    try {
      await CometChat.blockUsers([user.getUid()]);
      user.setBlockedByMe(true);
      setIsBlocked(true);
      setShowBlockDialog(false);
      publish({ type: "ui:user/blocked", user });
    } catch (error) {
      console.error("Error blocking user:", error);
    }
  }

  async function handleUnblock() {
    if (!user) return;
    try {
      await CometChat.unblockUsers([user.getUid()]);
      user.setBlockedByMe(false);
      setIsBlocked(false);
      publish({ type: "ui:user/unblocked", user });
    } catch (error) {
      console.error("Error unblocking user:", error);
    }
  }

  if (!user) return <div>Loading...</div>;

  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
      {/* Confirmation dialog */}
      {showBlockDialog && (
        <CometChatConfirmDialog.Root isOpen={true} onClose={() => setShowBlockDialog(false)}>
          <CometChatConfirmDialog.Icon />
          <CometChatConfirmDialog.Content
            title="Block Contact"
            messageText="Are you sure you want to block this user? They won't be able to send you messages."
          />
          <CometChatConfirmDialog.Actions
            confirmButtonText="Block"
            onConfirm={handleBlock}
            onCancel={() => setShowBlockDialog(false)}
          />
        </CometChatConfirmDialog.Root>
      )}

      {/* Header with block/unblock action */}
      <CometChatMessageHeader
        user={user}
        auxiliaryButtonView={
          <button
            onClick={isBlocked ? handleUnblock : () => setShowBlockDialog(true)}
            style={{ background: "none", border: "none", cursor: "pointer", fontSize: "14px", color: isBlocked ? "#3399ff" : "#f44336" }}
          >
            {isBlocked ? "Unblock" : "Block"}
          </button>
        }
      />

      {/* Message list */}
      <div style={{ flex: 1, overflow: "hidden" }}>
        <CometChatMessageList user={user} />
      </div>

      {/* Composer or blocked prompt */}
      {!isBlocked ? (
        <CometChatMessageComposer user={user} />
      ) : (
        <div style={{ padding: "16px", textAlign: "center", background: "#f5f5f5" }}>
          <p>Cannot send a message to a blocked user.</p>
          <span
            onClick={handleUnblock}
            role="button"
            tabIndex={0}
            style={{ color: "#3399ff", cursor: "pointer" }}
          >
            Click to unblock.
          </span>
        </div>
      )}
    </div>
  );
}

function App() {
  return (
    <CometChatProvider>
      <ChatView targetUid="user-to-chat-with" />
    </CometChatProvider>
  );
}

export default App;
```

## Next Steps

* [Message Composer](/docs/ui-kit/react/components/message-composer) — learn about composer customization
* [Conversations](/docs/ui-kit/react/components/conversations) — build a full conversations list
* [CometChatProvider](/docs/ui-kit/react/cometchat-provider) — configure the root provider


# Group Chat Setup
Source: https://www.cometchat.com/docs/ui-kit/react/guide-group-chat-setup

Create and join group conversations with a full messaging interface using CometChat UI Kit components.

## Goal

By the end of this guide you will have a working group chat interface where users can create a new group, add members, and exchange messages in real time using the CometChat compound components.

## Prerequisites

* Completed the [Integration Guide](/docs/ui-kit/react/integration-react) guide
* A running `CometChatProvider` setup with valid credentials
* Familiarity with the [Conversations](/docs/ui-kit/react/components/conversations) and [Message List](/docs/ui-kit/react/components/message-list) components

## Components Used

| Component / API                 | Purpose                                       |
| :------------------------------ | :-------------------------------------------- |
| `CometChatConversations`        | Lists existing conversations including groups |
| `CometChatMessageHeader`        | Displays group name, avatar, and member count |
| `CometChatMessageList`          | Renders group messages in real time           |
| `CometChatMessageComposer`      | Text input for sending messages to the group  |
| `CometChat.createGroup()`       | SDK method to create a new group              |
| `CometChat.joinGroup()`         | SDK method to join an existing group          |
| `CometChat.addMembersToGroup()` | SDK method to add members                     |

## Step 1: Set up the app shell

Wrap your application in `CometChatProvider` and create a layout with a sidebar for conversations and a main area for messages.

```tsx App.tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatProvider } from "@cometchat/chat-uikit-react";
import { GroupChat } from "./GroupChat";

function App() {
  return (
    <CometChatProvider>
      <GroupChat />
    </CometChatProvider>
  );
}

export default App;
```

## Step 2: Create a new group

Use `CometChat.createGroup()` to programmatically create a group. You need a unique GUID, a name, and a group type (public, private, or password-protected).

```tsx theme={null}
async function createGroup() {
  const group = new CometChat.Group(
    "group-" + Date.now(), // unique GUID
    "My Team Chat",        // group name
    CometChat.GROUP_TYPE.PUBLIC // public, private, or password
  );

  try {
    const createdGroup = await CometChat.createGroup(group);
    console.log("Group created:", createdGroup.getName());
    return createdGroup;
  } catch (error) {
    console.error("Group creation failed:", error);
  }
}
```

## Step 3: Add members to the group

After creating a group, add members using `CometChat.addMembersToGroup()`. Each member needs a UID and a scope (admin, moderator, or participant).

```tsx theme={null}
async function addMembers(guid: string, memberUids: string[]) {
  const members = memberUids.map(
    (uid) =>
      new CometChat.GroupMember(uid, CometChat.GROUP_MEMBER_SCOPE.PARTICIPANT)
  );

  try {
    const response = await CometChat.addMembersToGroup(guid, members, []);
    console.log("Members added:", response);
  } catch (error) {
    console.error("Failed to add members:", error);
  }
}
```

## Step 4: Join an existing group

For public groups, users can join without an invite using `CometChat.joinGroup()`.

```tsx theme={null}
async function joinGroup(guid: string) {
  try {
    const group = await CometChat.joinGroup(guid, CometChat.GROUP_TYPE.PUBLIC);
    console.log("Joined group:", group.getName());
    return group;
  } catch (error) {
    console.error("Failed to join group:", error);
  }
}
```

## Step 5: Display conversations and select a group

Use `CometChatConversations` to show the user's conversations. When a group conversation is selected, pass the group object to the message components.

```tsx theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react";

function GroupChat() {
  const [activeGroup, setActiveGroup] = useState<CometChat.Group | null>(null);

  function handleConversationClick(conversation: CometChat.Conversation) {
    const entity = conversation.getConversationWith();
    if (entity instanceof CometChat.Group) {
      setActiveGroup(entity);
    }
  }

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: "320px", borderRight: "1px solid #e0e0e0" }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>
      <div style={{ flex: 1 }}>
        {activeGroup && <GroupMessageView group={activeGroup} />}
      </div>
    </div>
  );
}
```

## Step 6: Render the group message view

Combine `CometChatMessageList` and `CometChatMessageComposer` to display messages and allow sending within the selected group.

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

function GroupMessageView({ group }: { group: CometChat.Group }) {
  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
      <CometChatMessageHeader group={group} />

      <div style={{ flex: 1, overflow: "hidden" }}>
        <CometChatMessageList group={group} />
      </div>

      <CometChatMessageComposer group={group} />
    </div>
  );
}
```

## Step 7: Add a create-group form

Provide a simple UI for users to create groups on the fly. Wire it to the `createGroup` function from Step 2.

```tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function CreateGroupForm({ onCreate }: { onCreate: (group: CometChat.Group) => void }) {
  const [name, setName] = useState("");
  const [type, setType] = useState<string>(CometChat.GROUP_TYPE.PUBLIC);

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    if (!name.trim()) return;

    const group = new CometChat.Group(
      "group-" + Date.now(),
      name.trim(),
      type as typeof CometChat.GROUP_TYPE.PUBLIC
    );

    try {
      const createdGroup = await CometChat.createGroup(group);
      onCreate(createdGroup);
      setName("");
    } catch (error) {
      console.error("Group creation failed:", error);
    }
  }

  return (
    <form onSubmit={handleSubmit} style={{ padding: "12px" }}>
      <input
        value={name}
        onChange={(e) => setName(e.target.value)}
        placeholder="Group name"
        style={{ width: "100%", marginBottom: "8px", padding: "8px" }}
      />
      <select
        value={type}
        onChange={(e) => setType(e.target.value)}
        style={{ width: "100%", marginBottom: "8px", padding: "8px" }}
      >
        <option value={CometChat.GROUP_TYPE.PUBLIC}>Public</option>
        <option value={CometChat.GROUP_TYPE.PRIVATE}>Private</option>
        <option value={CometChat.GROUP_TYPE.PASSWORD}>Password Protected</option>
      </select>
      <button type="submit" style={{ width: "100%", padding: "8px" }}>
        Create Group
      </button>
    </form>
  );
}
```

## Complete Example

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

function CreateGroupForm({ onCreate }: { onCreate: (group: CometChat.Group) => void }) {
  const [name, setName] = useState("");
  const [type, setType] = useState<string>(CometChat.GROUP_TYPE.PUBLIC);

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    if (!name.trim()) return;

    const group = new CometChat.Group(
      "group-" + Date.now(),
      name.trim(),
      type as typeof CometChat.GROUP_TYPE.PUBLIC
    );

    try {
      const createdGroup = await CometChat.createGroup(group);
      onCreate(createdGroup);
      setName("");
    } catch (error) {
      console.error("Group creation failed:", error);
    }
  }

  return (
    <form onSubmit={handleSubmit} style={{ padding: "12px" }}>
      <input
        value={name}
        onChange={(e) => setName(e.target.value)}
        placeholder="Group name"
        style={{ width: "100%", marginBottom: "8px", padding: "8px" }}
      />
      <select
        value={type}
        onChange={(e) => setType(e.target.value)}
        style={{ width: "100%", marginBottom: "8px", padding: "8px" }}
      >
        <option value={CometChat.GROUP_TYPE.PUBLIC}>Public</option>
        <option value={CometChat.GROUP_TYPE.PRIVATE}>Private</option>
        <option value={CometChat.GROUP_TYPE.PASSWORD}>Password Protected</option>
      </select>
      <button type="submit" style={{ width: "100%", padding: "8px" }}>
        Create Group
      </button>
    </form>
  );
}

function GroupMessageView({ group }: { group: CometChat.Group }) {
  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
      <CometChatMessageHeader group={group} />

      <div style={{ flex: 1, overflow: "hidden" }}>
        <CometChatMessageList group={group} />
      </div>

      <CometChatMessageComposer group={group} />
    </div>
  );
}

function GroupChat() {
  const [activeGroup, setActiveGroup] = useState<CometChat.Group | null>(null);
  const [showCreateForm, setShowCreateForm] = useState(false);

  function handleConversationClick(conversation: CometChat.Conversation) {
    const entity = conversation.getConversationWith();
    if (entity instanceof CometChat.Group) {
      setActiveGroup(entity);
    }
  }

  function handleGroupCreated(group: CometChat.Group) {
    setActiveGroup(group);
    setShowCreateForm(false);
  }

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: "320px", borderRight: "1px solid #e0e0e0", display: "flex", flexDirection: "column" }}>
        <div style={{ padding: "8px", borderBottom: "1px solid #e0e0e0" }}>
          <button
            onClick={() => setShowCreateForm(!showCreateForm)}
            style={{ width: "100%", padding: "8px" }}
          >
            {showCreateForm ? "Cancel" : "New Group"}
          </button>
        </div>

        {showCreateForm && <CreateGroupForm onCreate={handleGroupCreated} />}

        <div style={{ flex: 1, overflow: "hidden" }}>
          <CometChatConversations onItemClick={handleConversationClick} />
        </div>
      </div>

      <div style={{ flex: 1 }}>
        {activeGroup ? (
          <GroupMessageView group={activeGroup} />
        ) : (
          <div style={{ display: "flex", alignItems: "center", justifyContent: "center", height: "100%" }}>
            <p>Select a group conversation or create a new group</p>
          </div>
        )}
      </div>
    </div>
  );
}

function App() {
  return (
    <CometChatProvider>
      <GroupChat />
    </CometChatProvider>
  );
}

export default App;
```

## Next Steps

* [Groups](/docs/ui-kit/react/components/groups) — browse and join existing groups
* [Group Members](/docs/ui-kit/react/components/group-members) — manage group membership
* [Message Header](/docs/ui-kit/react/components/message-header) — customize the group header
* [CometChatProvider](/docs/ui-kit/react/cometchat-provider) — configure the root provider


# Message Privately
Source: https://www.cometchat.com/docs/ui-kit/react/guide-message-privately

Let users send a private one-on-one message to another user directly from within a group chat conversation.

## Goal

By the end of this guide you will have a group chat interface where users can select a group member and open a private one-on-one conversation with them — without leaving the current screen. This is useful for side conversations, follow-ups, or sensitive messages that shouldn't be shared with the entire group.

## Prerequisites

* Completed the [Integration Guide](/docs/ui-kit/react/integration-react) guide
* A running `CometChatProvider` setup with valid credentials
* An existing group chat screen using `CometChatMessageList` and `CometChatMessageComposer`

## Components Used

| Component / API            | Purpose                                                                                      |
| :------------------------- | :------------------------------------------------------------------------------------------- |
| `CometChatMessageList`     | Displays group messages (publishes `ui:open-chat` internally via "Message Privately" option) |
| `CometChatMessageComposer` | Text input for the private conversation                                                      |
| `CometChatMessageHeader`   | Displays user/group info                                                                     |
| `useCometChatEvents`       | Subscribe to `ui:open-chat` event                                                            |
| `ui:open-chat`             | UI event published when user clicks "Message Privately"                                      |

## Step 1: Set up the main layout with provider

Start with a layout that includes a conversations sidebar and a main chat area wrapped in `CometChatProvider`.

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

function App() {
  return (
    <CometChatProvider>
      <ChatWithPrivateMessaging />
    </CometChatProvider>
  );
}

export default App;
```

## Step 2: Track group and private chat state

Maintain state for the active group conversation and a separate state for the private user when a user initiates a private message.

```tsx ChatWithPrivateMessaging.tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function ChatWithPrivateMessaging() {
  const [user, setUser] = useState<CometChat.User | null>(null);
  const [group, setGroup] = useState<CometChat.Group | null>(null);
  const [privateUser, setPrivateUser] = useState<CometChat.User | null>(null);

  // ... continued in next steps
}
```

## Step 3: Handle conversation selection

Connect `CometChatConversations` to switch between user and group chats. When switching conversations, close any open private message panel.

```tsx theme={null}
function handleConversationClick(conversation: CometChat.Conversation) {
  setPrivateUser(null); // close private panel on conversation switch

  const entity = conversation.getConversationWith();
  if (entity instanceof CometChat.User) {
    setUser(entity);
    setGroup(null);
  } else if (entity instanceof CometChat.Group) {
    setGroup(entity);
    setUser(null);
  }
}
```

## Step 4: Initiate a private message from a group member

Use the message header or a custom action to let users pick a group member for private messaging. You can fetch the user from a member click event or from the message sender's info.

```tsx theme={null}
async function handleMessagePrivately(uid: string) {
  try {
    const targetUser = await CometChat.getUser(uid);
    setPrivateUser(targetUser);
  } catch (error) {
    console.error("Failed to fetch user for private messaging:", error);
  }
}
```

## Step 5: Listen for the `ui:open-chat` event

Use `useCometChatEvents` to subscribe to the `ui:open-chat` event, which is published internally when a user clicks "Message Privately" from the context menu. When the event fires, extract the user and open the private panel.

```tsx theme={null}
import { useCometChatEvents } from "@cometchat/chat-uikit-react";
import type { CometChatEvent } from "@cometchat/chat-uikit-react";

useCometChatEvents(
  (event: CometChatEvent) => {
    if (event.type === "ui:open-chat" && event.user) {
      setPrivateUser(event.user);
    }
  },
  [group?.getGuid()]
);
```

## Step 6: Render the private message panel

When `privateUser` is set, show a side panel with a private one-on-one chat. This panel includes a header, message list, and composer scoped to the private user.

```tsx theme={null}
{privateUser && (
  <div style={{ width: "400px", borderLeft: "1px solid #e0e0e0", display: "flex", flexDirection: "column" }}>
    <div style={{ display: "flex", alignItems: "center", padding: "12px", borderBottom: "1px solid #e0e0e0" }}>
      <span style={{ flex: 1, fontWeight: 600 }}>
        Private: {privateUser.getName()}
      </span>
      <button onClick={() => setPrivateUser(null)}>✕</button>
    </div>

    <div style={{ flex: 1, overflow: "hidden" }}>
      <CometChatMessageList user={privateUser} />
    </div>

    <CometChatMessageComposer user={privateUser} />
  </div>
)}
```

## Step 7: Handle edge cases

Consider these scenarios when implementing private messaging from a group:

| Scenario                   | Behavior                                                                    |
| :------------------------- | :-------------------------------------------------------------------------- |
| User messages themselves   | Disable the private message option for the logged-in user's own messages    |
| User is blocked            | Check `getBlockedByMe()` before opening the private panel and show a prompt |
| Private panel already open | Replace the current private user with the newly selected one                |
| Group conversation changes | Close the private panel when switching to a different conversation          |

## Complete Example

```tsx App.tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatConversations,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatMessageHeader,
  useCometChatEvents,
} from "@cometchat/chat-uikit-react";
import type { CometChatEvent } from "@cometchat/chat-uikit-react";

function ChatWithPrivateMessaging() {
  const [user, setUser] = useState<CometChat.User | null>(null);
  const [group, setGroup] = useState<CometChat.Group | null>(null);
  const [privateUser, setPrivateUser] = useState<CometChat.User | null>(null);

  function handleConversationClick(conversation: CometChat.Conversation) {
    setPrivateUser(null);
    const entity = conversation.getConversationWith();
    if (entity instanceof CometChat.User) {
      setUser(entity);
      setGroup(null);
    } else if (entity instanceof CometChat.Group) {
      setGroup(entity);
      setUser(null);
    }
  }

  async function handleMessagePrivately(uid: string) {
    try {
      const targetUser = await CometChat.getUser(uid);
      setPrivateUser(targetUser);
    } catch (error) {
      console.error("Failed to fetch user for private messaging:", error);
    }
  }

  useCometChatEvents(
    (event: CometChatEvent) => {
      if (event.type === "ui:open-chat" && event.user) {
        setPrivateUser(event.user);
      }
    },
    [group?.getGuid()]
  );

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      {/* Conversations sidebar */}
      <div style={{ width: "300px", borderRight: "1px solid #e0e0e0" }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>

      {/* Main chat panel */}
      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        {(user || group) && (
          <>
            <CometChatMessageHeader user={user ?? undefined} group={group ?? undefined} />
            <div style={{ flex: 1, overflow: "hidden" }}>
              <CometChatMessageList
                user={user ?? undefined}
                group={group ?? undefined}
              />
            </div>
            <CometChatMessageComposer user={user ?? undefined} group={group ?? undefined} />
          </>
        )}
      </div>

      {/* Private message panel */}
      {privateUser && (
        <div style={{ width: "400px", borderLeft: "1px solid #e0e0e0", display: "flex", flexDirection: "column" }}>
          <div style={{ display: "flex", alignItems: "center", padding: "12px", borderBottom: "1px solid #e0e0e0" }}>
            <span style={{ flex: 1, fontWeight: 600 }}>
              Private: {privateUser.getName()}
            </span>
            <button onClick={() => setPrivateUser(null)}>✕</button>
          </div>

          <div style={{ flex: 1, overflow: "hidden" }}>
            <CometChatMessageList user={privateUser} />
          </div>

          <CometChatMessageComposer user={privateUser} />
        </div>
      )}
    </div>
  );
}

function App() {
  return (
    <CometChatProvider>
      <ChatWithPrivateMessaging />
    </CometChatProvider>
  );
}

export default App;
```

## Next Steps

* [Message Composer](/docs/ui-kit/react/components/message-composer) — customize the composer for private chats
* [Conversations](/docs/ui-kit/react/components/conversations) — manage the conversations list
* [Users](/docs/ui-kit/react/components/users) — browse and select users directly
* [CometChatProvider](/docs/ui-kit/react/cometchat-provider) — learn about provider configuration


# New Chat Creation
Source: https://www.cometchat.com/docs/ui-kit/react/guide-new-chat-creation

Start new one-on-one or group conversations by selecting users or groups from a list.

## Goal

By the end of this guide you will have a chat interface where users can initiate new one-on-one conversations by selecting from a user list, or start group chats by selecting from available groups — then immediately begin messaging.

## Prerequisites

* Completed the [Integration Guide](/docs/ui-kit/react/integration-react) guide
* A running `CometChatProvider` setup with valid credentials
* Familiarity with [CometChatUsers](/docs/ui-kit/react/components/users) and [CometChatGroups](/docs/ui-kit/react/components/groups) components

## Components Used

| Component / API            | Purpose                                         |
| :------------------------- | :---------------------------------------------- |
| `CometChatUsers`           | Lists available users for 1:1 chat selection    |
| `CometChatGroups`          | Lists available groups for group chat selection |
| `CometChatConversations`   | Shows existing conversations                    |
| `CometChatMessageHeader`   | Displays selected user/group info               |
| `CometChatMessageList`     | Renders conversation messages                   |
| `CometChatMessageComposer` | Text input for the conversation                 |
| `CometChat.joinGroup()`    | SDK method to join a group                      |

## Step 1: Set up the app shell

Wrap your application in `CometChatProvider` and create a layout that will hold the conversation area and a trigger for starting new chats.

```tsx App.tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatProvider } from "@cometchat/chat-uikit-react";
import { NewChatApp } from "./NewChatApp";

function App() {
  return (
    <CometChatProvider>
      <NewChatApp />
    </CometChatProvider>
  );
}

export default App;
```

## Step 2: Add a "New Chat" trigger

Create a button that opens a selection panel. Use component state to toggle between the conversations view and the user/group selection view.

```tsx NewChatApp.tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatConversations } from "@cometchat/chat-uikit-react";

type ChatTarget =
  | { type: "user"; entity: CometChat.User }
  | { type: "group"; entity: CometChat.Group };

function NewChatApp() {
  const [showNewChat, setShowNewChat] = useState(false);
  const [activeChat, setActiveChat] = useState<ChatTarget | null>(null);

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: "320px", borderRight: "1px solid #e0e0e0", display: "flex", flexDirection: "column" }}>
        <div style={{ padding: "8px", borderBottom: "1px solid #e0e0e0" }}>
          <button
            onClick={() => setShowNewChat(!showNewChat)}
            style={{ width: "100%", padding: "8px" }}
          >
            {showNewChat ? "Cancel" : "New Chat"}
          </button>
        </div>

        {showNewChat ? (
          <UserGroupSelector
            onSelectUser={(user) => {
              setActiveChat({ type: "user", entity: user });
              setShowNewChat(false);
            }}
            onSelectGroup={(group) => {
              setActiveChat({ type: "group", entity: group });
              setShowNewChat(false);
            }}
          />
        ) : (
          <div style={{ flex: 1, overflow: "hidden" }}>
            <CometChatConversations
              onItemClick={(conversation) => {
                const entity = conversation.getConversationWith();
                if (entity instanceof CometChat.User) {
                  setActiveChat({ type: "user", entity });
                } else if (entity instanceof CometChat.Group) {
                  setActiveChat({ type: "group", entity });
                }
              }}
            />
          </div>
        )}
      </div>

      <div style={{ flex: 1 }}>
        {activeChat ? (
          <ChatView target={activeChat} />
        ) : (
          <div style={{ display: "flex", alignItems: "center", justifyContent: "center", height: "100%" }}>
            <p>Select a conversation or start a new chat</p>
          </div>
        )}
      </div>
    </div>
  );
}
```

## Step 3: Build the user/group selector

Use `CometChatUsers` and `CometChatGroups` to let the user pick a chat target. Add tabs to switch between users and groups.

```tsx UserGroupSelector.tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatUsers, CometChatGroups } from "@cometchat/chat-uikit-react";

function UserGroupSelector({
  onSelectUser,
  onSelectGroup,
}: {
  onSelectUser: (user: CometChat.User) => void;
  onSelectGroup: (group: CometChat.Group) => void;
}) {
  const [tab, setTab] = useState<"users" | "groups">("users");

  return (
    <div style={{ display: "flex", flexDirection: "column", flex: 1, overflow: "hidden" }}>
      <div style={{ display: "flex", borderBottom: "1px solid #e0e0e0" }}>
        <button
          onClick={() => setTab("users")}
          style={{
            flex: 1,
            padding: "8px",
            fontWeight: tab === "users" ? "bold" : "normal",
          }}
        >
          Users
        </button>
        <button
          onClick={() => setTab("groups")}
          style={{
            flex: 1,
            padding: "8px",
            fontWeight: tab === "groups" ? "bold" : "normal",
          }}
        >
          Groups
        </button>
      </div>

      <div style={{ flex: 1, overflow: "hidden" }}>
        {tab === "users" ? (
          <CometChatUsers onItemClick={onSelectUser} />
        ) : (
          <CometChatGroups onItemClick={onSelectGroup} />
        )}
      </div>
    </div>
  );
}
```

## Step 4: Start a one-on-one conversation

When a user is selected from the list, pass the `CometChat.User` object to `CometChatMessageList` and `CometChatMessageComposer`. The SDK automatically creates the conversation when the first message is sent — no explicit creation step is needed.

```tsx ChatView.tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatMessageHeader,
} from "@cometchat/chat-uikit-react";

type ChatTarget =
  | { type: "user"; entity: CometChat.User }
  | { type: "group"; entity: CometChat.Group };

function ChatView({ target }: { target: ChatTarget }) {
  const userProp = target.type === "user" ? target.entity : undefined;
  const groupProp = target.type === "group" ? target.entity : undefined;

  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
      <CometChatMessageHeader user={userProp} group={groupProp} />

      <div style={{ flex: 1, overflow: "hidden" }}>
        <CometChatMessageList user={userProp} group={groupProp} />
      </div>

      <CometChatMessageComposer user={userProp} group={groupProp} />
    </div>
  );
}
```

## Step 5: Start a group conversation

For groups, the flow is the same — select a group from `CometChatGroups` and pass the `CometChat.Group` object to the message components. If the user hasn't joined the group yet, you can call `CometChat.joinGroup()` before opening the chat.

```tsx theme={null}
async function handleGroupSelect(group: CometChat.Group) {
  // For public groups, join if not already a member
  if (!group.getHasJoined()) {
    try {
      const joinedGroup = await CometChat.joinGroup(
        group.getGuid(),
        CometChat.GROUP_TYPE.PUBLIC
      );
      onSelectGroup(joinedGroup);
    } catch (error) {
      console.error("Failed to join group:", error);
    }
  } else {
    onSelectGroup(group);
  }
}
```

## Step 6: Send the first message programmatically (optional)

If you want to send an initial message when starting a new chat (for example, an icebreaker), use the SDK directly after selecting a user.

```tsx theme={null}
async function sendFirstMessage(uid: string, text: string) {
  const receiverType = CometChat.RECEIVER_TYPE.USER;
  const textMessage = new CometChat.TextMessage(uid, text, receiverType);

  try {
    const sentMessage = await CometChat.sendMessage(textMessage);
    console.log("Message sent:", sentMessage.getId());
  } catch (error) {
    console.error("Failed to send message:", error);
  }
}
```

## Complete Example

```tsx NewChatApp.tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatConversations,
  CometChatUsers,
  CometChatGroups,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatMessageHeader,
} from "@cometchat/chat-uikit-react";

type ChatTarget =
  | { type: "user"; entity: CometChat.User }
  | { type: "group"; entity: CometChat.Group };

function UserGroupSelector({
  onSelectUser,
  onSelectGroup,
}: {
  onSelectUser: (user: CometChat.User) => void;
  onSelectGroup: (group: CometChat.Group) => void;
}) {
  const [tab, setTab] = useState<"users" | "groups">("users");

  async function handleGroupSelect(group: CometChat.Group) {
    if (!group.getHasJoined()) {
      try {
        const joinedGroup = await CometChat.joinGroup(
          group.getGuid(),
          CometChat.GROUP_TYPE.PUBLIC
        );
        onSelectGroup(joinedGroup);
      } catch (error) {
        console.error("Failed to join group:", error);
      }
    } else {
      onSelectGroup(group);
    }
  }

  return (
    <div style={{ display: "flex", flexDirection: "column", flex: 1, overflow: "hidden" }}>
      <div style={{ display: "flex", borderBottom: "1px solid #e0e0e0" }}>
        <button
          onClick={() => setTab("users")}
          style={{
            flex: 1,
            padding: "8px",
            fontWeight: tab === "users" ? "bold" : "normal",
          }}
        >
          Users
        </button>
        <button
          onClick={() => setTab("groups")}
          style={{
            flex: 1,
            padding: "8px",
            fontWeight: tab === "groups" ? "bold" : "normal",
          }}
        >
          Groups
        </button>
      </div>

      <div style={{ flex: 1, overflow: "hidden" }}>
        {tab === "users" ? (
          <CometChatUsers onItemClick={onSelectUser} />
        ) : (
          <CometChatGroups onItemClick={handleGroupSelect} />
        )}
      </div>
    </div>
  );
}

function ChatView({ target }: { target: ChatTarget }) {
  const userProp = target.type === "user" ? target.entity : undefined;
  const groupProp = target.type === "group" ? target.entity : undefined;

  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
      <CometChatMessageHeader user={userProp} group={groupProp} />

      <div style={{ flex: 1, overflow: "hidden" }}>
        <CometChatMessageList user={userProp} group={groupProp} />
      </div>

      <CometChatMessageComposer user={userProp} group={groupProp} />
    </div>
  );
}

function NewChatApp() {
  const [showNewChat, setShowNewChat] = useState(false);
  const [activeChat, setActiveChat] = useState<ChatTarget | null>(null);

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: "320px", borderRight: "1px solid #e0e0e0", display: "flex", flexDirection: "column" }}>
        <div style={{ padding: "8px", borderBottom: "1px solid #e0e0e0" }}>
          <button
            onClick={() => setShowNewChat(!showNewChat)}
            style={{ width: "100%", padding: "8px" }}
          >
            {showNewChat ? "Cancel" : "New Chat"}
          </button>
        </div>

        {showNewChat ? (
          <UserGroupSelector
            onSelectUser={(user) => {
              setActiveChat({ type: "user", entity: user });
              setShowNewChat(false);
            }}
            onSelectGroup={(group) => {
              setActiveChat({ type: "group", entity: group });
              setShowNewChat(false);
            }}
          />
        ) : (
          <div style={{ flex: 1, overflow: "hidden" }}>
            <CometChatConversations
              onItemClick={(conversation) => {
                const entity = conversation.getConversationWith();
                if (entity instanceof CometChat.User) {
                  setActiveChat({ type: "user", entity });
                } else if (entity instanceof CometChat.Group) {
                  setActiveChat({ type: "group", entity });
                }
              }}
            />
          </div>
        )}
      </div>

      <div style={{ flex: 1 }}>
        {activeChat ? (
          <ChatView target={activeChat} />
        ) : (
          <div style={{ display: "flex", alignItems: "center", justifyContent: "center", height: "100%" }}>
            <p>Select a conversation or start a new chat</p>
          </div>
        )}
      </div>
    </div>
  );
}

function App() {
  return (
    <CometChatProvider>
      <NewChatApp />
    </CometChatProvider>
  );
}

export default App;
```

## Next Steps

* [CometChatUsers](/docs/ui-kit/react/components/users) — customize the user list appearance and filtering
* [CometChatGroups](/docs/ui-kit/react/components/groups) — browse and manage groups
* [Conversations](/docs/ui-kit/react/components/conversations) — display existing conversations
* [Group Chat Setup](/docs/ui-kit/react/guide-group-chat-setup) — create and configure group conversations


# Search Messages
Source: https://www.cometchat.com/docs/ui-kit/react/guide-search-messages

Add message search to your chat so users can find specific messages within a conversation using the built-in CometChatSearch component.

## Goal

By the end of this guide you will have a chat interface with a search panel that lets users find messages in a conversation by keyword and scroll to a selected result — using the built-in [`CometChatSearch`](/docs/ui-kit/react/components/search) component instead of building your own search UI.

`CometChatSearch` already handles the input, debouncing, SDK queries, result rendering, pagination, loading/empty/error states, and keyword highlighting — so you only wire it to your message list.

## Prerequisites

* Completed the [Integration Guide](/docs/ui-kit/react/integration-react)
* A running `CometChatProvider` setup with valid credentials
* An existing chat screen using `CometChatMessageList` and `CometChatMessageHeader`

## Components Used

| Component                | Purpose                                                                  |
| :----------------------- | :----------------------------------------------------------------------- |
| `CometChatSearch`        | Built-in search panel — input, message queries, result list, and states  |
| `CometChatMessageList`   | Displays messages and supports `goToMessageId` for scrolling to a result |
| `CometChatMessageHeader` | Header with a search trigger button                                      |
| `CometChatConversations` | Sidebar for switching conversations                                      |

## Step 1: Set up the chat layout with search state

Start with a full chat layout — a conversations sidebar, message panel, and state to control the search panel visibility and the message to jump to.

*File: App.tsx*

```tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatConversations,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatMessageHeader,
  CometChatSearch,
  type CometChatSearchMessageClickEvent,
} from "@cometchat/chat-uikit-react";

function ChatWithSearch() {
  const [user, setUser] = useState<CometChat.User | null>(null);
  const [group, setGroup] = useState<CometChat.Group | null>(null);
  const [showSearch, setShowSearch] = useState(false);
  const [goToMessageId, setGoToMessageId] = useState<number | undefined>(undefined);

  function handleConversationClick(conversation: CometChat.Conversation) {
    setShowSearch(false);
    setGoToMessageId(undefined);
    const entity = conversation.getConversationWith();
    if (entity instanceof CometChat.User) {
      setUser(entity);
      setGroup(null);
    } else if (entity instanceof CometChat.Group) {
      setGroup(entity);
      setUser(null);
    }
  }

  // Fired by CometChatSearch when a message result is clicked
  function handleMessageClick(event: CometChatSearchMessageClickEvent) {
    setGoToMessageId(event.message.getId());
  }

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      {/* Conversations sidebar */}
      <div style={{ width: "300px", borderRight: "1px solid #e0e0e0" }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>

      {/* Main message panel */}
      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        {(user || group) && (
          <>
            <CometChatMessageHeader
              user={user ?? undefined}
              group={group ?? undefined}
              auxiliaryButtonView={
                <button
                  onClick={() => setShowSearch((prev) => !prev)}
                  aria-label="Search messages"
                  style={{ background: "none", border: "none", cursor: "pointer", fontSize: "18px" }}
                >
                  🔍
                </button>
              }
            />
            <div style={{ flex: 1, overflow: "hidden" }}>
              <CometChatMessageList
                user={user ?? undefined}
                group={group ?? undefined}
                goToMessageId={goToMessageId}
              />
            </div>
            <CometChatMessageComposer user={user ?? undefined} group={group ?? undefined} />
          </>
        )}
      </div>

      {/* Built-in search panel, scoped to the open conversation */}
      {showSearch && (user || group) && (
        <div style={{ width: "350px", borderLeft: "1px solid #e0e0e0" }}>
          <CometChatSearch
            searchIn={["messages"]}
            uid={user?.getUid()}
            guid={group?.getGuid()}
            onMessageClicked={handleMessageClick}
            onBack={() => setShowSearch(false)}
          />
        </div>
      )}
    </div>
  );
}

function App() {
  return (
    <CometChatProvider>
      <ChatWithSearch />
    </CometChatProvider>
  );
}

export default App;
```

## Step 2: Scope CometChatSearch to the conversation

`CometChatSearch` is a complete, self-contained search panel — there's no custom input or result list to build. A few props tailor it to in-conversation message search:

```tsx theme={null}
<CometChatSearch
  searchIn={["messages"]}
  uid={user?.getUid()}
  guid={group?.getGuid()}
  onMessageClicked={handleMessageClick}
  onBack={() => setShowSearch(false)}
/>
```

| Prop                      | What it does                                                                                   |
| :------------------------ | :--------------------------------------------------------------------------------------------- |
| `searchIn={["messages"]}` | Shows only message results (omit it to also search conversations)                              |
| `uid` / `guid`            | Scopes the search to a single user or group conversation. Pass whichever matches the open chat |
| `onMessageClicked`        | Fired when a result is tapped. The event payload is `{ message, searchKeyword }`               |
| `onBack`                  | Fired when the back button is clicked — use it to close the panel                              |

The component handles the search input, debouncing, SDK queries, pagination, and the loading/empty/error states internally. For the full prop list and customization (filter chips, custom result item views, request builders), see the [Search component reference](/docs/ui-kit/react/components/search).

## Step 3: Navigate to a selected search result

When a result is clicked, `onMessageClicked` gives you the selected `message`. Pass its ID to `CometChatMessageList` via the `goToMessageId` prop — the list scrolls to the matching message and highlights it.

```tsx theme={null}
function handleMessageClick(event: CometChatSearchMessageClickEvent) {
  setGoToMessageId(event.message.getId());
}

<CometChatMessageList
  user={user ?? undefined}
  group={group ?? undefined}
  goToMessageId={goToMessageId}
/>
```

<Note>
  Reset `goToMessageId` to `undefined` when switching conversations (as in `handleConversationClick` above) so the list doesn't try to jump to a message ID from a previous chat.
</Note>

## Next Steps

* [Search](/docs/ui-kit/react/components/search) — full `CometChatSearch` reference: filters, scopes, custom result views, and request builders
* [Message List](/docs/ui-kit/react/components/message-list) — configure message rendering and scroll behavior
* [Message Header](/docs/ui-kit/react/components/message-header) — customize header actions and auxiliary views
* [Threaded Messages](/docs/ui-kit/react/guide-threaded-messages) — add threaded replies to your chat


# Threaded Messages
Source: https://www.cometchat.com/docs/ui-kit/react/guide-threaded-messages

Add threaded message replies to your chat so users can create focused sub-conversations on any message.

## Goal

By the end of this guide you will have a chat interface where users can open a thread panel from any message, view the parent message with its reply count, browse threaded replies, and send new replies — all using v7 compound components and a state-based approach (no custom events needed).

## Prerequisites

* Completed the [Integration Guide](/docs/ui-kit/react/integration-react) guide
* A running `CometChatProvider` setup with valid credentials
* An existing chat screen using `CometChatMessageList` and `CometChatMessageComposer`

## Components Used

| Component                  | Purpose                                                                                              |
| :------------------------- | :--------------------------------------------------------------------------------------------------- |
| `CometChatThreadHeader`    | Displays the parent message and reply count at the top of the thread panel                           |
| `CometChatMessageList`     | Renders threaded replies when given a `parentMessageId`                                              |
| `CometChatMessageComposer` | Sends replies into the thread with `parentMessageId`, `layout="compact"`, and `enableRichTextEditor` |

## Step 1: Thread State Management

Store the `threadedMessage` in state. When set, the thread panel renders. When cleared, it closes. This mirrors the pattern used in the sample app's `CometChatThreadPanel` component.

*File: ChatWithThreads.tsx*

```tsx theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function ChatWithThreads() {
  const [user, setUser] = useState<CometChat.User | null>(null);
  const [group, setGroup] = useState<CometChat.Group | null>(null);
  const [threadedMessage, setThreadedMessage] = useState<CometChat.BaseMessage | null>(null);

  // Thread opens when threadedMessage is set, closes when cleared
}
```

## Step 2: Wire the Thread Trigger

Use the `onThreadRepliesClick` callback on `CometChatMessageList` to capture when a user clicks "Reply in Thread." This sets the threaded message and opens the panel — no events required.

*File: ChatWithThreads.tsx*

```tsx theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react";

<CometChatMessageList
  user={user ?? undefined}
  group={group ?? undefined}
  onThreadRepliesClick={(message) => setThreadedMessage(message)}
/>
```

## Step 3: Build the Thread Panel

When `threadedMessage` is set, render a side panel composing `CometChatThreadHeader` + `CometChatMessageList` (with `parentMessageId`) + `CometChatMessageComposer` (with `parentMessageId`, `layout="compact"`, and `enableRichTextEditor`). The `onClose` callback clears the state to dismiss the panel.

*File: ChatWithThreads.tsx*

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

{threadedMessage && (
  <div style={{ width: "400px", borderLeft: "1px solid #e0e0e0", display: "flex", flexDirection: "column" }}>
    <CometChatThreadHeader
      parentMessage={threadedMessage}
      onClose={() => setThreadedMessage(null)}
      onParentDeleted={() => setThreadedMessage(null)}
    />

    <div style={{ flex: 1, overflow: "hidden" }}>
      <CometChatMessageList
        parentMessageId={threadedMessage.getId()}
        user={user ?? undefined}
        group={group ?? undefined}
      />
    </div>

    <CometChatMessageComposer
      parentMessageId={threadedMessage.getId()}
      user={user ?? undefined}
      group={group ?? undefined}
      layout="compact"
      enableRichTextEditor
    />
  </div>
)}
```

## Step 4: Handle Parent Deleted

Use the `onParentDeleted` prop on `CometChatThreadHeader` to automatically close the thread panel when the parent message is deleted by another user or a moderation action.

*File: ChatWithThreads.tsx*

```tsx theme={null}
<CometChatThreadHeader
  parentMessage={threadedMessage}
  onClose={() => setThreadedMessage(null)}
  onParentDeleted={() => setThreadedMessage(null)}
/>
```

## Complete Example

*File: App.tsx*

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

function ChatWithThreads() {
  const [user, setUser] = useState<CometChat.User | null>(null);
  const [group, setGroup] = useState<CometChat.Group | null>(null);
  const [threadedMessage, setThreadedMessage] = useState<CometChat.BaseMessage | null>(null);

  function handleConversationClick(conversation: CometChat.Conversation) {
    setThreadedMessage(null);
    const entity = conversation.getConversationWith();
    if (entity instanceof CometChat.User) {
      setUser(entity);
      setGroup(null);
    } else if (entity instanceof CometChat.Group) {
      setGroup(entity);
      setUser(null);
    }
  }

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      {/* Conversations sidebar */}
      <div style={{ width: "300px", borderRight: "1px solid #e0e0e0" }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>

      {/* Main message panel */}
      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        {(user || group) && (
          <>
            <CometChatMessageHeader user={user ?? undefined} group={group ?? undefined} />
            <div style={{ flex: 1, overflow: "hidden" }}>
              <CometChatMessageList
                user={user ?? undefined}
                group={group ?? undefined}
                onThreadRepliesClick={(message) => setThreadedMessage(message)}
              />
            </div>
            <CometChatMessageComposer user={user ?? undefined} group={group ?? undefined} />
          </>
        )}
      </div>

      {/* Thread panel */}
      {threadedMessage && (
        <div style={{ width: "400px", borderLeft: "1px solid #e0e0e0", display: "flex", flexDirection: "column" }}>
          <CometChatThreadHeader
            parentMessage={threadedMessage}
            onClose={() => setThreadedMessage(null)}
            onParentDeleted={() => setThreadedMessage(null)}
          />
          <div style={{ flex: 1, overflow: "hidden" }}>
            <CometChatMessageList
              parentMessageId={threadedMessage.getId()}
              user={user ?? undefined}
              group={group ?? undefined}
            />
          </div>
          <CometChatMessageComposer
            parentMessageId={threadedMessage.getId()}
            user={user ?? undefined}
            group={group ?? undefined}
            layout="compact"
            enableRichTextEditor
          />
        </div>
      )}
    </div>
  );
}

function App() {
  return (
    <CometChatProvider>
      <ChatWithThreads />
    </CometChatProvider>
  );
}

export default App;
```

## Next Steps

* [Thread Header](/docs/ui-kit/react/components/thread-header) — customize the thread header appearance
* [Message List](/docs/ui-kit/react/components/message-list) — configure message list rendering and options
* [CometChatProvider](/docs/ui-kit/react/cometchat-provider) — learn about provider configuration


# Astro Integration
Source: https://www.cometchat.com/docs/ui-kit/react/integration-astro

Add CometChat to an Astro app in 5 steps: create project, install, init + login, render island, run.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                                              |
  | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package          | `@cometchat/chat-uikit-react` v7.0.x                                                                                                               |
  | Peer deps        | `react` >=18, `react-dom` >=18, `@cometchat/chat-sdk-javascript` ^4.1.9, `dompurify` ^3.3.1                                                        |
  | Init             | `CometChatUIKit.init(UIKitSettings)` — must resolve before `login()`                                                                               |
  | Login            | `CometChatUIKit.login("UID")` — must resolve before rendering components                                                                           |
  | Order            | `init()` → `login()` → render `<CometChatProvider>`. Breaking this order = blank screen                                                            |
  | Auth Key         | Dev/testing only. Use Auth Token in production                                                                                                     |
  | SSR              | Use `client:only="react"` directive — CometChat components cannot be server-rendered                                                               |
  | Calling          | Optional. Install `@cometchat/calls-sdk-javascript` and call `.setCallingEnabled(true)` on `UIKitSettingsBuilder`                                  |
  | Other frameworks | [React.js](/docs/ui-kit/react/integration-react) · [Next.js](/docs/ui-kit/react/integration-nextjs) · [React Router](/docs/ui-kit/react/integration-react-router) |
</Accordion>

This guide walks you through adding CometChat to an Astro app using React islands. By the end you'll have a working chat UI.

<Frame>
  <img />
</Frame>

***

## Prerequisites

You need three things from the [CometChat Dashboard](https://app.cometchat.com/):

| Credential | Where to find it                                           |
| ---------- | ---------------------------------------------------------- |
| App ID     | Dashboard → Your App → Credentials                         |
| Auth Key   | Dashboard → Your App → Credentials                         |
| Region     | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) |

You also need **Node.js 18+** and npm/yarn installed.

<Warning>
  Auth Key is for development only. In production, generate Auth Tokens server-side via the REST API. Never ship Auth Keys in client code.
</Warning>

***

## Step 1 — Create an Astro Project

```bash theme={null}
npm create astro@latest my-app
cd my-app
npx astro add react
```

When prompted by `astro add react`, confirm the installation of `react`, `react-dom`, and `@astrojs/react`.

***

## Step 2 — Install the UI Kit

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript dompurify
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript dompurify
    ```
  </Tab>
</Tabs>

If you want voice/video calling, also install:

```bash theme={null}
npm install @cometchat/calls-sdk-javascript
```

***

## Step 3 — Create the React Island Component

CometChat components live inside a React island (a `.tsx` file in `src/components/`). Initialize the SDK, login, then render inside `CometChatProvider`.

For development, use one of the pre-created test UIDs:

`cometchat-uid-1` · `cometchat-uid-2` · `cometchat-uid-3` · `cometchat-uid-4` · `cometchat-uid-5`

```tsx title="src/components/CometChatApp.tsx" theme={null}
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
  CometChatProvider,
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

export default function CometChatApp() {
  const [ready, setReady] = useState(false);
  const [chatUser, setChatUser] = useState<CometChat.User | undefined>();
  const [chatGroup, setChatGroup] = useState<CometChat.Group | undefined>();

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      setReady(true);
    });
  }, []);

  if (!ready) return <div>Loading chat...</div>;

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setChatUser(entity as CometChat.User);
      setChatGroup(undefined);
    } else {
      setChatGroup(entity as CometChat.Group);
      setChatUser(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div style={{ display: "flex", height: "100vh" }}>
        <div style={{ width: 360, borderRight: "1px solid #eee" }}>
          <CometChatConversations onItemClick={handleConversationClick} />
        </div>
        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
          {(chatUser || chatGroup) && (
            <>
              <CometChatMessageHeader user={chatUser} group={chatGroup} />
              <CometChatMessageList user={chatUser} group={chatGroup} />
              <CometChatMessageComposer user={chatUser} group={chatGroup} />
            </>
          )}
        </div>
      </div>
    </CometChatProvider>
  );
}
```

`CometChatProvider` supplies theme, locale, plugin registry, and event context to all child components. Init and login happen in `useEffect` and the provider only mounts after login succeeds. See the [CometChatProvider](/docs/ui-kit/react/cometchat-provider) guide for all props.

<Note>
  For production, use `CometChatUIKit.loginWithAuthToken(token)` instead of `login(uid)`. Generate auth tokens server-side via the CometChat REST API. Never ship auth keys in client code.
</Note>

***

## Step 4 — Render the Island in an Astro Page

Create an Astro page that renders the React island with `client:only="react"`. This ensures the component only runs in the browser — no server-side rendering.

```astro title="src/pages/index.astro" theme={null}
---
import CometChatApp from '../components/CometChatApp.tsx';
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Chat App</title>
  </head>
  <body>
    <CometChatApp client:only="react" />
  </body>
</html>
```

<Warning>
  You must use `client:only="react"` — not `client:load` or `client:visible`. CometChat components use browser APIs (DOM, WebSocket) and cannot be server-rendered. Using `client:only` skips SSR entirely.
</Warning>

***

## Step 5 — Run

```bash theme={null}
npm run dev
```

Open `http://localhost:4321`. You should see the conversation list on the left. Click a conversation to open the message panel.

<Frame>
  <img />
</Frame>

***

## Choose a Chat Experience

### Conversation List + Message View

Two-panel layout — conversation list on the left, messages on the right.

<Frame>
  <img />
</Frame>

***

### One-to-One / Group Chat

Single chat window — no sidebar. Good for support chat or embedded widgets.

<Frame>
  <img />
</Frame>

***

### Tab-Based Chat

Tabbed navigation — Chat, Call Logs, Users, Settings in separate tabs.

<Frame>
  <img />
</Frame>

***

## Build Your Own Chat Experience

Need full control over the UI? Use individual components, customize themes, and wire up your own layouts.

* [Sample App](https://github.com/cometchat/cometchat-uikit-react/tree/v7/sample-app) — Working reference app to compare against
* [Components](/docs/ui-kit/react/components-overview) — All prebuilt UI elements with props and customization options
* [Core Features](/docs/ui-kit/react/core-features) — Messaging, real-time updates, and other capabilities
* [Theming](/docs/ui-kit/react/theming) — Colors, fonts, dark mode, and custom styling
* [Build Your Own UI](/docs/sdk/javascript/overview) — Skip the UI Kit entirely and build on the raw SDK

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and styles
  </Card>

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

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/react/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Next.js Integration
Source: https://www.cometchat.com/docs/ui-kit/react/integration-nextjs

Add CometChat to a Next.js (App Router) app in 5 steps: create project, install, init + login, render, run.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                                           |
  | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package          | `@cometchat/chat-uikit-react` v7.0.x                                                                                                            |
  | Peer deps        | `react` >=18, `react-dom` >=18, `@cometchat/chat-sdk-javascript` ^4.1.9, `dompurify` ^3.3.1                                                     |
  | Init             | `CometChatUIKit.init(UIKitSettings)` — must resolve before `login()`                                                                            |
  | Login            | `CometChatUIKit.login("UID")` — must resolve before rendering components                                                                        |
  | Order            | `init()` → `login()` → render `<CometChatProvider>`. Breaking this order = blank screen                                                         |
  | Auth Key         | Dev/testing only. Use `loginWithAuthToken` in production                                                                                        |
  | SSR              | CometChat components must be loaded with `dynamic(() => import(...), { ssr: false })`                                                           |
  | Calling          | Optional. Install `@cometchat/calls-sdk-javascript` and call `.setCallingEnabled(true)` on `UIKitSettingsBuilder`                               |
  | Other frameworks | [React.js](/docs/ui-kit/react/integration-react) · [React Router](/docs/ui-kit/react/integration-react-router) · [Astro](/docs/ui-kit/react/integration-astro) |
</Accordion>

This guide walks you through adding CometChat to a Next.js (App Router) app. By the end you'll have a working chat UI.

<Frame>
  <img />
</Frame>

***

## Prerequisites

You need three things from the [CometChat Dashboard](https://app.cometchat.com/):

| Credential | Where to find it                                           |
| ---------- | ---------------------------------------------------------- |
| App ID     | Dashboard → Your App → Credentials                         |
| Auth Key   | Dashboard → Your App → Credentials                         |
| Region     | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) |

You also need **Node.js 18+** and npm/yarn installed.

<Warning>
  Auth Key is for development only. In production, generate Auth Tokens server-side via the REST API. Never ship Auth Keys in client code.
</Warning>

***

## Step 1 — Create a Next.js Project

```bash theme={null}
npx create-next-app@latest my-app --typescript
cd my-app
```

When prompted, select **App Router** (the default in Next.js 14+).

***

## Step 2 — Install the UI Kit

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript dompurify
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript dompurify
    ```
  </Tab>
</Tabs>

If you want voice/video calling, also install:

```bash theme={null}
npm install @cometchat/calls-sdk-javascript
```

***

## Step 3 — Create the CometChat Client Component

CometChat uses browser APIs and cannot run in Server Components. Create a `'use client'` component that initializes the SDK, logs in, and renders your chat UI inside `CometChatProvider`.

For development, use one of the pre-created test UIDs:

`cometchat-uid-1` · `cometchat-uid-2` · `cometchat-uid-3` · `cometchat-uid-4` · `cometchat-uid-5`

```tsx title="app/CometChatClient.tsx" theme={null}
'use client';

import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
  CometChatProvider,
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

export default function CometChatClient() {
  const [ready, setReady] = useState(false);
  const [chatUser, setChatUser] = useState<CometChat.User | undefined>();
  const [chatGroup, setChatGroup] = useState<CometChat.Group | undefined>();

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      setReady(true);
    });
  }, []);

  if (!ready) return <div>Loading chat...</div>;

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setChatUser(entity as CometChat.User);
      setChatGroup(undefined);
    } else {
      setChatGroup(entity as CometChat.Group);
      setChatUser(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div style={{ display: "flex", height: "100vh" }}>
        <div style={{ width: 360, borderRight: "1px solid #eee" }}>
          <CometChatConversations onItemClick={handleConversationClick} />
        </div>
        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
          {(chatUser || chatGroup) && (
            <>
              <CometChatMessageHeader user={chatUser} group={chatGroup} />
              <CometChatMessageList user={chatUser} group={chatGroup} />
              <CometChatMessageComposer user={chatUser} group={chatGroup} />
            </>
          )}
        </div>
      </div>
    </CometChatProvider>
  );
}
```

`'use client'` is required because CometChat components use browser APIs. Init and login happen in a `useEffect`, and the provider only mounts after login succeeds. See the [CometChatProvider](/docs/ui-kit/react/cometchat-provider) guide for all provider props.

<Note>
  For production, use `CometChatUIKit.loginWithAuthToken(token)` instead of `login(uid)`. Generate auth tokens server-side via the CometChat REST API. Never ship auth keys in client code.
</Note>

***

## Step 4 — Import with SSR Disabled

In your page file, use `dynamic()` with `ssr: false` to prevent the CometChat component from rendering on the server.

```tsx title="app/page.tsx" theme={null}
import dynamic from 'next/dynamic';

const CometChatClient = dynamic(() => import('./CometChatClient'), { ssr: false });

export default function Home() {
  return <CometChatClient />;
}
```

<Warning>
  You must use `dynamic(() => import(...), { ssr: false })`. Without this, Next.js will attempt to render CometChat on the server, causing errors like `window is not defined` or `document is not defined`.
</Warning>

***

## Step 5 — Run

```bash theme={null}
npm run dev
```

Open `http://localhost:3000`. You should see the conversation list on the left. Click a conversation to open the message panel.

<Frame>
  <img />
</Frame>

***

## Choose a Chat Experience

### Conversation List + Message View

Two-panel layout — conversation list on the left, messages on the right.

<Frame>
  <img />
</Frame>

***

### One-to-One / Group Chat

Single chat window — no sidebar. Good for support chat or embedded widgets.

<Frame>
  <img />
</Frame>

***

### Tab-Based Chat

Tabbed navigation — Chat, Call Logs, Users, Settings in separate tabs.

<Frame>
  <img />
</Frame>

***

## Build Your Own Chat Experience

Need full control over the UI? Use individual components, customize themes, and wire up your own layouts.

* [Sample App](https://github.com/cometchat/cometchat-uikit-react/tree/v7/sample-app) — Working reference app to compare against
* [Components](/docs/ui-kit/react/components-overview) — All prebuilt UI elements with props and customization options
* [Core Features](/docs/ui-kit/react/core-features) — Messaging, real-time updates, and other capabilities
* [Theming](/docs/ui-kit/react/theming) — Colors, fonts, dark mode, and custom styling
* [Build Your Own UI](/docs/sdk/javascript/overview) — Skip the UI Kit entirely and build on the raw SDK

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and styles
  </Card>

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

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/react/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# React.js Integration
Source: https://www.cometchat.com/docs/ui-kit/react/integration-react

Add CometChat to a React.js app in 4 steps: create project, install, init + login, render.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                                           |
  | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package          | `@cometchat/chat-uikit-react` v7.0.x                                                                                                            |
  | Peer deps        | `react` >=18, `react-dom` >=18, `@cometchat/chat-sdk-javascript` ^4.1.9, `dompurify` ^3.3.1                                                     |
  | Init             | `CometChatUIKit.init(UIKitSettings)` — must resolve before `login()`                                                                            |
  | Login            | `CometChatUIKit.login("UID")` — must resolve before rendering components                                                                        |
  | Order            | `init()` → `login()` → render `<CometChatProvider>`. Breaking this order = blank screen                                                         |
  | Auth Key         | Dev/testing only. Use Auth Token in production                                                                                                  |
  | Calling          | Optional. Install `@cometchat/calls-sdk-javascript` and call `.setCallingEnabled(true)` on `UIKitSettingsBuilder`                               |
  | Other frameworks | [Next.js](/docs/ui-kit/react/integration-nextjs) · [React Router](/docs/ui-kit/react/integration-react-router) · [Astro](/docs/ui-kit/react/integration-astro) |
</Accordion>

This guide walks you through adding CometChat to a React.js app. By the end you'll have a working chat UI.

<Frame>
  <img />
</Frame>

***

## Prerequisites

You need three things from the [CometChat Dashboard](https://app.cometchat.com/):

| Credential | Where to find it                                           |
| ---------- | ---------------------------------------------------------- |
| App ID     | Dashboard → Your App → Credentials                         |
| Auth Key   | Dashboard → Your App → Credentials                         |
| Region     | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) |

You also need **Node.js 18+** and npm/yarn installed.

<Warning>
  Auth Key is for development only. In production, generate Auth Tokens server-side via the REST API. Never ship Auth Keys in client code.
</Warning>

***

## Step 1 — Create a React Project

<Tabs>
  <Tab title="Vite (recommended)">
    ```bash theme={null}
    npm create vite@latest my-app -- --template react-ts
    cd my-app
    ```
  </Tab>

  <Tab title="Create React App">
    ```bash theme={null}
    npx create-react-app my-app --template typescript
    cd my-app
    ```
  </Tab>
</Tabs>

***

## Step 2 — Install the UI Kit

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript dompurify
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript dompurify
    ```
  </Tab>
</Tabs>

If you want voice/video calling, also install:

```bash theme={null}
npm install @cometchat/calls-sdk-javascript
```

***

## Step 3 — Initialize, Login, and Render

Call `CometChatUIKit.init()` and `CometChatUIKit.login()` before rendering your app. Then wrap your components in `CometChatProvider`.

For development, use one of the pre-created test UIDs:

`cometchat-uid-1` · `cometchat-uid-2` · `cometchat-uid-3` · `cometchat-uid-4` · `cometchat-uid-5`

```tsx title="src/main.tsx" theme={null}
import ReactDOM from "react-dom/client";
import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";
import App from "./App";

const settings = new UIKitSettingsBuilder()
  .setAppId("YOUR_APP_ID")
  .setRegion("YOUR_REGION")
  .setAuthKey("YOUR_AUTH_KEY")
  .subscribePresenceForAllUsers()
  .build();

CometChatUIKit.init(settings).then(async () => {
  await CometChatUIKit.login("cometchat-uid-1");
  ReactDOM.createRoot(document.getElementById("root")!).render(<App />);
});
```

```tsx title="src/App.tsx" theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

function App() {
  const [chatUser, setChatUser] = useState<CometChat.User | undefined>();
  const [chatGroup, setChatGroup] = useState<CometChat.Group | undefined>();

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setChatUser(entity as CometChat.User);
      setChatGroup(undefined);
    } else {
      setChatGroup(entity as CometChat.Group);
      setChatUser(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div style={{ display: "flex", height: "100vh" }}>
        <div style={{ width: 360, borderRight: "1px solid #eee" }}>
          <CometChatConversations onItemClick={handleConversationClick} />
        </div>
        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
          {(chatUser || chatGroup) && (
            <>
              <CometChatMessageHeader user={chatUser} group={chatGroup} />
              <CometChatMessageList user={chatUser} group={chatGroup} />
              <CometChatMessageComposer user={chatUser} group={chatGroup} />
            </>
          )}
        </div>
      </div>
    </CometChatProvider>
  );
}

export default App;
```

`CometChatProvider` supplies theme, locale, plugin registry, and event context to all child components. Init and login must complete before the provider mounts. See the [CometChatProvider](/docs/ui-kit/react/cometchat-provider) guide for all props.

<Note>
  For production, use `CometChatUIKit.loginWithAuthToken(token)` instead of `login(uid)`. Generate auth tokens server-side via the [REST API](/docs/rest-api/chat-apis). Never ship auth keys in client code.
</Note>

<Note>
  By default, session data is stored in `localStorage`. To use `sessionStorage` instead, see [Setting Session Storage Mode](/docs/ui-kit/react/methods#setting-session-storage-mode).
</Note>

***

## Step 4 — Run

```bash theme={null}
npm run dev
```

Open `http://localhost:5173` (Vite) or `http://localhost:3000` (CRA). You should see the conversation list on the left. Click a conversation to open the message panel.

<Frame>
  <img />
</Frame>

***

## Choose a Chat Experience

### Conversation List + Message View

Two-panel layout — conversation list on the left, messages on the right.

<Frame>
  <img />
</Frame>

***

### One-to-One / Group Chat

Single chat window — no sidebar. Good for support chat or embedded widgets.

<Frame>
  <img />
</Frame>

***

### Tab-Based Chat

Tabbed navigation — Chat, Call Logs, Users, Settings in separate tabs.

<Frame>
  <img />
</Frame>

***

## Build Your Own Chat Experience

Need full control over the UI? Use individual components, customize themes, and wire up your own layouts.

* [Sample App](https://github.com/cometchat/cometchat-uikit-react/tree/v7/sample-app) — Working reference app to compare against
* [Components](/docs/ui-kit/react/components-overview) — All prebuilt UI elements with props and customization options
* [Core Features](/docs/ui-kit/react/core-features) — Messaging, real-time updates, and other capabilities
* [Theming](/docs/ui-kit/react/theming) — Colors, fonts, dark mode, and custom styling
* [Build Your Own UI](/docs/sdk/javascript/overview) — Skip the UI Kit entirely and build on the raw SDK

***

## iFrame Embedding

If your React app runs inside an `<iframe>`, wrap your tree in `CometChatFrameProvider` so dialogs and portals mount in the correct frame:

```tsx theme={null}
import { CometChatFrameProvider } from "@cometchat/chat-uikit-react";

<CometChatFrameProvider iframeId="cometchat-frame">
  <App />
</CometChatFrameProvider>
```

| Prop       | Type     | Description                                   |
| ---------- | -------- | --------------------------------------------- |
| `iframeId` | `string` | The DOM `id` of the target `<iframe>` element |

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and styles
  </Card>

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

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/react/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# React Router Integration
Source: https://www.cometchat.com/docs/ui-kit/react/integration-react-router

Add CometChat to a React Router app in 5 steps: create project, install, init + login, render, run.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                                |
  | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
  | Package          | `@cometchat/chat-uikit-react` v7.0.x                                                                                                 |
  | Peer deps        | `react` >=18, `react-dom` >=18, `@cometchat/chat-sdk-javascript` ^4.1.9, `dompurify` ^3.3.1                                          |
  | Init             | `CometChatUIKit.init(UIKitSettings)` — must resolve before `login()`                                                                 |
  | Login            | `CometChatUIKit.login("UID")` — must resolve before rendering components                                                             |
  | Order            | `init()` → `login()` → render `<CometChatProvider>`. Breaking this order = blank screen                                              |
  | Auth Key         | Dev/testing only. Use Auth Token in production                                                                                       |
  | SSR              | N/A — client-side SPA by default                                                                                                     |
  | Calling          | Optional. Install `@cometchat/calls-sdk-javascript` and call `.setCallingEnabled(true)` on `UIKitSettingsBuilder`                    |
  | Other frameworks | [React.js](/docs/ui-kit/react/integration-react) · [Next.js](/docs/ui-kit/react/integration-nextjs) · [Astro](/docs/ui-kit/react/integration-astro) |
</Accordion>

This guide walks you through adding CometChat to a React Router app. By the end you'll have a working chat UI with route-based navigation.

<Frame>
  <img />
</Frame>

***

## Prerequisites

You need three things from the [CometChat Dashboard](https://app.cometchat.com/):

| Credential | Where to find it                                           |
| ---------- | ---------------------------------------------------------- |
| App ID     | Dashboard → Your App → Credentials                         |
| Auth Key   | Dashboard → Your App → Credentials                         |
| Region     | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) |

You also need **Node.js 18+** and npm/yarn installed.

<Warning>
  Auth Key is for development only. In production, generate Auth Tokens server-side via the REST API. Never ship Auth Keys in client code.
</Warning>

***

## Step 1 — Create a React Project with React Router

```bash theme={null}
npm create vite@latest my-app -- --template react-ts
cd my-app
npm install react-router-dom
```

***

## Step 2 — Install the UI Kit

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript dompurify
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript dompurify
    ```
  </Tab>
</Tabs>

If you want voice/video calling, also install:

```bash theme={null}
npm install @cometchat/calls-sdk-javascript
```

***

## Step 3 — Initialize, Login, and Set Up Routes

Call `CometChatUIKit.init()` and `CometChatUIKit.login()` before rendering. Then wrap your chat route in `CometChatProvider`.

For development, use one of the pre-created test UIDs:

`cometchat-uid-1` · `cometchat-uid-2` · `cometchat-uid-3` · `cometchat-uid-4` · `cometchat-uid-5`

```tsx title="src/main.tsx" theme={null}
import ReactDOM from "react-dom/client";
import { BrowserRouter } from "react-router-dom";
import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";
import App from "./App";

const settings = new UIKitSettingsBuilder()
  .setAppId("YOUR_APP_ID")
  .setRegion("YOUR_REGION")
  .setAuthKey("YOUR_AUTH_KEY")
  .subscribePresenceForAllUsers()
  .build();

CometChatUIKit.init(settings).then(async () => {
  await CometChatUIKit.login("cometchat-uid-1");
  ReactDOM.createRoot(document.getElementById("root")!).render(
    <BrowserRouter>
      <App />
    </BrowserRouter>
  );
});
```

```tsx title="src/App.tsx" theme={null}
import { Routes, Route, Navigate } from "react-router-dom";
import ChatPage from "./pages/ChatPage";

function App() {
  return (
    <Routes>
      <Route path="/chat" element={<ChatPage />} />
      <Route path="*" element={<Navigate to="/chat" replace />} />
    </Routes>
  );
}

export default App;
```

```tsx title="src/pages/ChatPage.tsx" theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

export default function ChatPage() {
  const [chatUser, setChatUser] = useState<CometChat.User | undefined>();
  const [chatGroup, setChatGroup] = useState<CometChat.Group | undefined>();

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setChatUser(entity as CometChat.User);
      setChatGroup(undefined);
    } else {
      setChatGroup(entity as CometChat.Group);
      setChatUser(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div style={{ display: "flex", height: "100vh" }}>
        <div style={{ width: 360, borderRight: "1px solid #eee" }}>
          <CometChatConversations onItemClick={handleConversationClick} />
        </div>
        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
          {(chatUser || chatGroup) && (
            <>
              <CometChatMessageHeader user={chatUser} group={chatGroup} />
              <CometChatMessageList user={chatUser} group={chatGroup} />
              <CometChatMessageComposer user={chatUser} group={chatGroup} />
            </>
          )}
        </div>
      </div>
    </CometChatProvider>
  );
}
```

Init and login complete before the app renders. `CometChatProvider` then supplies theme, locale, plugin registry, and event context. See the [CometChatProvider](/docs/ui-kit/react/cometchat-provider) guide for all props.

<Note>
  For production, use `CometChatUIKit.loginWithAuthToken(token)` instead of `login(uid)`. Generate auth tokens server-side via the CometChat REST API. Never ship auth keys in client code.
</Note>

***

## Step 4 — Run

```bash theme={null}
npm run dev
```

Open `http://localhost:5173/chat`. You should see the conversation list on the left. Click a conversation to open the message panel.

<Frame>
  <img />
</Frame>

***

## Choose a Chat Experience

### Conversation List + Message View

Two-panel layout — conversation list on the left, messages on the right.

<Frame>
  <img />
</Frame>

***

### One-to-One / Group Chat

Single chat window — no sidebar. Good for support chat or embedded widgets.

<Frame>
  <img />
</Frame>

***

### Tab-Based Chat

Tabbed navigation — Chat, Call Logs, Users, Settings in separate tabs.

<Frame>
  <img />
</Frame>

***

## Build Your Own Chat Experience

Need full control over the UI? Use individual components, customize themes, and wire up your own layouts.

* [Sample App](https://github.com/cometchat/cometchat-uikit-react/tree/v7/sample-app) — Working reference app to compare against
* [Components](/docs/ui-kit/react/components-overview) — All prebuilt UI elements with props and customization options
* [Core Features](/docs/ui-kit/react/core-features) — Messaging, real-time updates, and other capabilities
* [Theming](/docs/ui-kit/react/theming) — Colors, fonts, dark mode, and custom styling
* [Build Your Own UI](/docs/sdk/javascript/overview) — Skip the UI Kit entirely and build on the raw SDK

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and styles
  </Card>

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

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/react/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Changelog
Source: https://www.cometchat.com/docs/ui-kit/react/link/changelog

Navigate to Changelog documentation.



# Figma Design
Source: https://www.cometchat.com/docs/ui-kit/react/link/figma

Navigate to Figma Design documentation.



# React Sample App
Source: https://www.cometchat.com/docs/ui-kit/react/link/sample

Navigate to React Sample App documentation.



# Localization
Source: https://www.cometchat.com/docs/ui-kit/react/localization

19 built-in languages with support for custom translations, fallback languages, and date/time formatting.

<Accordion title="AI Integration Quick Reference">
  | Field               | Value                                                                                            |
  | ------------------- | ------------------------------------------------------------------------------------------------ |
  | Locale prop         | `locale="fr"` on `CometChatProvider`                                                             |
  | Default             | `en-us`                                                                                          |
  | Languages           | 19 built-in: de, en-gb, en-us, es, fr, hi, hu, it, ja, ko, lt, ms, nl, pt, ru, sv, tr, zh, zh-tw |
  | Hook                | `useLocale()` → `{ getLocalizedString, language }`                                               |
  | Static access       | `CometChatLocalize.getSharedInstance()?.t(key)`                                                  |
  | Custom translations | Pass via `CometChatLocalize` constructor or `addTranslation()`                                   |
</Accordion>

## Overview

The UI Kit ships with translations for 19 languages. All user-facing text (button labels, status messages, timestamps, error messages) is resolved through translation keys. Set the `locale` prop on `CometChatProvider` to switch languages.

***

## Setting the Language

```tsx theme={null}
<CometChatProvider locale="fr">
  <MyChatApp />
</CometChatProvider>
```

***

## Supported Languages

| Code    | Language               |
| ------- | ---------------------- |
| `en-us` | English (US) — default |
| `en-gb` | English (UK)           |
| `de`    | German                 |
| `es`    | Spanish                |
| `fr`    | French                 |
| `hi`    | Hindi                  |
| `hu`    | Hungarian              |
| `it`    | Italian                |
| `ja`    | Japanese               |
| `ko`    | Korean                 |
| `lt`    | Lithuanian             |
| `ms`    | Malay                  |
| `nl`    | Dutch                  |
| `pt`    | Portuguese             |
| `ru`    | Russian                |
| `sv`    | Swedish                |
| `tr`    | Turkish                |
| `zh`    | Chinese (Simplified)   |
| `zh-tw` | Chinese (Traditional)  |

***

## Accessing Translations in Components

Use the `useLocale` hook:

```tsx theme={null}
import { useLocale } from "@cometchat/chat-uikit-react";

function MyComponent() {
  const { getLocalizedString, language } = useLocale();

  return <p>{getLocalizedString("message_deleted")}</p>;
  // Renders: "This message was deleted" (en-us)
  // Renders: "Ce message a été supprimé" (fr)
}
```

***

## Adding Custom Translations

Override or add translation keys for a language:

```tsx theme={null}
import { CometChatLocalize } from "@cometchat/chat-uikit-react";

const localize = CometChatLocalize.getSharedInstance();
localize?.addTranslation("en-us", {
  "custom_greeting": "Welcome to our chat!",
  "message_deleted": "Message removed",  // Override built-in key
});
```

***

## Fallback Language

If a key is not found in the current language, the system falls back to the fallback language (default: `en-us`). Configure via `CometChatLocalize`:

```tsx theme={null}
const localize = new CometChatLocalize({
  language: "fr",
  fallbackLanguage: "en-us",
});
```

***

## Date & Time Localization

Date formatting respects the locale. The `CometChatDate` component and all timestamp displays use locale-aware formatting:

* Relative time: "2 minutes ago", "il y a 2 minutes"
* Day names: "Monday", "Lundi"
* Date formats: "12/25/2024" (en-us), "25/12/2024" (en-gb)

***

## Static Access (Non-React Code)

For plugins and utilities that run outside React components:

```tsx theme={null}
import { CometChatLocalize } from "@cometchat/chat-uikit-react";

const t = CometChatLocalize.getSharedInstance()?.t;
const text = t?.("message_deleted") ?? "This message was deleted";
```

***

## Differences from v6

| v6                                    | v7                                        |
| ------------------------------------- | ----------------------------------------- |
| `CometChatLocalize.setLanguage("fr")` | `locale="fr"` prop on `CometChatProvider` |
| Global static state                   | React context via provider                |
| Manual init required                  | Provider handles locale context           |
| Same 19 languages                     | Same 19 languages                         |


# Methods
Source: https://www.cometchat.com/docs/ui-kit/react/methods

Static methods on CometChatUIKit for initialization, authentication, and message sending.

<Accordion title="AI Integration Quick Reference">
  | Field   | Value                                                                     |
  | ------- | ------------------------------------------------------------------------- |
  | Class   | `CometChatUIKit`                                                          |
  | Package | `@cometchat/chat-uikit-react`                                             |
  | Usage   | Static methods — no instantiation needed                                  |
  | Note    | You must call `init()` and `login()` before rendering `CometChatProvider` |
</Accordion>

## Overview

`CometChatUIKit` is a static class that provides imperative methods for SDK initialization, authentication, and message sending. The UI Kit wraps the [Chat SDK](/docs/sdk/javascript/overview) methods to manage internal eventing and keep UI components synchronized. Use these wrapper methods instead of raw SDK calls.

You must call `CometChatUIKit.init()` and `CometChatUIKit.login()` (or `loginWithAuthToken()`) before mounting `CometChatProvider`. These methods are also useful for:

* Sending messages programmatically outside the composer
* Checking initialization/login state

***

## Initialization

### `CometChatUIKit.init(settings)`

Initialize the CometChat SDK and UIKit.

```tsx theme={null}
import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";

const settings = new UIKitSettingsBuilder()
  .setAppId("APP_ID")
  .setRegion("us")
  .setAuthKey("AUTH_KEY")
  .subscribePresenceForAllUsers()
  .build();

const user = await CometChatUIKit.init(settings);
// user is non-null if an existing session was found
```

| Parameter  | Type            | Description                      |
| ---------- | --------------- | -------------------------------- |
| `settings` | `UIKitSettings` | Built via `UIKitSettingsBuilder` |

**Returns:** `Promise<CometChat.User | null>` — the logged-in user if a session exists, otherwise null.

**What it does:**

1. Initializes the CometChat SDK with app settings
2. Sets source metadata for analytics
3. Creates the plugin registry (default + user plugins)
4. Initializes the localization singleton
5. Resumes existing session (if any)
6. Initializes Calls SDK (if enabled)

### Setting Session Storage Mode

By default, session data is stored in `localStorage`. To use `sessionStorage` instead, configure it during initialization via the `UIKitSettingsBuilder`:

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";

const settings = new UIKitSettingsBuilder()
  .setAppId("APP_ID")
  .setRegion("REGION")
  .setAuthKey("AUTH_KEY")
  .setStorageMode(CometChat.StorageMode.SESSION)
  .build();

CometChatUIKit.init(settings).then(() => {
  console.log("Initialization completed with session storage");
});
```

When using `sessionStorage`, configure it in your `UIKitSettingsBuilder` before calling `CometChatUIKit.init()`:

```tsx theme={null}
<CometChatProvider>
  <App />
</CometChatProvider>
```

<Note>
  Session storage is cleared when the browser tab is closed. Use this mode if you want users to re-authenticate on every new tab/session.
</Note>

***

## Authentication

### `CometChatUIKit.login(uid)`

Log in a user by UID. Requires `authKey` in UIKitSettings.

```tsx theme={null}
const user = await CometChatUIKit.login("superhero1");
```

| Parameter | Type     | Description    |
| --------- | -------- | -------------- |
| `uid`     | `string` | The user's UID |

**Returns:** `Promise<CometChat.User>`

### `CometChatUIKit.loginWithAuthToken(authToken)`

Log in with a server-generated auth token. Preferred for production.

```tsx theme={null}
const user = await CometChatUIKit.loginWithAuthToken(token);
```

| Parameter   | Type     | Description                 |
| ----------- | -------- | --------------------------- |
| `authToken` | `string` | Server-generated auth token |

**Returns:** `Promise<CometChat.User>`

### `CometChatUIKit.logout()`

Log out the current user.

```tsx theme={null}
await CometChatUIKit.logout();
```

**Returns:** `Promise<void>`

***

## User Management

Both methods require `authKey` in your UIKitSettings — they throw if it is missing. Intended for development/testing; in production, create and update users server-side via the REST API.

### `CometChatUIKit.createUser(user)`

Create a new user.

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";

const user = new CometChat.User("new-uid");
user.setName("Alice");

const created = await CometChatUIKit.createUser(user);
```

| Parameter | Type             | Description        |
| --------- | ---------------- | ------------------ |
| `user`    | `CometChat.User` | The user to create |

**Returns:** `Promise<CometChat.User>`

### `CometChatUIKit.updateUser(user)`

Update an existing user.

```tsx theme={null}
const user = new CometChat.User("existing-uid");
user.setName("Alice Updated");

const updated = await CometChatUIKit.updateUser(user);
```

| Parameter | Type             | Description        |
| --------- | ---------------- | ------------------ |
| `user`    | `CometChat.User` | The user to update |

**Returns:** `Promise<CometChat.User>`

***

## State Getters

### `CometChatUIKit.getLoggedInUser()`

Get the currently logged-in user (synchronous).

```tsx theme={null}
const user = CometChatUIKit.getLoggedInUser();
```

**Returns:** `CometChat.User | null`

### `CometChatUIKit.isInitialized()`

Check if the SDK has been initialized.

```tsx theme={null}
if (CometChatUIKit.isInitialized()) { ... }
```

**Returns:** `boolean`

### `CometChatUIKit.isCallingReady()`

Check if the Calls SDK is ready.

**Returns:** `boolean`

### `CometChatUIKit.getPluginRegistry()`

Get the plugin registry instance.

**Returns:** `CometChatPluginRegistry | null`

### `CometChatUIKit.getSettings()`

Get the UIKitSettings used during initialization.

**Returns:** `UIKitSettings | null`

### `CometChatUIKit.getConversationUpdateSettings()`

Get conversation update settings fetched from the dashboard.

**Returns:** `CometChat.ConversationUpdateSettings | null`

***

## Message Sending

<Warning>
  These methods are low-level utilities. They send messages via the SDK but do **not** publish `ui:message/sent` events. This means:

  * The message won't appear in `CometChatMessageList` automatically
  * The `CometChatConversations` list won't update

  For messages to appear in the UI, use the `CometChatMessageComposer` component, or manually publish the event after sending:

  ```tsx theme={null}
  const publish = usePublishEvent();
  const msg = await CometChatUIKit.sendTextMessage(message);
  publish({ type: "ui:message/sent", message: msg, status: CometChatMessageStatus.success });
  ```
</Warning>

### `CometChatUIKit.sendTextMessage(message)`

Send a text message. Sets `muid` and `sentAt` if not already set.

```tsx theme={null}
const textMessage = new CometChat.TextMessage("receiverUid", "Hello!", "user");
const sent = await CometChatUIKit.sendTextMessage(textMessage);
```

**Returns:** `Promise<CometChat.BaseMessage>`

### `CometChatUIKit.sendMediaMessage(message)`

Send a media message (image, video, audio, file).

```tsx theme={null}
const mediaMessage = new CometChat.MediaMessage("receiverUid", file, "image", "user");
const sent = await CometChatUIKit.sendMediaMessage(mediaMessage);
```

**Returns:** `Promise<CometChat.BaseMessage>`

### `CometChatUIKit.sendCustomMessage(message)`

Send a custom message (polls, location, etc.).

```tsx theme={null}
const customMessage = new CometChat.CustomMessage("receiverUid", "user", "location", { latitude: 37.7749, longitude: -122.4194 });
const sent = await CometChatUIKit.sendCustomMessage(customMessage);
```

**Returns:** `Promise<CometChat.BaseMessage>`


# Upgrading from v6 to v7
Source: https://www.cometchat.com/docs/ui-kit/react/migration-overview

Migration guide covering breaking changes, architecture shifts, and step-by-step upgrade path from CometChat React UI Kit v6 to v7.

<Accordion title="AI Integration Quick Reference">
  | Field         | Value                                                                                          |
  | ------------- | ---------------------------------------------------------------------------------------------- |
  | Package       | `@cometchat/chat-uikit-react` v6 → v7                                                          |
  | React minimum | `>=18.0.0 <21.0.0`                                                                             |
  | New peer dep  | `dompurify` 3.3.1                                                                              |
  | Removed dep   | `rxjs` (no longer needed)                                                                      |
  | Init change   | Same as v6: `CometChatUIKit.init()` + `login()` imperatively, then wrap in `CometChatProvider` |
  | Extensibility | `DataSource`/`ChatConfigurator` → `CometChatMessagePlugin` interface                           |
  | Events        | RxJS Subjects → `useCometChatEvents` hook                                                      |
  | Theming       | Same CSS variables, simpler setup via `theme` prop on provider                                 |
</Accordion>

## What's New in v7

v7 is a ground-up rewrite that replaces global singletons with React-native patterns while keeping most component props compatible. The core shifts:

| Area            | v6                                                        | v7                                                                         |
| --------------- | --------------------------------------------------------- | -------------------------------------------------------------------------- |
| Initialization  | `CometChatUIKit.init()` + `login()` (imperative)          | Same: `CometChatUIKit.init()` + `login()` then wrap in `CometChatProvider` |
| Extensibility   | `DataSource` / `DataSourceDecorator` / `ChatConfigurator` | Plugin system (`CometChatMessagePlugin` interface)                         |
| Events          | Multiple RxJS Subject classes                             | Unified event bus (`useCometChatEvents` hook)                              |
| Component API   | Flat props only                                           | Compound components (flat API still works)                                 |
| Message Bubbles | Presentational — receive pre-extracted props from parent  | Self-extracting — accept SDK `message` and derive data internally          |
| Theming         | CSS variables + manual `data-theme` setup                 | CSS variables + `theme` prop on provider (same tokens)                     |
| Dependencies    | `rxjs` required                                           | No `rxjs` dependency                                                       |

***

## Step-by-Step Migration Checklist

### 1. Update Dependencies

```bash theme={null}
npm install @cometchat/chat-uikit-react@7 @cometchat/chat-sdk-javascript@^4.1.10 dompurify@3.3.1
npm uninstall rxjs  # No longer needed for CometChat
```

| Package                           | v6       | v7                     |
| --------------------------------- | -------- | ---------------------- |
| `@cometchat/chat-uikit-react`     | `^6.x`   | `^7.0.0`               |
| `@cometchat/chat-sdk-javascript`  | `^4.x`   | `^4.1.10` (peer dep)   |
| `react`                           | `>=18`   | `>=18 <21`             |
| `dompurify`                       | —        | `3.3.1` (new peer dep) |
| `rxjs`                            | Required | Not needed             |
| `@cometchat/calls-sdk-javascript` | Optional | Optional (unchanged)   |

### 2. Update Initialization

The initialization pattern is nearly identical between v6 and v7. The only addition in v7 is wrapping your app in `CometChatProvider`:

```tsx title="v6" theme={null}
// main.tsx
const settings = new UIKitSettingsBuilder()
  .setAppId("APP_ID")
  .setRegion("us")
  .setAuthKey("AUTH_KEY")
  .build();

CometChatUIKit.init(settings).then(async () => {
  await CometChatUIKit.login("uid");
  render(<App />);
});
```

```tsx title="v7" theme={null}
// main.tsx — same init + login, just add CometChatProvider in your component tree
const settings = new UIKitSettingsBuilder()
  .setAppId("APP_ID")
  .setRegion("us")
  .setAuthKey("AUTH_KEY")
  .build();

CometChatUIKit.init(settings).then(async () => {
  await CometChatUIKit.login("uid");
  render(<App />);
});

// App.tsx — wrap in CometChatProvider
function App() {
  return (
    <CometChatProvider>
      <MyChatApp />
    </CometChatProvider>
  );
}
```

### 3. Replace DataSource/Decorator with Plugins

```tsx title="v6" theme={null}
class MyDecorator extends DataSourceDecorator {
  getTextMessageBubble() { ... }
  getAttachmentOptions() { ... }
}
ChatConfigurator.enable(new MyDecorator());
```

```tsx title="v7" theme={null}
const MyPlugin: CometChatMessagePlugin = {
  id: "my-plugin",
  messageTypes: ["custom-type"],
  messageCategories: ["custom"],
  renderBubble(message, context) { return <MyBubble />; },
  getOptions(message, context) { return [...]; },
  getLastMessagePreview(message) { return "Preview text"; },
};

<CometChatProvider plugins={[MyPlugin]}>
```

See [Plugins Overview](/docs/ui-kit/react/plugins/overview) for the full guide.

### 4. Replace RxJS Event Subscriptions

```tsx title="v6" theme={null}
import { CometChatMessageEvents } from "@cometchat/chat-uikit-react";

CometChatMessageEvents.ccMessageSent.subscribe((data) => { ... });
CometChatMessageEvents.ccMessageEdited.subscribe((data) => { ... });
```

```tsx title="v7" theme={null}
import { useCometChatEvents } from "@cometchat/chat-uikit-react";

useCometChatEvents((event) => {
  if (event.type === "ui:message/sent") { ... }
  if (event.type === "message/edited") { ... }
});
```

See [Event System](/docs/ui-kit/react/event-system) for the full event catalog.

### 5. Update Component Props

Most component props are unchanged. Key patterns to watch for:

| Pattern                  | v6                         | v7                                           |
| ------------------------ | -------------------------- | -------------------------------------------- |
| View props type          | `JSX.Element`              | `ReactNode` (compatible)                     |
| Date format type         | `CalendarObject`           | `CometChatDateFormatConfig` (same shape)     |
| Error handling           | `hideError` prop           | `errorView` prop (pass custom error UI)      |
| Loading state            | `disableLoadingState` prop | `loadingView` prop (pass custom loading UI)  |
| Templates                | `templates` prop           | Plugin system (removed from components)      |
| Text formatters on lists | `textFormatters` prop      | Plugin system (removed from list components) |

For the full prop-by-prop reference, see [Property Changes](/docs/ui-kit/react/migration-property-changes).

### 6. Update Theming (Minor)

CSS variables are the same between v6 and v7. The only change is how you set the theme:

```tsx title="v6" theme={null}
// Manual data-theme attribute
<div className="cometchat-root" data-theme="dark">
```

```tsx title="v7" theme={null}
// theme prop on provider
<CometChatProvider theme="dark">
```

Or use the `useTheme()` hook for runtime switching:

```tsx theme={null}
const { theme, setTheme } = useTheme();
```

### 7. Enable Calling (If Used)

Calling is now configured via `UIKitSettingsBuilder` rather than a provider prop:

```tsx title="v7" theme={null}
const settings = new UIKitSettingsBuilder()
  .setAppId("APP_ID")
  .setRegion("us")
  .setAuthKey("AUTH_KEY")
  .setCallingEnabled(true)
  .build();

await CometChatUIKit.init(settings);
```

Without `.setCallingEnabled(true)`, call buttons are hidden and the Calls SDK is not loaded.

***

## Architecture Changes

### DataSource → Plugin System

v6 used a decorator pattern (`DataSourceDecorator`) to customize message rendering. v7 replaces this with a simpler plugin interface:

* Each plugin owns one or more message types
* Plugins provide `renderBubble()`, `getOptions()`, `getLastMessagePreview()`
* Default plugins are included automatically
* Custom plugins are passed via the `plugins` prop on `CometChatProvider`

### RxJS Subjects → Unified Event Bus

v6 had separate RxJS Subject classes for each event category (`CometChatMessageEvents`, `CometChatGroupEvents`, `CometChatCallEvents`, etc.). v7 merges all events into a single typed pub/sub system:

* Subscribe: `useCometChatEvents((event) => { ... })`
* Publish: `const publish = usePublishEvent()`
* SDK events (from network) and UI events (from components) flow through the same bus

### Flat API → Compound Components

v7 components support both flat API (same as v6) and compound composition:

```tsx title="Flat API (works same as v6)" theme={null}
<CometChatConversations hideSearch onItemClick={handleClick} />
```

```tsx title="Compound (new in v7)" theme={null}
<CometChatConversations.Root onItemClick={handleClick}>
  {/* Search omitted — just don't render it */}
  <CometChatConversations.List />
</CometChatConversations.Root>
```

The flat API is fully backward-compatible. Compound composition is optional for advanced customization.

### Presentational Bubbles → Self-Extracting Bubbles

In v6, message bubble components (TextBubble, ImageBubble, etc.) were **presentational** — they received pre-extracted props like `src`, `text`, `isSentByMe` from the parent. The DataSource/plugin layer did the extraction and passed data down.

In v7, bubble components are **self-extracting** — they accept the SDK `message` object as their primary input and derive rendering state internally (attachments, text, sender info, alignment). Some bubbles retain optional override props (e.g., `text` and `isSentByMe` on `CometChatTextBubble`), but the standard usage is to pass only `message`.

```tsx title="v6 — presentational (parent extracts data)" theme={null}
<CometChatImageBubble src={message.getURL()} isSentByMe={true} />
```

```tsx title="v7 — self-extracting (bubble handles it)" theme={null}
<CometChatImagesBubble message={message} />
```

This applies to all message bubbles: `CometChatTextBubble`, `CometChatImagesBubble`, `CometChatVideosBubble`, `CometChatAudiosBubble`, `CometChatVoiceNoteBubble`, `CometChatFilesBubble`, `CometChatPollBubble`, `CometChatStickerBubble`, `CometChatCallBubble`, `CometChatCollaborativeDocumentBubble`, `CometChatCollaborativeWhiteboardBubble`, `CometChatGroupActionBubble`, and `CometChatCallActionBubble`.

<Note>
  In v7 the default rendering moves to the multi-attachment media bubbles: `CometChatImageBubble` → `CometChatImagesBubble`, `CometChatVideoBubble` → `CometChatVideosBubble`, `CometChatFileBubble` → `CometChatFilesBubble`, and `CometChatAudioBubble` → `CometChatAudiosBubble` (attached audio files) or `CometChatVoiceNoteBubble` (recorded voice notes). The singular `CometChat*Bubble` components still ship and can be used standalone — only the message list's default routing changed.
</Note>

***

## Removed Concepts

| v6 Concept                                                           | Replacement in v7                                                                                                                                   |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DataSource` / `DataSourceDecorator`                                 | `CometChatMessagePlugin` interface                                                                                                                  |
| `ChatConfigurator.enable()`                                          | `plugins` prop on `CometChatProvider`                                                                                                               |
| `CometChatMessageEvents` (RxJS)                                      | `useCometChatEvents` hook                                                                                                                           |
| `CometChatGroupEvents` (RxJS)                                        | `useCometChatEvents` hook                                                                                                                           |
| `CometChatCallEvents` (RxJS)                                         | `useCometChatEvents` hook                                                                                                                           |
| `CometChatUIEvents` (RxJS)                                           | `usePublishEvent` hook                                                                                                                              |
| `CometChatMessageTemplate`                                           | Plugin `renderBubble()` method                                                                                                                      |
| `*Configuration` objects                                             | Direct props on compound sub-components                                                                                                             |
| `MessagesDataSource.getAttachmentOptions()`                          | Composer handles attachments directly                                                                                                               |
| Presentational bubble props (`src`, `text`, etc.) as required inputs | Bubbles now accept `message` as the primary prop and self-extract data — optional overrides like `text` or `isSentByMe` still exist on some bubbles |

***

## Next Steps

<CardGroup>
  <Card title="Property Changes" icon="list" href="/ui-kit/react/migration-property-changes">
    Full prop-by-prop migration reference for every component
  </Card>

  <Card title="CometChatProvider" icon="box" href="/ui-kit/react/cometchat-provider">
    Provider setup with all props explained
  </Card>

  <Card title="Plugins" icon="puzzle-piece" href="/ui-kit/react/plugins/overview">
    The new plugin system that replaces DataSource
  </Card>

  <Card title="Event System" icon="bolt" href="/ui-kit/react/event-system">
    Unified event bus replacing RxJS Subjects
  </Card>
</CardGroup>


# Property Changes
Source: https://www.cometchat.com/docs/ui-kit/react/migration-property-changes

Complete prop migration reference for all components from v6 to v7 — renamed, removed, added, and type-changed props.

<Accordion title="AI Integration Quick Reference">
  | Package                       | Migration from | Key changes                                                                                                                                                                            | Reference                                              |
  | ----------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
  | `@cometchat/chat-uikit-react` | v6 → v7        | Plugin system replaces templates/textFormatters; compound components replace string props; individual hide\*Option props consolidated; view props become render props on MessageBubble | [Migration Overview](/docs/ui-kit/react/migration-overview) |
</Accordion>

## Common Patterns

These 8 patterns apply across all components. You do not need to look them up per-component:

| # | Pattern                                    | v6                           | v7                          | Action Required                                                           |
| - | ------------------------------------------ | ---------------------------- | --------------------------- | ------------------------------------------------------------------------- |
| 1 | View prop types                            | `JSX.Element`                | `ReactNode`                 | None (backward-compatible)                                                |
| 2 | Date format type                           | `CalendarObject`             | `CometChatDateFormatConfig` | Same shape, type alias renamed                                            |
| 3 | `hideError` prop (list & other components) | `boolean`                    | Removed                     | Use `errorView` prop instead — **retained on `CometChatMessageComposer`** |
| 4 | `disableLoadingState` prop                 | `boolean`                    | Removed                     | Use `loadingView` prop instead                                            |
| 5 | `textFormatters` on list components        | `CometChatTextFormatter[]`   | Removed                     | Handled by plugin system                                                  |
| 6 | `templates` prop                           | `CometChatMessageTemplate[]` | Removed                     | Handled by plugin system                                                  |
| 7 | `className` prop                           | Not available                | `string`                    | New on all components — for custom styling                                |
| 8 | `children` prop                            | Not available                | `ReactNode`                 | New on many components — for compound composition                         |

***

## CometChatConversations

### Removed Props

| Prop             | Replacement                      |
| ---------------- | -------------------------------- |
| `textFormatters` | Plugin system handles formatting |
| `hideError`      | Use `errorView` prop             |

### New Props

| Prop                   | Type                          | Description                            |
| ---------------------- | ----------------------------- | -------------------------------------- |
| `onEmpty`              | `() => void`                  | Called when conversation list is empty |
| `searchRequestBuilder` | `ConversationsRequestBuilder` | Builder for search filtering           |
| `searchKeyword`        | `string`                      | Controlled search keyword              |

***

## CometChatMessageList

### Modified Props

| Prop            | v6 Type  | v7 Type  | Notes                                        |
| --------------- | -------- | -------- | -------------------------------------------- |
| `goToMessageId` | `string` | `number` | Changed to match SDK's `getId()` return type |

### Removed Props

| Prop             | Replacement          |
| ---------------- | -------------------- |
| `templates`      | Plugin system        |
| `textFormatters` | Plugin system        |
| `hideError`      | Use `errorView` prop |

### New Props

| Prop                         | Type                                       | Description                        |
| ---------------------------- | ------------------------------------------ | ---------------------------------- |
| `messageTypes`               | `string[]`                                 | Filter message types to display    |
| `messageCategories`          | `string[]`                                 | Filter message categories          |
| `onAvatarClick`              | `(user: CometChat.User) => void`           | Avatar click callback              |
| `onEditMessage`              | `(message: CometChat.BaseMessage) => void` | Edit message callback              |
| `onReplyMessage`             | `(message: CometChat.BaseMessage) => void` | Reply message callback             |
| `disableTruncation`          | `boolean`                                  | Disable text truncation in bubbles |
| `bubbleView`                 | `(message, loggedInUser) => ReactNode`     | Custom bubble renderer             |
| `onActiveChatChanged`        | `(data) => void`                           | Active chat change callback        |
| `onMessageRead`              | `(message: CometChat.BaseMessage) => void` | Message read callback              |
| `onMessageDeleted`           | `(message: CometChat.BaseMessage) => void` | Message deleted callback           |
| `onConversationMarkedAsRead` | `(conversation) => void`                   | Conversation marked as read        |
| `onConversationUpdated`      | `(conversation) => void`                   | Conversation updated callback      |

***

## CometChatMessageComposer

### Renamed Props

| v6 Name                                                                                                                                                                                                            | v7 Name                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| `initialComposerText`                                                                                                                                                                                              | `initialText`                                               |
| `placeholderText`                                                                                                                                                                                                  | `placeholder`                                               |
| `hideImageAttachmentOption` / `hideVideoAttachmentOption` / `hideAudioAttachmentOption` / `hideFileAttachmentOption` / `hidePollsOption` / `hideCollaborativeDocumentOption` / `hideCollaborativeWhiteboardOption` | `hideAttachmentOptions` (single object with boolean fields) |

### New Props

| Prop                            | Type                              | Description                                                                                                            |
| ------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `layout`                        | `CometChatMessageComposerLayout`  | Absorbs CompactMessageComposer variant                                                                                 |
| `text`                          | `string`                          | Controlled text value                                                                                                  |
| `maxInputHeight`                | `number`                          | Max height before scrolling                                                                                            |
| `enableRichTextEditor`          | `boolean`                         | Enable rich text formatting toolbar                                                                                    |
| `hideRichTextFormattingOptions` | `boolean`                         | Hide formatting toolbar when rich text is enabled                                                                      |
| `showBubbleMenuOnSelection`     | `boolean`                         | Show bubble menu on text selection                                                                                     |
| `messageToEdit`                 | `TextMessage \| null`             | Message being edited                                                                                                   |
| `messageToReply`                | `BaseMessage \| null`             | Message being replied to                                                                                               |
| `hideAttachmentOptions`         | `CometChatAttachmentHideOptions`  | Object to hide specific attachment types                                                                               |
| `showAttachmentPreview`         | `boolean`                         | Show attachment preview before sending                                                                                 |
| `enableMultipleAttachments`     | `boolean`                         | Enable multi-attachment staging tray and batch send. Default: `true`. Set to `false` for legacy single-select behavior |
| `disableDragAndDrop`            | `boolean`                         | Disable drag-and-drop file upload. Default: `false`                                                                    |
| `allowedFileTypes`              | `string[]`                        | Allowed MIME types for attachments                                                                                     |
| `hideAIButton`                  | `boolean`                         | Hide AI assistant button                                                                                               |
| `hideLiveReaction`              | `boolean`                         | Hide live reaction button                                                                                              |
| `hideError`                     | `boolean`                         | Hide error state                                                                                                       |
| `disableAutoFocusOnMobile`      | `boolean`                         | Disable auto-focus on mobile                                                                                           |
| `liveReactionIcon`              | `string`                          | Custom live reaction icon                                                                                              |
| `attachmentIconView`            | `ReactNode`                       | Custom attachment icon                                                                                                 |
| `voiceRecordingIconView`        | `ReactNode`                       | Custom voice recording icon                                                                                            |
| `emojiIconView`                 | `ReactNode`                       | Custom emoji icon                                                                                                      |
| `secondaryButtonView`           | `ReactNode`                       | Custom secondary button                                                                                                |
| `sendTextMessageOverride`       | `(text, richTextHtml?) => string` | Override sent text                                                                                                     |
| `onClosePreview`                | `() => void`                      | Close preview callback                                                                                                 |
| `onAttachmentAdded`             | `(file: File) => void`            | Attachment added callback                                                                                              |
| `onAttachmentRemoved`           | `(file: File) => void`            | Attachment removed callback                                                                                            |
| `onMentionSelected`             | `(user) => void`                  | Mention selected callback                                                                                              |

***

## CometChatMessageHeader

### Modified Props

| Prop          | v6 Signature | v7 Signature                      | Notes                              |
| ------------- | ------------ | --------------------------------- | ---------------------------------- |
| `onItemClick` | `() => void` | `(entity: User \| Group) => void` | Now receives the user/group entity |

### Removed Props

| Prop       | Replacement                                      |
| ---------- | ------------------------------------------------ |
| `itemView` | Use compound composition to replace header parts |

### New Props

| Prop                  | Type                              | Description                  |
| --------------------- | --------------------------------- | ---------------------------- |
| `onSummaryClick`      | `() => void`                      | Summary button click         |
| `onVoiceCallClick`    | `(entity: User \| Group) => void` | Voice call button click      |
| `onVideoCallClick`    | `(entity: User \| Group) => void` | Video call button click      |
| `callSettingsBuilder` | `any`                             | Custom call settings builder |

***

## CometChatThreadHeader

### Removed Props

| Prop             | Replacement   |
| ---------------- | ------------- |
| `template`       | Plugin system |
| `textFormatters` | Plugin system |

### New Props

| Prop              | Type         | Description                           |
| ----------------- | ------------ | ------------------------------------- |
| `onParentDeleted` | `() => void` | Called when parent message is deleted |
| `headerView`      | `ReactNode`  | Custom header content                 |

***

## CometChatUsers

### Removed Props

| Prop                  | Replacement            |
| --------------------- | ---------------------- |
| `hideError`           | Use `errorView` prop   |
| `disableLoadingState` | Use `loadingView` prop |

***

## CometChatGroups

### Removed Props

| Prop        | Replacement          |
| ----------- | -------------------- |
| `hideError` | Use `errorView` prop |

### New Props

| Prop            | Type         | Description               |
| --------------- | ------------ | ------------------------- |
| `onEmpty`       | `() => void` | Called when list is empty |
| `searchKeyword` | `string`     | Controlled search keyword |

***

## CometChatGroupMembers

### Modified Props

| Prop      | v6 Signature                  | v7 Signature           | Notes                                                     |
| --------- | ----------------------------- | ---------------------- | --------------------------------------------------------- |
| `options` | `(group, member) => Option[]` | `(member) => Option[]` | `group` param removed — component already knows its group |

### Removed Props

| Prop                  | Replacement            |
| --------------------- | ---------------------- |
| `hideError`           | Use `errorView` prop   |
| `disableLoadingState` | Use `loadingView` prop |

### New Props

| Prop     | Type         | Description          |
| -------- | ------------ | -------------------- |
| `onBack` | `() => void` | Back button callback |

***

## CometChatIncomingCall

### Removed Props

| Prop   | Replacement                                   |
| ------ | --------------------------------------------- |
| `call` | Incoming call is detected automatically in v7 |

### New Props

| Prop          | Type         | Description           |
| ------------- | ------------ | --------------------- |
| `onCallEnded` | `() => void` | Called when call ends |

***

## CometChatOngoingCall

### New Props

| Prop              | Type         | Description           |
| ----------------- | ------------ | --------------------- |
| `isAudioOnly`     | `boolean`    | Audio-only call mode  |
| `isDirectCalling` | `boolean`    | Direct calling mode   |
| `onCallEnded`     | `() => void` | Called when call ends |

***

## CometChatMessageBubble

### Renamed Props

| v6 Name       | v7 Name             |
| ------------- | ------------------- |
| `topMenuSize` | `quickOptionsCount` |

### Modified Props

| Prop             | v6 Type                                            | v7 Type                          | Migration                               |
| ---------------- | -------------------------------------------------- | -------------------------------- | --------------------------------------- |
| `leadingView`    | `JSX.Element \| null`                              | `(message) => ReactNode \| null` | Wrap in arrow function: `() => yourJSX` |
| `headerView`     | `JSX.Element \| null`                              | `(message) => ReactNode \| null` | Wrap in arrow function                  |
| `bottomView`     | `JSX.Element \| null`                              | `(message) => ReactNode \| null` | Wrap in arrow function                  |
| `threadView`     | `JSX.Element \| null`                              | `(message) => ReactNode \| null` | Wrap in arrow function                  |
| `footerView`     | `JSX.Element \| null`                              | `(message) => ReactNode \| null` | Wrap in arrow function                  |
| `statusInfoView` | `JSX.Element \| null`                              | `(message) => ReactNode \| null` | Wrap in arrow function                  |
| `options`        | `(CometChatActionsIcon \| CometChatActionsView)[]` | `CometChatMessageOption[]`       | New type with `id`, `title`, `onClick`  |
| `setRef`         | `(ref: any) => void`                               | `Ref<HTMLDivElement>`            | Use `useRef()` instead of callback      |

### Removed Props

| Prop       | Replacement                 |
| ---------- | --------------------------- |
| `id`       | Derived from `message` prop |
| `type`     | Derived from `message` prop |
| `category` | Derived from `message` prop |

### New Props

| Prop                          | Type                         | Description                   |
| ----------------------------- | ---------------------------- | ----------------------------- |
| `message`                     | `CometChat.BaseMessage`      | The message object (required) |
| `group`                       | `CometChat.Group`            | Group context                 |
| `hideAvatar`                  | `boolean`                    | Hide avatar                   |
| `forceShowAvatar`             | `boolean`                    | Force show avatar             |
| `hideSenderName`              | `boolean`                    | Hide sender name              |
| `hideTimestamp`               | `boolean`                    | Hide timestamp                |
| `hideThreadView`              | `boolean`                    | Hide thread indicator         |
| `showError`                   | `boolean`                    | Show error state              |
| `disableInteraction`          | `boolean`                    | Disable all interactions      |
| `hideReceipts`                | `boolean`                    | Hide delivery receipts        |
| `messageSentAtDateTimeFormat` | `CometChatDateFormatConfig`  | Timestamp format              |
| `onAvatarClick`               | `(user) => void`             | Avatar click callback         |
| `onThreadRepliesClick`        | `(message) => void`          | Thread click callback         |
| `onOptionClick`               | `(option, message) => void`  | Option click callback         |
| `onReactionChipClick`         | `(messageId, emoji) => void` | Reaction chip click           |
| `isSelected`                  | `boolean`                    | Selection state               |

***

## CometChatContextMenu

### Renamed Props

| v6 Name             | v7 Name             |
| ------------------- | ------------------- |
| `data`              | `items`             |
| `moreIconHoverText` | `moreButtonTooltip` |

### Modified Props

| Prop              | Change                                                    |
| ----------------- | --------------------------------------------------------- |
| `onOptionClicked` | Type changed: now receives `CometChatContextMenuItemData` |

***

## CometChatConfirmDialog

All string/callback props moved to compound sub-components:

| v6 Prop             | v7 Location                                                 |
| ------------------- | ----------------------------------------------------------- |
| `title`             | `CometChatConfirmDialog.Content` → `title` prop             |
| `messageText`       | `CometChatConfirmDialog.Content` → `messageText` prop       |
| `cancelButtonText`  | `CometChatConfirmDialog.Actions` → `cancelButtonText` prop  |
| `confirmButtonText` | `CometChatConfirmDialog.Actions` → `confirmButtonText` prop |
| `onSubmitClick`     | `CometChatConfirmDialog.Actions` → `onConfirm` prop         |
| `onCancelClick`     | `CometChatConfirmDialog.Actions` → `onCancel` prop          |

New root-level props: `isOpen`, `onClose`, `closeOnOutsideClick`, `variant`.

The compound sub-components are `CometChatConfirmDialog.Root`, `.Icon` (optional leading icon, new in v7), `.Content`, and `.Actions`.

***

## CometChatActionSheet

All props moved to compound pattern:

| v6 Prop             | v7 Equivalent                                                                 |
| ------------------- | ----------------------------------------------------------------------------- |
| `actions`           | Pass items as `<CometChatActionSheet.Item item={...} />` children             |
| `onActionItemClick` | Each `CometChatActionSheet.Item` handles its own `onClick` via `item.onClick` |

New root-level props: `isOpen`, `onClose`, `layoutMode`, `title`.

***

## CometChatCheckbox

### Renamed Props

| v6 Name                  | v7 Name    |
| ------------------------ | ---------- |
| `labelText`              | `label`    |
| `onCheckBoxValueChanged` | `onChange` |

***

## CometChatChangeScope

### Renamed Props

| v6 Name        | v7 Name   |
| -------------- | --------- |
| `onCloseClick` | `onClose` |

### Modified Props

| Prop      | v6 Type    | v7 Type                            | Notes                                                                                               |
| --------- | ---------- | ---------------------------------- | --------------------------------------------------------------------------------------------------- |
| `options` | `string[]` | `CometChatChangeScopeOptionData[]` | Changed to structured `{ id, label }` objects. Migration: `options.map(s => ({ id: s, label: s }))` |

***

## CometChatDate

### Renamed Props

| v6 Name          | v7 Name        |
| ---------------- | -------------- |
| `calendarObject` | `formatConfig` |

### New Props

| Prop        | Type                            | Description            |
| ----------- | ------------------------------- | ---------------------- |
| `formatter` | `(timestamp: number) => string` | Custom format function |
| `variant`   | `CometChatDateVariant`          | Display variant        |

***

## CometChatReactions

### Renamed Props

| v6 Name                   | v7 Name          |
| ------------------------- | ---------------- |
| `messageObject`           | `message`        |
| `onReactionListItemClick` | `onReactorClick` |

### Modified Props

| Prop              | v6 Signature                                 | v7 Signature                       | Notes                                           |
| ----------------- | -------------------------------------------- | ---------------------------------- | ----------------------------------------------- |
| `onReactionClick` | `(reaction: ReactionCount, message) => void` | `(emoji: string, message) => void` | First param changed from object to emoji string |

***

## CometChatReactionList

### Renamed Props

| v6 Name               | v7 Name       |
| --------------------- | ------------- |
| `messageObject`       | `message`     |
| `reactionItemClicked` | `onItemClick` |

***

## CometChatFullScreenViewer

### Renamed Props

| v6 Name          | v7 Name   |
| ---------------- | --------- |
| `ccCloseClicked` | `onClose` |

### Removed Props

| Prop               | Replacement                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `message`          | Replaced by individual props: `senderName`, `senderAvatar`, `sentAt` |
| `placeholderImage` | Handled internally                                                   |

### New Props

| Prop                     | Type                                 | Description                   |
| ------------------------ | ------------------------------------ | ----------------------------- |
| `isOpen`                 | `boolean`                            | Controlled open state         |
| `mediaType`              | `CometChatFullScreenViewerMediaType` | Type of media being viewed    |
| `fileName`               | `string`                             | File name display             |
| `fileSize`               | `number`                             | File size display             |
| `attachments`            | `CometChatMediaAttachment[]`         | Multi-media gallery support   |
| `startIndex`             | `number`                             | Initial gallery index         |
| `senderName`             | `string`                             | Sender display name           |
| `senderAvatar`           | `string`                             | Sender avatar URL             |
| `senderStatus`           | `string`                             | Sender online status          |
| `sentAt`                 | `string`                             | Message timestamp             |
| `onIndexChange`          | `(index: number) => void`            | Gallery index change callback |
| `onDownload`             | `(attachment) => void`               | Download callback             |
| `enablePictureInPicture` | `boolean`                            | PiP for video                 |

***

## CometChatImageBubble → CometChatImagesBubble

In v7, the image bubble is renamed **`CometChatImagesBubble`** and is **self-extracting**: pass the SDK `message` and the bubble derives its own attachments, caption, and alignment (and renders multiple images in a grid). The pre-extracted data props from v6 are gone.

### Removed Props

| Prop          | Replacement                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| `src`         | Self-extracted from `message` (multi-image support via the message's attachments)                            |
| `isSentByMe`  | `alignment` (`"left"` / `"right"`), auto-derived from the message sender vs. the logged-in user when omitted |
| `attachments` | Self-extracted from `message`                                                                                |
| `caption`     | Self-extracted from `message`                                                                                |
| `senderName`  | Self-extracted from `message`                                                                                |

### New / Current Props

| Prop               | Type                          | Description                                           |
| ------------------ | ----------------------------- | ----------------------------------------------------- |
| `message`          | `CometChat.MediaMessage`      | Source message — drives all extraction (**required**) |
| `alignment`        | `"left" \| "right"`           | Override incoming/outgoing alignment                  |
| `textFormatters`   | `CometChatTextFormatter[]`    | Text formatters for caption rendering                 |
| `placeholderImage` | `string`                      | Custom placeholder shown while the image loads        |
| `onImageClicked`   | `(attachment, index) => void` | Fires when an image is clicked                        |
| `className`        | `string`                      | Custom root class                                     |

<Note>
  The other media bubbles likewise default to their multi-attachment v7 components: `CometChatVideoBubble` → `CometChatVideosBubble`, `CometChatFileBubble` → `CometChatFilesBubble`, and `CometChatAudioBubble` → `CometChatAudiosBubble` (attached audio files) or `CometChatVoiceNoteBubble` (recorded voice notes). The singular `CometChat*Bubble` components still ship and can be used standalone — only the default routing changed. This self-extracting pattern applies to all message bubbles in v7 (`CometChatTextBubble`, `CometChatPollBubble`, `CometChatStickerBubble`, `CometChatCallBubble`, and the action/collaborative bubbles too): each takes the SDK `message` and derives its own data. See [Message Bubble](/docs/ui-kit/react/components/message-bubble).
</Note>

***

## CometChatSearchBar

### Modified Props

| Prop       | v6 Signature                          | v7 Signature              | Notes                                 |
| ---------- | ------------------------------------- | ------------------------- | ------------------------------------- |
| `onChange` | `(input: { value?: string }) => void` | `(value: string) => void` | Simplified — receives string directly |

### New Props

| Prop                | Type                    | Description              |
| ------------------- | ----------------------- | ------------------------ |
| `defaultSearchText` | `string`                | Default search text      |
| `disabled`          | `boolean`               | Disable the search bar   |
| `debounceMs`        | `number`                | Debounce delay in ms     |
| `inputRef`          | `Ref<HTMLInputElement>` | Ref to the input element |
| `style`             | `CSSProperties`         | Inline styles            |

***

## CometChatButton

### Removed Props

| Prop      | Replacement                                                        |
| --------- | ------------------------------------------------------------------ |
| `text`    | Use `children`                                                     |
| `iconURL` | Use `children` (render your own icon)                              |
| `onClick` | Uses native `ButtonHTMLAttributes` — standard `onClick` from React |

### New Props

| Prop           | Type                     | Description                |
| -------------- | ------------------------ | -------------------------- |
| `variant`      | `CometChatButtonVariant` | Button style variant       |
| `size`         | `CometChatButtonSize`    | Button size                |
| `loadingLabel` | `string`                 | Label shown during loading |

***

## Next Steps

<CardGroup>
  <Card title="Migration Overview" icon="arrow-up" href="/ui-kit/react/migration-overview">
    Architecture changes and step-by-step checklist
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all v7 components
  </Card>
</CardGroup>


# Conversation List + Message View
Source: https://www.cometchat.com/docs/ui-kit/react/next-conversation

Build a two-panel conversation list + message view layout in Next.js (App Router) with CometChat UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                  |
  | ------------ | ------------------------------------------------------------------------------------------------------ |
  | Package      | `@cometchat/chat-uikit-react`                                                                          |
  | Framework    | Next.js (App Router)                                                                                   |
  | Components   | `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Two-panel — conversation list (left) + message view (right)                                            |
  | Prerequisite | Complete [Next.js Integration](/docs/ui-kit/react/integration-nextjs) first                                 |
  | SSR          | Component loaded with `dynamic(() => import(...), { ssr: false })`                                     |
  | Pattern      | WhatsApp Web, Slack, Microsoft Teams                                                                   |
</Accordion>

This guide builds a two-panel chat layout — conversation list on the left, messages on the right. Users click a conversation to open it.

This assumes you've already completed [Next.js Integration](/docs/ui-kit/react/integration-nextjs) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three sections working together:

1. **Sidebar (conversation list)** — shows all active conversations (users and groups)
2. **Message view** — displays chat messages for the selected conversation in real time
3. **Message composer** — text input with support for media, emojis, and reactions

***

## Full Code

Create the client component with the chat UI, then import it dynamically in your page. Init and login happen in a `useEffect` before the provider mounts.

```tsx title="app/chat/CometChatClient.tsx" theme={null}
'use client';

import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
  CometChatProvider,
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

export default function CometChatClient() {
  const [ready, setReady] = useState(false);
  const [selectedUser, setSelectedUser] = useState<CometChat.User | undefined>(undefined);
  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group | undefined>(undefined);

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      setReady(true);
    });
  }, []);

  if (!ready) return <div>Loading chat...</div>;

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setSelectedUser(entity as CometChat.User);
      setSelectedGroup(undefined);
    } else {
      setSelectedGroup(entity as CometChat.Group);
      setSelectedUser(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div className="conversations-with-messages">
        <div className="conversations-wrapper">
          <CometChatConversations onItemClick={handleConversationClick} />
        </div>

        {selectedUser || selectedGroup ? (
          <div className="messages-wrapper">
            <CometChatMessageHeader user={selectedUser} group={selectedGroup} />
            <CometChatMessageList user={selectedUser} group={selectedGroup} />
            <CometChatMessageComposer user={selectedUser} group={selectedGroup} />
          </div>
        ) : (
          <div className="empty-conversation">
            Select a conversation to start chatting
          </div>
        )}
      </div>
    </CometChatProvider>
  );
}
```

```css title="app/chat/chat.css" theme={null}
.conversations-with-messages {
  display: flex;
  height: 100vh;
  width: 100%;
}

.conversations-wrapper {
  width: 360px;
  height: 100%;
  border-right: 1px solid #eee;
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

.messages-wrapper {
  flex: 1;
  height: 100%;
  display: flex;
  flex-direction: column;
}

.empty-conversation {
  flex: 1;
  display: flex;
  justify-content: center;
  align-items: center;
  background: var(--cometchat-background-color-03, #f5f5f5);
  color: var(--cometchat-text-color-secondary, #727272);
  font: var(--cometchat-font-body-regular, 400 14px Roboto);
}
```

```tsx title="app/chat/page.tsx" theme={null}
import dynamic from 'next/dynamic';

const CometChatClient = dynamic(() => import('./CometChatClient'), { ssr: false });

export default function ChatPage() {
  return <CometChatClient />;
}
```

***

## How It Works

1. **`'use client'`** marks the component as a Client Component — required because CometChat uses browser APIs.
2. **`dynamic(() => import(...), { ssr: false })`** prevents the component from rendering on the server, avoiding `window is not defined` errors.
3. **CometChatProvider** wraps the entire tree — it supplies theme, locale, and event context to all CometChat components.
4. **CometChatConversations** renders the sidebar list. When a user clicks a conversation, `onItemClick` fires with the `Conversation` object.
5. **handleConversationClick** extracts the `User` or `Group` from the conversation and stores it in state.
6. **Message components** (`MessageHeader`, `MessageList`, `MessageComposer`) receive either `user` or `group` as a prop — never both at the same time.

***

## Run

```bash theme={null}
npm run dev
```

Open `http://localhost:3000/chat`. You should see the conversation list on the left. Click any conversation to load messages on the right.

***

## Next Steps

<CardGroup>
  <Card title="One-to-One / Group Chat" icon="message" href="/ui-kit/react/next-one-to-one-chat">
    Single chat window without a sidebar
  </Card>

  <Card title="Tab-Based Chat" icon="table-columns" href="/ui-kit/react/next-tab-based-chat">
    Tabbed navigation with Chats, Calls, Users
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and styles
  </Card>
</CardGroup>


# One-to-One / Group Chat
Source: https://www.cometchat.com/docs/ui-kit/react/next-one-to-one-chat

Build a single chat window for one-to-one or group messaging in Next.js (App Router) with CometChat UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                        |
  | ------------ | ---------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react`                                                |
  | Framework    | Next.js (App Router)                                                         |
  | Components   | `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Single chat window — no sidebar, no conversation list                        |
  | Prerequisite | Complete [Next.js Integration](/docs/ui-kit/react/integration-nextjs) first       |
  | SSR          | Component loaded with `dynamic(() => import(...), { ssr: false })`           |
  | Pattern      | Support chat, embedded widgets, focused messaging                            |
</Accordion>

This guide builds a single chat window — no sidebar, no conversation list. Users go directly into a one-to-one or group chat. Good for support chat, embedded widgets, or any focused messaging experience.

This assumes you've already completed [Next.js Integration](/docs/ui-kit/react/integration-nextjs) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three components stacked vertically:

1. **Chat header** — displays recipient name, avatar, online status, and optional call buttons
2. **Message list** — real-time chat history with scrolling
3. **Message composer** — text input with media, emojis, and reactions

***

## Full Code

Create the client component with the chat UI, then import it dynamically in your page.

```tsx title="app/chat/CometChatClient.tsx" theme={null}
'use client';

import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
  CometChatProvider,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

const RECIPIENT_UID = "cometchat-uid-2"; // Replace with the UID you want to chat with

export default function CometChatClient() {
  const [ready, setReady] = useState(false);
  const [chatUser, setChatUser] = useState<CometChat.User | undefined>(undefined);

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      const user = await CometChat.getUser(RECIPIENT_UID);
      setChatUser(user);
      setReady(true);
    });
  }, []);

  if (!ready || !chatUser) return <div>Loading chat...</div>;

  return (
    <CometChatProvider>
      <div style={{ display: "flex", flexDirection: "column", height: "100vh", width: "100%" }}>
        <CometChatMessageHeader user={chatUser} />
        <CometChatMessageList user={chatUser} />
        <CometChatMessageComposer user={chatUser} />
      </div>
    </CometChatProvider>
  );
}
```

```tsx title="app/chat/page.tsx" theme={null}
import dynamic from 'next/dynamic';

const CometChatClient = dynamic(() => import('./CometChatClient'), { ssr: false });

export default function ChatPage() {
  return <CometChatClient />;
}
```

Key points:

* `'use client'` is required — CometChat components use browser APIs (DOM, WebSocket).
* `dynamic(() => import(...), { ssr: false })` prevents server-side rendering of the chat component.
* `CometChat.getUser(UID)` fetches the full user object from the SDK — you need a real user object, not a manually constructed one.
* Pass either `user` or `group` to the message components, never both.
* The `RECIPIENT_UID` should be a user that exists in your CometChat app. Use one of the pre-created test UIDs: `cometchat-uid-1` through `cometchat-uid-5`.

***

## Switching to Group Chat

To load a group chat instead of one-to-one, fetch a `Group` object and pass it to the message components:

```tsx title="app/chat/CometChatClient.tsx" theme={null}
'use client';

import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
  CometChatProvider,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

const GROUP_ID = "cometchat-guid-1"; // Replace with your Group ID

export default function CometChatClient() {
  const [ready, setReady] = useState(false);
  const [chatGroup, setChatGroup] = useState<CometChat.Group | undefined>(undefined);

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      const group = await CometChat.getGroup(GROUP_ID);
      setChatGroup(group);
      setReady(true);
    });
  }, []);

  if (!ready || !chatGroup) return <div>Loading chat...</div>;

  return (
    <CometChatProvider>
      <div style={{ display: "flex", flexDirection: "column", height: "100vh", width: "100%" }}>
        <CometChatMessageHeader group={chatGroup} />
        <CometChatMessageList group={chatGroup} />
        <CometChatMessageComposer group={chatGroup} />
      </div>
    </CometChatProvider>
  );
}
```

The only difference: use `CometChat.getGroup(GUID)` instead of `CometChat.getUser(UID)`, and pass `group` instead of `user`.

***

## Run

```bash theme={null}
npm run dev
```

Open `http://localhost:3000/chat`. You should see the chat window load with the conversation for the UID or GUID you set.

***

## Next Steps

<CardGroup>
  <Card title="Conversation List + Messages" icon="comments" href="/ui-kit/react/next-conversation">
    Two-panel layout with a sidebar
  </Card>

  <Card title="Tab-Based Chat" icon="table-columns" href="/ui-kit/react/next-tab-based-chat">
    Tabbed navigation with Chats, Calls, Users
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>
</CardGroup>


# Tab-Based Chat
Source: https://www.cometchat.com/docs/ui-kit/react/next-tab-based-chat

Build a tab-based chat interface with Chat, Call Logs, and Users tabs in Next.js (App Router).

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                                                         |
  | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react`                                                                                                                 |
  | Framework    | Next.js (App Router)                                                                                                                          |
  | Components   | `CometChatConversations`, `CometChatCallLogs`, `CometChatUsers`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Tabbed sidebar (Chat, Calls, Users) + message view                                                                                            |
  | Prerequisite | Complete [Next.js Integration](/docs/ui-kit/react/integration-nextjs) first                                                                        |
  | SSR          | Component loaded with `dynamic(() => import(...), { ssr: false })`                                                                            |
  | Pattern      | Full-featured messaging app with multiple sections                                                                                            |
</Accordion>

This guide builds a tabbed messaging UI — Chat, Calls, and Users tabs in the sidebar, with a message view on the right. Good for full-featured apps that need more than just conversations.

This assumes you've already completed [Next.js Integration](/docs/ui-kit/react/integration-nextjs) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three sections working together:

1. **Tab bar** — switches between Chat, Calls, and Users
2. **Sidebar** — renders the list for the active tab
3. **Message view** — header + messages + composer for the selected item

***

## Full Code

Create the client component with the tabbed UI, then import it dynamically in your page. Init and login happen in a `useEffect` before the provider mounts.

```tsx title="app/chat/CometChatClient.tsx" theme={null}
'use client';

import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
  CometChatProvider,
  CometChatConversations,
  CometChatUsers,
  CometChatCallLogs,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

type Tab = "chat" | "calls" | "users";

export default function CometChatClient() {
  const [ready, setReady] = useState(false);
  const [activeTab, setActiveTab] = useState<Tab>("chat");
  const [selectedUser, setSelectedUser] = useState<CometChat.User | undefined>(undefined);
  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group | undefined>(undefined);

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      setReady(true);
    });
  }, []);

  if (!ready) return <div>Loading chat...</div>;

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setSelectedUser(entity as CometChat.User);
      setSelectedGroup(undefined);
    } else {
      setSelectedGroup(entity as CometChat.Group);
      setSelectedUser(undefined);
    }
  };

  const handleUserClick = (user: CometChat.User) => {
    setSelectedUser(user);
    setSelectedGroup(undefined);
  };

  const handleCallClick = (call: any) => {
    const initiator = call.getInitiator();
    const receiver = call.getReceiver();

    // Determine the other party in the call
    if (receiver instanceof CometChat.User) {
      setSelectedUser(receiver);
      setSelectedGroup(undefined);
    } else if (receiver instanceof CometChat.Group) {
      setSelectedUser(undefined);
      setSelectedGroup(receiver);
    } else if (initiator instanceof CometChat.User) {
      setSelectedUser(initiator);
      setSelectedGroup(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div className="tabbed-chat">
        <div className="sidebar">
          <div className="tab-bar">
            <button
              className={`tab-button ${activeTab === "chat" ? "tab-button--active" : ""}`}
              onClick={() => setActiveTab("chat")}
            >
              Chats
            </button>
            <button
              className={`tab-button ${activeTab === "calls" ? "tab-button--active" : ""}`}
              onClick={() => setActiveTab("calls")}
            >
              Calls
            </button>
            <button
              className={`tab-button ${activeTab === "users" ? "tab-button--active" : ""}`}
              onClick={() => setActiveTab("users")}
            >
              Users
            </button>
          </div>

          <div className="sidebar-list">
            {activeTab === "chat" && (
              <CometChatConversations onItemClick={handleConversationClick} />
            )}
            {activeTab === "calls" && (
              <CometChatCallLogs onItemClick={handleCallClick} />
            )}
            {activeTab === "users" && (
              <CometChatUsers onItemClick={handleUserClick} />
            )}
          </div>
        </div>

        {selectedUser || selectedGroup ? (
          <div className="messages-wrapper">
            <CometChatMessageHeader user={selectedUser} group={selectedGroup} />
            <CometChatMessageList user={selectedUser} group={selectedGroup} />
            <CometChatMessageComposer user={selectedUser} group={selectedGroup} />
          </div>
        ) : (
          <div className="empty-conversation">
            Select a conversation to start chatting
          </div>
        )}
      </div>
    </CometChatProvider>
  );
}
```

```css title="app/chat/chat.css" theme={null}
.tabbed-chat {
  display: flex;
  height: 100vh;
  width: 100%;
}

.sidebar {
  width: 360px;
  height: 100%;
  display: flex;
  flex-direction: column;
  border-right: 1px solid #eee;
}

.tab-bar {
  display: flex;
  border-bottom: 1px solid #eee;
  background: var(--cometchat-background-color-01, #fff);
}

.tab-button {
  flex: 1;
  padding: 12px 0;
  border: none;
  background: none;
  cursor: pointer;
  font: var(--cometchat-font-body-medium, 500 14px Roboto);
  color: var(--cometchat-text-color-secondary, #727272);
  border-bottom: 2px solid transparent;
  transition: color 0.2s, border-color 0.2s;
}

.tab-button:hover {
  color: var(--cometchat-text-color-primary, #141414);
}

.tab-button--active {
  color: var(--cometchat-text-color-highlight, #6851d6);
  border-bottom-color: var(--cometchat-primary-color, #6851d6);
}

.sidebar-list {
  flex: 1;
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

.messages-wrapper {
  flex: 1;
  height: 100%;
  display: flex;
  flex-direction: column;
}

.empty-conversation {
  flex: 1;
  display: flex;
  justify-content: center;
  align-items: center;
  background: var(--cometchat-background-color-03, #f5f5f5);
  color: var(--cometchat-text-color-secondary, #727272);
  font: var(--cometchat-font-body-regular, 400 14px Roboto);
}
```

```tsx title="app/chat/page.tsx" theme={null}
import dynamic from 'next/dynamic';

const CometChatClient = dynamic(() => import('./CometChatClient'), { ssr: false });

export default function ChatPage() {
  return <CometChatClient />;
}
```

***

## How It Works

1. **`'use client'`** marks the component as a Client Component — required because CometChat uses browser APIs.
2. **`dynamic(() => import(...), { ssr: false })`** prevents the component from rendering on the server.
3. **Tab state** — `activeTab` controls which list component renders in the sidebar.
4. **Conditional rendering** — only the active tab's component mounts. Switching tabs unmounts the previous list and mounts the new one.
5. **Unified selection** — all three tabs feed into the same `selectedUser` / `selectedGroup` state. Clicking any item (conversation, call log, or user) updates the message panel.
6. **Call log handling** — when a call log is clicked, the receiver (user or group) is extracted and passed to the message components.

***

## Adding More Tabs

To add a Groups tab, import `CometChatGroups` and add another tab button + conditional render:

```tsx theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react";

// Add to Tab type:
type Tab = "chat" | "calls" | "users" | "groups";

// Add button in tab-bar:
<button
  className={`tab-button ${activeTab === "groups" ? "tab-button--active" : ""}`}
  onClick={() => setActiveTab("groups")}
>
  Groups
</button>

// Add in sidebar-list:
{activeTab === "groups" && (
  <CometChatGroups
    onItemClick={(group: CometChat.Group) => {
      setSelectedGroup(group);
      setSelectedUser(undefined);
    }}
  />
)}
```

You can follow the same pattern for any additional tabs (Settings, Contacts, etc.).

***

## Run

```bash theme={null}
npm run dev
```

Open `http://localhost:3000/chat`. You should see the tab bar at the top of the sidebar. Switch between Chats, Calls, and Users — clicking any item loads the message view on the right.

***

## Next Steps

<CardGroup>
  <Card title="Conversation List + Messages" icon="comments" href="/ui-kit/react/next-conversation">
    Two-panel layout without tabs
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and styles
  </Card>
</CardGroup>


# React UI Kit
Source: https://www.cometchat.com/docs/ui-kit/react/overview

Prebuilt React components for chat, voice, and video calling. Supports React.js, Next.js, React Router, and Astro.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                       |
  | ------------ | ------------------------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react` v7.0.x                                                        |
  | Peer deps    | `react` >=18, `react-dom` >=18, `@cometchat/chat-sdk-javascript` ^4.1.9, `dompurify` ^3.3.1 |
  | Calling      | Optional — `@cometchat/calls-sdk-javascript`                                                |
  | SSR          | SSR-safe — no browser APIs at module scope. Next.js App Router compatible.                  |
  | Localization | 19 languages built-in                                                                       |
  | Source       | [GitHub](https://github.com/cometchat/cometchat-uikit-react/tree/v7)                        |
</Accordion>

The CometChat React UI Kit provides prebuilt, customizable components for adding chat, voice, and video calling to any React app. Each component handles its own data fetching, real-time listeners, and state — you just drop them into your layout.

<Frame>
  <img />
</Frame>

***

## Try It

<CardGroup>
  <Card title="Live Demo" icon="play" href="https://link.cometchat.com/cometchat-demo">
    Try the full chat experience in your browser
  </Card>

  <Card title="CodeSandbox" icon="code" href="https://link.cometchat.com/react-conversation-list-message">
    Fork, add your credentials, and start building
  </Card>
</CardGroup>

***

## Get Started

Pick your framework and follow the step-by-step integration guide:

<CardGroup>
  <Card title="React.js" icon="react" href="/ui-kit/react/integration-react">
    Vite or Create React App
  </Card>

  <Card title="Next.js" icon="server" href="/ui-kit/react/integration-nextjs">
    App Router with client-side rendering
  </Card>

  <Card title="React Router" icon="route" href="/ui-kit/react/integration-react-router">
    SPA with React Router v6+
  </Card>

  <Card title="Astro" icon="rocket" href="/ui-kit/react/integration-astro">
    React islands with client:only directive
  </Card>
</CardGroup>

***

## What's Included

* **Compound components** — compose only what you need using namespace sub-components (Root, View, EmptyState, etc.)
* **Plugin system** — extensible message rendering via `CometChatMessagePlugin` interface
* **Theming** — CSS custom properties (`--cometchat-*`) with built-in light and dark themes
* **Localization** — 19 supported languages with customizable translation keys
* **Calling** — optional voice and video calling via `@cometchat/calls-sdk-javascript`
* **SSR-safe** — no browser-only APIs at module scope; Next.js App Router compatible
* **Tree-shakeable** — ESM-first build with dual ESM + CJS output

***

## Prerequisites

Before integrating the UI Kit, ensure you have:

* **Node.js 18+** installed
* A **CometChat account** with the following credentials:
  * `appId` — your CometChat application ID
  * `region` — your app region (e.g., `"us"` or `"eu"`)
  * `authKey` — your CometChat auth key (for client-side authentication)

You can find these values in the [CometChat Dashboard](https://app.cometchat.com).

### Installation

```bash theme={null}
npm install @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript react react-dom dompurify
```

| Package                           | Version                            |
| --------------------------------- | ---------------------------------- |
| `@cometchat/chat-uikit-react`     | `^7.0.0`                           |
| `@cometchat/chat-sdk-javascript`  | `^4.1.9`                           |
| `react`                           | `>=18.0.0 <21.0.0`                 |
| `react-dom`                       | `>=18.0.0 <21.0.0`                 |
| `dompurify`                       | `^3.3.1`                           |
| `@cometchat/calls-sdk-javascript` | Optional — for voice/video calling |

***

## Explore

<CardGroup>
  <Card title="Components" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Colors, fonts, dark mode, and custom styling
  </Card>

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

  <Card title="Guides" icon="book" href="/ui-kit/react/guide-threaded-messages">
    Threaded messages, new chat, search, and more
  </Card>
</CardGroup>

***

## Resources

<CardGroup>
  <Card title="Sample App" icon="github" href="https://github.com/cometchat/cometchat-uikit-react/tree/v7/sample-app">
    Working reference app
  </Card>

  <Card title="Source Code" icon="code" href="https://github.com/cometchat/cometchat-uikit-react/tree/v7">
    Full UI Kit source on GitHub
  </Card>

  <Card title="Figma" icon="figma" href="https://www.figma.com/community/file/1442863561340379957/cometchat-ui-kit-for-web">
    Design resources and prototyping
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/react/troubleshooting">
    Common issues and fixes
  </Card>

  <Card title="Support" icon="headset" href="https://help.cometchat.com/hc/en-us/requests/new">
    Open a support ticket
  </Card>

  <Card title="Migration Guide" icon="arrow-up" href="/ui-kit/react/migration-overview">
    Upgrading from v6
  </Card>
</CardGroup>


# Creating a Custom Plugin
Source: https://www.cometchat.com/docs/ui-kit/react/plugins/custom-plugin

Build a custom message plugin for rendering, context menus, and conversation previews, plus the plugin interface and context reference.

Custom plugins let you handle any message type with your own rendering logic. This walkthrough builds a complete "Location" plugin that renders a map preview, provides context menu options, and shows a conversation preview.

## Step 1: Define the Plugin

Create a file that implements `CometChatMessagePlugin`:

```tsx title="src/plugins/LocationPlugin.tsx" theme={null}
import React from "react";
import type { CometChat } from "@cometchat/chat-sdk-javascript";
import type {
  CometChatMessagePlugin,
  CometChatMessagePluginContext,
  CometChatMessageOption,
} from "@cometchat/chat-uikit-react";

// Extract location data from the custom message
function getLocationData(message: CometChat.BaseMessage) {
  const customMessage = message as CometChat.CustomMessage;
  const data = customMessage.getCustomData() as {
    latitude?: number;
    longitude?: number;
    address?: string;
  } | undefined;
  return {
    latitude: data?.latitude ?? 0,
    longitude: data?.longitude ?? 0,
    address: data?.address ?? "",
  };
}

export const LocationPlugin: CometChatMessagePlugin = {
  id: "location",
  messageTypes: ["location"],
  messageCategories: ["custom"],

  renderBubble(message: CometChat.BaseMessage, context: CometChatMessagePluginContext) {
    const { latitude, longitude, address } = getLocationData(message);
    const mapUrl = `https://maps.googleapis.com/maps/api/staticmap?center=${latitude},${longitude}&zoom=15&size=300x200&markers=${latitude},${longitude}&key=YOUR_API_KEY`;

    return (
      <div className="location-bubble">
        <img
          src={mapUrl}
          alt={address || "Location"}
          style={{ borderRadius: 8, width: "100%", maxWidth: 300 }}
        />
        {address && (
          <p style={{ margin: "8px 0 0", fontSize: 13, color: "#666" }}>
            {address}
          </p>
        )}
        <a
          href={`https://maps.google.com/?q=${latitude},${longitude}`}
          target="_blank"
          rel="noopener noreferrer"
          style={{ fontSize: 12, color: "#6851FF" }}
        >
          Open in Maps
        </a>
      </div>
    );
  },

  getOptions(
    message: CometChat.BaseMessage,
    context: CometChatMessagePluginContext
  ): CometChatMessageOption[] {
    const options: CometChatMessageOption[] = [];

    // Copy coordinates
    options.push({
      id: "copy-location",
      title: "Copy Location",
      onClick: (msg) => {
        const { latitude, longitude } = getLocationData(msg);
        void navigator.clipboard.writeText(`${latitude}, ${longitude}`);
        context.showToast?.("Location copied to clipboard");
      },
    });

    // Delete (sender only)
    options.push({
      id: "delete",
      title: context.getLocalizedString?.("delete") ?? "Delete",
      senderOnly: true,
      onClick: (msg) => context.onDeleteMessage?.(msg),
    });

    return options;
  },

  getLastMessagePreview(
    message: CometChat.BaseMessage
  ): string {
    const { address } = getLocationData(message);
    return address ? `📍 ${address}` : "📍 Location";
  },
};
```

## Step 2: Register the Plugin

Pass your plugin to `CometChatProvider`:

```tsx title="src/App.tsx" theme={null}
import { CometChatProvider } from "@cometchat/chat-uikit-react";
import { LocationPlugin } from "./plugins/LocationPlugin";

function App() {
  return (
    <CometChatProvider plugins={[LocationPlugin]}>
      <MyChatApp />
    </CometChatProvider>
  );
}
```

Your plugin is prepended before the default plugins. Since resolution is first-match, your custom plugins take precedence for the types they declare — here the plugin handles `"location"` messages, a type no built-in plugin claims. To override a built-in type instead, declare the same `messageTypes`/`messageCategories` as the default plugin.

## Step 3: Send a Location Message

Use the CometChat SDK to send a custom message with type `"location"`:

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatUIKit } from "@cometchat/chat-uikit-react";

async function sendLocation(receiverUid: string, lat: number, lng: number) {
  const message = new CometChat.CustomMessage(
    receiverUid,
    CometChat.RECEIVER_TYPE.USER,
    "location",
    { latitude: lat, longitude: lng, address: "123 Main St" }
  );

  await CometChatUIKit.sendCustomMessage(message);
}
```

## Step 4: Style the Bubble

```css title="src/plugins/LocationPlugin.css" theme={null}
.location-bubble {
  padding: 4px;
  max-width: 300px;
}

.location-bubble img {
  display: block;
  border-radius: 8px;
}
```

## Plugin Interface Reference

```typescript theme={null}
interface CometChatMessagePlugin {
  /** Unique plugin identifier. */
  id: string;

  /** SDK message types this plugin handles (e.g., ["text"], ["image"]). */
  messageTypes: string[];

  /** SDK message categories this plugin handles (e.g., ["message"], ["custom"]). */
  messageCategories: string[];

  /** Render the bubble content for a message. */
  renderBubble(message: BaseMessage, context: PluginContext): ReactNode;

  /** Return context menu options for a message. */
  getOptions?(message: BaseMessage, context: PluginContext): MessageOption[];

  /** Return plain-text preview for the conversation list subtitle. */
  getLastMessagePreview?(message: BaseMessage, loggedInUser: User, t?: (key: string) => string): string;

  /** Return text formatters (only relevant for text plugin). */
  getTextFormatters?(): CometChatTextFormatter[];

  // --- View Slot Methods (optional) ---
  renderLeadingView?(message: BaseMessage, context: PluginContext): ReactNode;
  renderHeaderView?(message: BaseMessage, context: PluginContext): ReactNode;
  renderFooterView?(message: BaseMessage, context: PluginContext): ReactNode;
  renderBottomView?(message: BaseMessage, context: PluginContext): ReactNode;
  renderStatusInfoView?(message: BaseMessage, context: PluginContext): ReactNode;
  renderReplyView?(message: BaseMessage, context: PluginContext): ReactNode;
  renderThreadView?(message: BaseMessage, context: PluginContext): ReactNode;
}
```

## Plugin Context

The `context` object passed to every plugin method:

| Field                | Type                            | Description                               |
| -------------------- | ------------------------------- | ----------------------------------------- |
| `loggedInUser`       | `CometChat.User`                | The currently logged-in user              |
| `group`              | `CometChat.Group \| undefined`  | The group (if group chat)                 |
| `alignment`          | `"left" \| "right" \| "center"` | Bubble alignment                          |
| `theme`              | `"light" \| "dark"`             | Current theme                             |
| `getLocalizedString` | `(key: string) => string`       | Localization function                     |
| `onDeleteMessage`    | `(msg) => void`                 | Delete a message                          |
| `onEditMessage`      | `(msg) => void`                 | Enter edit mode                           |
| `onReplyMessage`     | `(msg) => void`                 | Set reply-to target                       |
| `onThreadClick`      | `(msg) => void`                 | Open thread view                          |
| `onReactToMessage`   | `(msg) => void`                 | Open emoji picker                         |
| `onMessageInfo`      | `(msg) => void`                 | Open message info panel                   |
| `onMarkAsUnread`     | `(msg) => void`                 | Mark as unread                            |
| `onFlagMessage`      | `(msg) => void`                 | Open flag/report dialog                   |
| `showToast`          | `(text) => void`                | Show a toast notification                 |
| `getTextFormatters`  | `() => Formatter[]`             | Get text formatters for caption rendering |
| `publish`            | `(event) => void`               | Publish a UI event                        |

## Tips

* **Lazy-load heavy components** — use `React.lazy()` + `Suspense` for bubble components that import large libraries
* **Use `context.getLocalizedString`** — for any user-facing text in options or bubbles
* **Return `[]` from `getOptions`** — for system messages that shouldn't have a context menu
* **Keep `getLastMessagePreview` short** — max \~100 characters, plain text only (no HTML)
* **A single plugin can handle multiple types** — like the Call Action plugin handles both `audio` and `video` in the `call` category


# Plugins
Source: https://www.cometchat.com/docs/ui-kit/react/plugins/overview

How the plugin system renders messages, the built-in plugins, and the AI plugin.

## What is a Plugin?

A plugin owns one or more message types. It tells the UI Kit:

* **How to render the message** as a bubble in the message list
* **What context menu options** to show when a user hovers/long-presses a message
* **What preview text** to display in the Conversations list subtitle

Every message that appears in the UI is rendered by a plugin. If no plugin matches a message type, the message is not displayed.

Plugins are a thin routing layer — they decide which bubble component renders a message and provide context menu options and conversation previews. The **bubble components themselves are standalone** and documented under [Message Bubbles](/docs/ui-kit/react/components/message-bubble); this page links each plugin to its component instead of repeating that detail.

***

## Where Plugins Are Used

| Location               | Plugin Method                                    | What it does                                                                                      |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| **Message List**       | `renderBubble()`                                 | Routes to the appropriate bubble component (e.g., `CometChatTextBubble`, `CometChatImagesBubble`) |
| **Message List**       | `getOptions()`                                   | Provides context menu items (reply, edit, delete, copy, react)                                    |
| **Conversations List** | `getLastMessagePreview()`                        | Returns subtitle text ("📷 Photo", "You: Hello", "🎥 Video")                                      |
| **Message Bubble**     | `renderHeaderView()`, `renderFooterView()`, etc. | Customizes bubble regions beyond content                                                          |

***

## The Plugin Interface

Every plugin implements the `CometChatMessagePlugin` interface. Three members are **required**; everything else is optional and lets you override a specific bubble region or behavior.

| Member                  | Signature                                        | Required | Purpose                                                                                    |
| ----------------------- | ------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------ |
| `id`                    | `string`                                         | Yes      | Unique plugin identifier (e.g. `'text'`, `'polls'`)                                        |
| `messageTypes`          | `string[]`                                       | Yes      | SDK message types this plugin handles                                                      |
| `messageCategories`     | `string[]`                                       | Yes      | SDK message categories this plugin handles                                                 |
| `renderBubble`          | `(message, context) => ReactNode`                | Yes      | Render the inner bubble content (the outer wrapper is handled by `CometChatMessageBubble`) |
| `getOptions`            | `(message, context) => CometChatMessageOption[]` | Optional | Context menu options for the message (return `[]` for none)                                |
| `getLastMessagePreview` | `(message, loggedInUser, t?) => string`          | Optional | Plain-text subtitle shown in the Conversations list                                        |
| `getTextFormatters`     | `() => CometChatTextFormatter[]`                 | Optional | Text formatters this plugin provides (only the text plugin uses this)                      |
| `renderLeadingView`     | `(message, context) => ReactNode`                | Optional | Override the leading view (avatar area)                                                    |
| `renderHeaderView`      | `(message, context) => ReactNode`                | Optional | Override the header view (sender name area)                                                |
| `renderFooterView`      | `(message, context) => ReactNode`                | Optional | Override the footer view (reactions area)                                                  |
| `renderBottomView`      | `(message, context) => ReactNode`                | Optional | Override the bottom view (moderation / error footer)                                       |
| `renderStatusInfoView`  | `(message, context) => ReactNode`                | Optional | Override the status info (timestamp + receipts + "edited")                                 |
| `renderReplyView`       | `(message, context) => ReactNode`                | Optional | Override the reply view (quoted-message preview)                                           |
| `renderThreadView`      | `(message, context) => ReactNode`                | Optional | Override the thread view (reply-count indicator)                                           |

For the view-slot methods (`render*View`), return a `ReactNode` to override the region, `null` to suppress it, or `undefined` to keep the built-in default. The full TypeScript interface and the `context` object reference are documented in [Creating a Custom Plugin](/docs/ui-kit/react/plugins/custom-plugin).

***

## How Plugin Resolution Works

When the UI Kit needs to render a message, it asks the **Plugin Registry** to find the right plugin:

1. If the message is deleted (`getDeletedAt() !== null`), the Delete plugin handles it
2. Otherwise, the registry finds the first plugin whose `messageTypes` includes the message's type AND whose `messageCategories` includes the message's category
3. First match wins — plugin order matters. Custom plugins passed via the `plugins` prop are placed **before** the defaults, so a custom plugin can override a built-in one for the same type

```
Message { type: "image", category: "message" }
  → Registry scans plugins in order
  → CometChatImagePlugin matches (messageTypes: ["image"], messageCategories: ["message"])
  → ImagePlugin.renderBubble() is called
```

<Note>
  Precedence is determined by **plugin order** (your custom plugins first, defaults after) and matched by `messageTypes` + `messageCategories` — **not** by `id`. The `id` field is a required unique identifier for the plugin; it is not the override mechanism.
</Note>

***

## Adding Plugins

All default plugins are always included. To add your own custom plugins, pass them via the `plugins` prop on `CometChatProvider`. They are **prepended before the defaults**, so a custom plugin takes priority for its message types (first match wins) — letting you override a built-in plugin by declaring the same `messageTypes`/`messageCategories`:

```tsx theme={null}
import { CometChatProvider } from "@cometchat/chat-uikit-react";
import { MyCustomPlugin } from "./plugins/MyCustomPlugin";

function App() {
  return (
    <CometChatProvider plugins={[MyCustomPlugin]}>
      <MyChatApp />
    </CometChatProvider>
  );
}
```

***

## Built-in Plugins

These plugins are included automatically — no configuration needed. Each routes its message type to a bubble component; follow the component link for the full rendering behavior, props, and CSS.

| Plugin                       | Message type(s)                             | Category  | What it renders                                                                   | Component                                                                                   |
| ---------------------------- | ------------------------------------------- | --------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Text**                     | `text`                                      | `message` | Formatted text with @mentions, clickable URLs, and markdown                       | [Text Bubble](/docs/ui-kit/react/components/text-bubble)                                         |
| **Image**                    | `image`                                     | `message` | Responsive image grid with captions, batch grouping, and a fullscreen gallery     | [Image Bubble](/docs/ui-kit/react/components/image-bubble)                                       |
| **Video**                    | `video`                                     | `message` | Video grid with poster thumbnails, duration overlays, and a fullscreen viewer     | [Video Bubble](/docs/ui-kit/react/components/video-bubble)                                       |
| **File**                     | `file`                                      | `message` | Stacked file cards with type icons, size, and download                            | [File Bubble](/docs/ui-kit/react/components/file-bubble)                                         |
| **Audio**                    | `audio`                                     | `message` | Attached audio as stacked player cards; recorded voice notes as a waveform player | [Audio Bubble](/docs/ui-kit/react/components/audio-bubble)                                       |
| **Polls**                    | `extension_poll`                            | `custom`  | Interactive poll with voting and live results                                     | [Poll Bubble](/docs/ui-kit/react/components/poll-bubble)                                         |
| **Stickers**                 | `extension_sticker`                         | `custom`  | Sticker image extracted from the message metadata                                 | [Sticker Bubble](/docs/ui-kit/react/components/sticker-bubble)                                   |
| **Collaborative Document**   | `extension_document`                        | `custom`  | Document card with an "Open Document" button                                      | [Collaborative Document Bubble](/docs/ui-kit/react/components/collaborative-document-bubble)     |
| **Collaborative Whiteboard** | `extension_whiteboard`                      | `custom`  | Whiteboard card with an "Open Whiteboard" button                                  | [Collaborative Whiteboard Bubble](/docs/ui-kit/react/components/collaborative-whiteboard-bubble) |
| **Card**                     | any                                         | `card`    | Developer-defined card messages, drawn by the `CometChatCardView` renderer        | [Card Bubble](/docs/ui-kit/react/components/card-bubble)                                         |
| **Group Action**             | `groupMember`                               | `action`  | Centered system messages (joined, left, kicked, banned, scope change)             | [Group Action Bubble](/docs/ui-kit/react/components/group-action-bubble)                         |
| **Call Action**              | `audio` / `video`                           | `call`    | Centered call status messages (missed, outgoing, incoming, ended)                 | [Call Action Bubble](/docs/ui-kit/react/components/call-action-bubble)                           |
| **Meeting**                  | `meeting`                                   | `custom`  | Group/conference call invite card with a **Join** button                          | [Call Bubble](/docs/ui-kit/react/components/call-bubble)                                         |
| **AI**                       | `assistant`, `toolArguments`, `toolResults` | `agentic` | AI assistant responses, tool call arguments/results, and a streaming bubble       | [AI Plugin ↓](#ai-plugin)                                                                   |
| **Delete**                   | any (deleted)                               | any       | "This message was deleted" placeholder                                            | [Delete Bubble](/docs/ui-kit/react/components/delete-bubble)                                     |

***

## AI Plugin

The AI plugin handles messages in the `agentic` category. It renders completed assistant responses (with markdown), tool call arguments and results (as formatted JSON), and a streaming bubble while the AI is generating. It is **included by default** — no installation or `plugins` configuration is required.

<Frame>
  <img />
</Frame>

### Message Types

| Type            | Category  | What it renders                       |
| --------------- | --------- | ------------------------------------- |
| `assistant`     | `agentic` | Completed AI response with markdown   |
| `toolArguments` | `agentic` | Tool call arguments as formatted JSON |
| `toolResults`   | `agentic` | Tool call results as formatted JSON   |

Bubble components: `CometChatAIAssistantBubble`, `CometChatStreamMessageBubble`, `CometChatToolCallArgumentBubble`, `CometChatToolCallResultBubble`. AI messages are system-generated and have no context menu. For the full chat experience, see [AI Assistant Chat](/docs/ui-kit/react/components/ai-assistant-chat).

### Conversation Preview

| Type            | Preview text                                            |
| --------------- | ------------------------------------------------------- |
| `assistant`     | First 80 characters of the response (markdown stripped) |
| `toolArguments` | "Tool call"                                             |
| `toolResults`   | "Tool result"                                           |

### Preloading

The AI Assistant Chat panel can be preloaded on hover/focus to reduce perceived latency:

```tsx theme={null}
import { preloadAIAssistantChat } from "@cometchat/chat-uikit-react";

// Call on AI button hover
onMouseEnter={() => preloadAIAssistantChat()}
```


# Text Formatters
Source: https://www.cometchat.com/docs/ui-kit/react/plugins/text-formatters

Transform plain text into formatted HTML in message bubbles, with built-in URL, mention, and markdown formatters plus custom formatters.

Text formatters detect patterns in message text and transform them into formatted HTML for display in bubbles. They run as a pipeline — each formatter receives the output of the previous one, sorted by priority (lower number = runs first). The Text plugin provides three built-in formatters, and you can add your own.

## Built-in Formatters

| Formatter                    | Priority | Detects                                                       | Output                                   |
| ---------------------------- | -------- | ------------------------------------------------------------- | ---------------------------------------- |
| `CometChatMarkdownFormatter` | 10       | `**bold**`, `_italic_`, `` `code` ``, `> quote`, lists, links | HTML tags (`<b>`, `<i>`, `<code>`, etc.) |
| `CometChatMentionsFormatter` | 50       | `<@uid:xxx>` tokens                                           | Styled `@DisplayName` chips              |
| `CometChatUrlFormatter`      | 100      | `https://...`, `www.`                                         | Clickable `<a>` links                    |

```
Raw text: "Hey **@Alice**, check https://example.com"
  ↓ MarkdownFormatter (priority 10)
"Hey <b>@Alice</b>, check https://example.com"
  ↓ MentionsFormatter (priority 50)
"Hey <b><span class="mention">@Alice</span></b>, check https://example.com"
  ↓ UrlFormatter (priority 100)
"Hey <b><span class="mention">@Alice</span></b>, check <a href="...">https://example.com</a>"
```

## The Formatter Interface

All formatters extend the abstract `CometChatTextFormatter` class:

```typescript theme={null}
abstract class CometChatTextFormatter {
  /** Unique identifier. */
  abstract readonly id: string;

  /** Priority in the pipeline (lower = runs first). Default: 100. */
  priority: number;

  /** Regex pattern for detecting formattable content. */
  abstract getRegex(): RegExp;

  /** Transform the input text. Must store originalText, apply changes, return formattedText. */
  abstract format(text: string): string;

  /** Whether this formatter should process the given text. Override to skip conditionally. */
  shouldFormat(text: string, message?: BaseMessage): boolean;

  /** Reset internal state. */
  reset(): void;
}
```

## Creating a Custom Formatter

Here's a hashtag formatter that wraps `#word` patterns in a styled span:

```typescript title="src/formatters/HashtagFormatter.ts" theme={null}
import { CometChatTextFormatter } from "@cometchat/chat-uikit-react";

export class HashtagFormatter extends CometChatTextFormatter {
  readonly id = "hashtag-formatter";
  override priority = 90; // After mentions (50), before URLs (100)

  private hashtags: string[] = [];

  getRegex(): RegExp {
    return /(#\w+)/g;
  }

  format(text: string): string {
    if (!text) {
      this.originalText = "";
      this.formattedText = "";
      this.hashtags = [];
      return "";
    }

    this.originalText = text;
    this.hashtags = [];

    this.formattedText = text.replace(this.getRegex(), (match) => {
      this.hashtags.push(match);
      return `<span class="cometchat-hashtag" style="color: #6851FF; font-weight: 500;">${match}</span>`;
    });

    this.metadata = { hashtags: this.hashtags };
    return this.formattedText;
  }

  /** Get detected hashtags from the last format() call. */
  getHashtags(): string[] {
    return [...this.hashtags];
  }

  override reset(): void {
    super.reset();
    this.hashtags = [];
  }
}
```

## Registering Custom Formatters

Custom formatters are registered by creating a custom text plugin that provides them:

```typescript title="src/plugins/CustomTextPlugin.ts" theme={null}
import { CometChatTextPlugin } from "@cometchat/chat-uikit-react";
import type { CometChatTextFormatter } from "@cometchat/chat-uikit-react";
import {
  CometChatMarkdownFormatter,
  CometChatMentionsFormatter,
  CometChatUrlFormatter,
} from "@cometchat/chat-uikit-react";
import { HashtagFormatter } from "../formatters/HashtagFormatter";

export const CustomTextPlugin = {
  ...CometChatTextPlugin,
  id: "custom-text",

  getTextFormatters(): CometChatTextFormatter[] {
    return [
      new CometChatMarkdownFormatter(),   // priority 10
      new CometChatMentionsFormatter(),   // priority 50
      new HashtagFormatter(),             // priority 90
      new CometChatUrlFormatter(),        // priority 100
    ];
  },
};
```

Then pass it in your provider's `plugins` prop:

```tsx theme={null}
import { CometChatProvider } from "@cometchat/chat-uikit-react";
import { CustomTextPlugin } from "./plugins/CustomTextPlugin";

<CometChatProvider plugins={[CustomTextPlugin]}>
  <MyChatApp />
</CometChatProvider>
```

Since user plugins are prepended before the defaults in the registry, your custom text plugin takes precedence over the built-in one (first match wins).

## Formatter Details

### CometChatMarkdownFormatter

Converts markdown syntax to HTML. Runs first (priority 10) so subsequent formatters operate on HTML output.

* `**bold**` → `<b>bold</b>`
* `_italic_` → `<i>italic</i>`
* `__underline__` or `++underline++` → `<u>underline</u>`
* `~~strikethrough~~` → `<s>strikethrough</s>`
* `` `inline code` `` → `<code>inline code</code>`
* ` ```code block``` ` → `<pre><code>code block</code></pre>`
* `> blockquote` → `<blockquote>blockquote</blockquote>`
* `[text](url)` → `<a href="url">text</a>`
* `1. item` → ordered list; `• item` / `- item` → unordered list

### CometChatMentionsFormatter

Resolves SDK mention tokens (`<@uid:xxx>` and `<@all:label>`) into styled mention chips. Requires the mentioned-users list from the message to resolve UIDs to display names.

### CometChatUrlFormatter

Detects bare URLs (`https://...` and `www.`) and wraps them in clickable `<a>` tags with `target="_blank"` and `rel="noopener noreferrer"`. Protects existing markdown links and `<a>` tags from double-processing.

## Tips

* **Priority matters** — markdown must run before mentions/URLs so it doesn't break HTML tags
* **Protect code blocks** — formatters should skip content inside `<code>` and `<pre>` tags
* **Keep it fast** — formatters run on every text message render; avoid expensive operations
* **Use `shouldFormat()`** — override to skip formatting for specific messages
* **Store metadata** — use `this.metadata` to expose extracted data (URLs, hashtags, mentions) to consumers


# Conversation List + Message View
Source: https://www.cometchat.com/docs/ui-kit/react/react-conversation

Build a two-panel conversation list + message view layout in React.js with CometChat UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                  |
  | ------------ | ------------------------------------------------------------------------------------------------------ |
  | Package      | `@cometchat/chat-uikit-react`                                                                          |
  | Framework    | React.js                                                                                               |
  | Components   | `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Two-panel — conversation list (left) + message view (right)                                            |
  | Prerequisite | Complete [React.js Integration](/docs/ui-kit/react/integration-react) first                                 |
  | Pattern      | WhatsApp Web, Slack, Microsoft Teams                                                                   |
</Accordion>

This guide builds a two-panel chat layout — conversation list on the left, messages on the right. Users click a conversation to open it.

This assumes you've already completed [React.js Integration](/docs/ui-kit/react/integration-react) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three sections working together:

1. **Sidebar (conversation list)** — shows all active conversations (users and groups)
2. **Message view** — displays chat messages for the selected conversation in real time
3. **Message composer** — text input with support for media, emojis, and reactions

***

## Full Code

Replace your `src/App.tsx` with the following. Init and login must complete before the provider mounts — see the [React.js Integration](/docs/ui-kit/react/integration-react) guide for the `src/main.tsx` setup.

```tsx title="src/App.tsx" theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";
import "./App.css";

function App() {
  const [selectedUser, setSelectedUser] = useState<CometChat.User | undefined>(undefined);
  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group | undefined>(undefined);

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setSelectedUser(entity as CometChat.User);
      setSelectedGroup(undefined);
    } else {
      setSelectedGroup(entity as CometChat.Group);
      setSelectedUser(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div className="conversations-with-messages">
        <div className="conversations-wrapper">
          <CometChatConversations onItemClick={handleConversationClick} />
        </div>

        {selectedUser || selectedGroup ? (
          <div className="messages-wrapper">
            <CometChatMessageHeader user={selectedUser} group={selectedGroup} />
            <CometChatMessageList user={selectedUser} group={selectedGroup} />
            <CometChatMessageComposer user={selectedUser} group={selectedGroup} />
          </div>
        ) : (
          <div className="empty-conversation">
            Select a conversation to start chatting
          </div>
        )}
      </div>
    </CometChatProvider>
  );
}

export default App;
```

```css title="src/App.css" theme={null}
.conversations-with-messages {
  display: flex;
  height: 100vh;
  width: 100%;
}

.conversations-wrapper {
  width: 360px;
  height: 100%;
  border-right: 1px solid #eee;
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

.messages-wrapper {
  flex: 1;
  height: 100%;
  display: flex;
  flex-direction: column;
}

.empty-conversation {
  flex: 1;
  display: flex;
  justify-content: center;
  align-items: center;
  background: var(--cometchat-background-color-03, #f5f5f5);
  color: var(--cometchat-text-color-secondary, #727272);
  font: var(--cometchat-font-body-regular, 400 14px Roboto);
}
```

***

## How It Works

1. **CometChatProvider** wraps the entire tree — it supplies theme, locale, and event context to all CometChat components.
2. **CometChatConversations** renders the sidebar list. When a user clicks a conversation, `onItemClick` fires with the `Conversation` object.
3. **handleConversationClick** extracts the `User` or `Group` from the conversation and stores it in state.
4. **Message components** (`MessageHeader`, `MessageList`, `MessageComposer`) receive either `user` or `group` as a prop — never both at the same time.
5. When the user switches conversations, state updates and the message panel re-renders with the new chat.

***

## Run

```bash theme={null}
npm run dev
```

Open `http://localhost:5173`. You should see the conversation list on the left. Click any conversation to load messages on the right.

***

## Next Steps

<CardGroup>
  <Card title="One-to-One / Group Chat" icon="message" href="/ui-kit/react/react-one-to-one-chat">
    Single chat window without a sidebar
  </Card>

  <Card title="Tab-Based Chat" icon="table-columns" href="/ui-kit/react/react-tab-based-chat">
    Tabbed navigation with Chats, Calls, Users
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and styles
  </Card>
</CardGroup>


# One-to-One / Group Chat
Source: https://www.cometchat.com/docs/ui-kit/react/react-one-to-one-chat

Build a single chat window for one-to-one or group messaging in React.js with CometChat UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                        |
  | ------------ | ---------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react`                                                |
  | Framework    | React.js                                                                     |
  | Components   | `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Single chat window — no sidebar, no conversation list                        |
  | Prerequisite | Complete [React.js Integration](/docs/ui-kit/react/integration-react) first       |
  | Pattern      | Support chat, embedded widgets, focused messaging                            |
</Accordion>

This guide builds a single chat window — no sidebar, no conversation list. Users go directly into a one-to-one or group chat. Good for support chat, embedded widgets, or any focused messaging experience.

This assumes you've already completed [React.js Integration](/docs/ui-kit/react/integration-react) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three components stacked vertically:

1. **Chat header** — displays recipient name, avatar, online status, and optional call buttons
2. **Message list** — real-time chat history with scrolling
3. **Message composer** — text input with media, emojis, and reactions

***

## Full Code

Replace your `src/App.tsx` with the following. Init and login must complete before the provider mounts — see the [React.js Integration](/docs/ui-kit/react/integration-react) guide for the `src/main.tsx` setup.

```tsx title="src/App.tsx" theme={null}
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";
import "./App.css";

const RECIPIENT_UID = "cometchat-uid-2"; // Replace with the UID you want to chat with

function App() {
  const [chatUser, setChatUser] = useState<CometChat.User | undefined>(undefined);

  useEffect(() => {
    CometChat.getUser(RECIPIENT_UID).then(
      (user) => setChatUser(user),
      (error) => console.error("User fetch failed:", error)
    );
  }, []);

  if (!chatUser) return <div>Loading chat...</div>;

  return (
    <CometChatProvider>
      <div className="chat-window">
        <CometChatMessageHeader user={chatUser} />
        <CometChatMessageList user={chatUser} />
        <CometChatMessageComposer user={chatUser} />
      </div>
    </CometChatProvider>
  );
}

export default App;
```

```css title="src/App.css" theme={null}
.chat-window {
  display: flex;
  flex-direction: column;
  height: 100vh;
  width: 100%;
}
```

Key points:

* `CometChat.getUser(UID)` fetches the full user object from the SDK — you need a real user object, not a manually constructed one.
* Pass either `user` or `group` to the message components, never both.
* The `RECIPIENT_UID` should be a user that exists in your CometChat app. Use one of the pre-created test UIDs: `cometchat-uid-1` through `cometchat-uid-5`.

***

## Switching to Group Chat

To load a group chat instead of one-to-one, fetch a `Group` object and pass it to the message components:

```tsx title="src/App.tsx" theme={null}
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";
import "./App.css";

const GROUP_ID = "cometchat-guid-1"; // Replace with your Group ID

function App() {
  const [chatGroup, setChatGroup] = useState<CometChat.Group | undefined>(undefined);

  useEffect(() => {
    CometChat.getGroup(GROUP_ID).then(
      (group) => setChatGroup(group),
      (error) => console.error("Group fetch failed:", error)
    );
  }, []);

  if (!chatGroup) return <div>Loading chat...</div>;

  return (
    <CometChatProvider>
      <div className="chat-window">
        <CometChatMessageHeader group={chatGroup} />
        <CometChatMessageList group={chatGroup} />
        <CometChatMessageComposer group={chatGroup} />
      </div>
    </CometChatProvider>
  );
}

export default App;
```

The only difference: use `CometChat.getGroup(GUID)` instead of `CometChat.getUser(UID)`, and pass `group` instead of `user`.

***

## Run

```bash theme={null}
npm run dev
```

Open `http://localhost:5173`. You should see the chat window load with the conversation for the UID or GUID you set.

***

## Next Steps

<CardGroup>
  <Card title="Conversation List + Messages" icon="comments" href="/ui-kit/react/react-conversation">
    Two-panel layout with a sidebar
  </Card>

  <Card title="Tab-Based Chat" icon="table-columns" href="/ui-kit/react/react-tab-based-chat">
    Tabbed navigation with Chats, Calls, Users
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>
</CardGroup>


# Conversation List + Message View
Source: https://www.cometchat.com/docs/ui-kit/react/react-router-conversation

Build a two-panel conversation list + message view layout in React Router with CometChat UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                  |
  | ------------ | ------------------------------------------------------------------------------------------------------ |
  | Package      | `@cometchat/chat-uikit-react`                                                                          |
  | Framework    | React Router                                                                                           |
  | Components   | `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Two-panel — conversation list (left) + message view (right)                                            |
  | Prerequisite | Complete [React Router Integration](/docs/ui-kit/react/integration-react-router) first                      |
  | SSR          | N/A — client-side SPA by default                                                                       |
  | Pattern      | WhatsApp Web, Slack, Microsoft Teams                                                                   |
</Accordion>

This guide builds a two-panel chat layout — conversation list on the left, messages on the right. Users click a conversation to open it.

This assumes you've already completed [React Router Integration](/docs/ui-kit/react/integration-react-router) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three sections working together:

1. **Sidebar (conversation list)** — shows all active conversations (users and groups)
2. **Message view** — displays chat messages for the selected conversation in real time
3. **Message composer** — text input with support for media, emojis, and reactions

***

## Full Code

Create a chat route component. Init and login must complete before the provider mounts — see the [React Router Integration](/docs/ui-kit/react/integration-react-router) guide for the `src/main.tsx` setup.

```tsx title="src/pages/ChatPage.tsx" theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";
import "./ChatPage.css";

export default function ChatPage() {
  const [selectedUser, setSelectedUser] = useState<CometChat.User | undefined>(undefined);
  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group | undefined>(undefined);

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setSelectedUser(entity as CometChat.User);
      setSelectedGroup(undefined);
    } else {
      setSelectedGroup(entity as CometChat.Group);
      setSelectedUser(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div className="conversations-with-messages">
        <div className="conversations-wrapper">
          <CometChatConversations onItemClick={handleConversationClick} />
        </div>

        {selectedUser || selectedGroup ? (
          <div className="messages-wrapper">
            <CometChatMessageHeader user={selectedUser} group={selectedGroup} />
            <CometChatMessageList user={selectedUser} group={selectedGroup} />
            <CometChatMessageComposer user={selectedUser} group={selectedGroup} />
          </div>
        ) : (
          <div className="empty-conversation">
            Select a conversation to start chatting
          </div>
        )}
      </div>
    </CometChatProvider>
  );
}
```

```css title="src/pages/ChatPage.css" theme={null}
.conversations-with-messages {
  display: flex;
  height: 100vh;
  width: 100%;
}

.conversations-wrapper {
  width: 360px;
  height: 100%;
  border-right: 1px solid #eee;
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

.messages-wrapper {
  flex: 1;
  height: 100%;
  display: flex;
  flex-direction: column;
}

.empty-conversation {
  flex: 1;
  display: flex;
  justify-content: center;
  align-items: center;
  background: var(--cometchat-background-color-03, #f5f5f5);
  color: var(--cometchat-text-color-secondary, #727272);
  font: var(--cometchat-font-body-regular, 400 14px Roboto);
}
```

Register the route in your `App.tsx`:

```tsx title="src/App.tsx" theme={null}
import { Routes, Route, Navigate } from "react-router-dom";
import ChatPage from "./pages/ChatPage";

function App() {
  // ... login logic from integration guide ...

  return (
    <Routes>
      <Route path="/chat" element={<ChatPage />} />
      <Route path="*" element={<Navigate to="/chat" replace />} />
    </Routes>
  );
}

export default App;
```

***

## How It Works

1. **CometChatProvider** wraps the entire tree — it supplies theme, locale, and event context to all CometChat components.
2. **CometChatConversations** renders the sidebar list. When a user clicks a conversation, `onItemClick` fires with the `Conversation` object.
3. **handleConversationClick** extracts the `User` or `Group` from the conversation and stores it in state.
4. **Message components** (`MessageHeader`, `MessageList`, `MessageComposer`) receive either `user` or `group` as a prop — never both at the same time.
5. When the user switches conversations, state updates and the message panel re-renders with the new chat.
6. **React Router** handles navigation — the chat page is a route component at `/chat`.

***

## Run

```bash theme={null}
npm run dev
```

Open `http://localhost:5173/chat`. You should see the conversation list on the left. Click any conversation to load messages on the right.

***

## Next Steps

<CardGroup>
  <Card title="One-to-One / Group Chat" icon="message" href="/ui-kit/react/react-router-one-to-one-chat">
    Single chat window without a sidebar
  </Card>

  <Card title="Tab-Based Chat" icon="table-columns" href="/ui-kit/react/react-router-tab-based-chat">
    Tabbed navigation with Chats, Calls, Users
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and styles
  </Card>
</CardGroup>


# One-to-One / Group Chat
Source: https://www.cometchat.com/docs/ui-kit/react/react-router-one-to-one-chat

Build a single chat window for one-to-one or group messaging in React Router with CometChat UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                             |
  | ------------ | --------------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react`                                                     |
  | Framework    | React Router                                                                      |
  | Components   | `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`      |
  | Layout       | Single chat window — no sidebar, no conversation list                             |
  | Prerequisite | Complete [React Router Integration](/docs/ui-kit/react/integration-react-router) first |
  | SSR          | N/A — client-side SPA by default                                                  |
  | Pattern      | Support chat, embedded widgets, focused messaging                                 |
</Accordion>

This guide builds a single chat window — no sidebar, no conversation list. Users go directly into a one-to-one or group chat. Good for support chat, embedded widgets, or any focused messaging experience.

This assumes you've already completed [React Router Integration](/docs/ui-kit/react/integration-react-router) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three components stacked vertically:

1. **Chat header** — displays recipient name, avatar, online status, and optional call buttons
2. **Message list** — real-time chat history with scrolling
3. **Message composer** — text input with media, emojis, and reactions

***

## Full Code

Create a route component for the chat page. Init and login are completed in `src/main.tsx` (see [React Router Integration](/docs/ui-kit/react/integration-react-router)).

```tsx title="src/pages/DirectChatPage.tsx" theme={null}
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";
import "./DirectChatPage.css";

const RECIPIENT_UID = "cometchat-uid-2"; // Replace with the UID you want to chat with

export default function DirectChatPage() {
  const [chatUser, setChatUser] = useState<CometChat.User | undefined>(undefined);

  useEffect(() => {
    CometChat.getUser(RECIPIENT_UID).then(
      (user) => setChatUser(user),
      (error) => console.error("User fetch failed:", error)
    );
  }, []);

  if (!chatUser) return <div>Loading chat...</div>;

  return (
    <CometChatProvider>
      <div className="chat-window">
        <CometChatMessageHeader user={chatUser} />
        <CometChatMessageList user={chatUser} />
        <CometChatMessageComposer user={chatUser} />
      </div>
    </CometChatProvider>
  );
}
```

```css title="src/pages/DirectChatPage.css" theme={null}
.chat-window {
  display: flex;
  flex-direction: column;
  height: 100vh;
  width: 100%;
}
```

Register the route in your `App.tsx`:

```tsx title="src/App.tsx" theme={null}
import { Routes, Route, Navigate } from "react-router-dom";
import DirectChatPage from "./pages/DirectChatPage";

function App() {
  // ... login logic from integration guide ...

  return (
    <Routes>
      <Route path="/chat" element={<DirectChatPage />} />
      <Route path="*" element={<Navigate to="/chat" replace />} />
    </Routes>
  );
}

export default App;
```

Key points:

* `CometChat.getUser(UID)` fetches the full user object from the SDK — you need a real user object, not a manually constructed one.
* Pass either `user` or `group` to the message components, never both.
* The `RECIPIENT_UID` should be a user that exists in your CometChat app. Use one of the pre-created test UIDs: `cometchat-uid-1` through `cometchat-uid-5`.
* The chat page is a route component — React Router handles navigation.

***

## Switching to Group Chat

To load a group chat instead of one-to-one, fetch a `Group` object and pass it to the message components:

```tsx title="src/pages/DirectChatPage.tsx" theme={null}
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";
import "./DirectChatPage.css";

const GROUP_ID = "cometchat-guid-1"; // Replace with your Group ID

export default function DirectChatPage() {
  const [chatGroup, setChatGroup] = useState<CometChat.Group | undefined>(undefined);

  useEffect(() => {
    CometChat.getGroup(GROUP_ID).then(
      (group) => setChatGroup(group),
      (error) => console.error("Group fetch failed:", error)
    );
  }, []);

  if (!chatGroup) return <div>Loading chat...</div>;

  return (
    <CometChatProvider>
      <div className="chat-window">
        <CometChatMessageHeader group={chatGroup} />
        <CometChatMessageList group={chatGroup} />
        <CometChatMessageComposer group={chatGroup} />
      </div>
    </CometChatProvider>
  );
}
```

The only difference: use `CometChat.getGroup(GUID)` instead of `CometChat.getUser(UID)`, and pass `group` instead of `user`.

***

## Run

```bash theme={null}
npm run dev
```

Open `http://localhost:5173/chat`. You should see the chat window load with the conversation for the UID or GUID you set.

***

## Next Steps

<CardGroup>
  <Card title="Conversation List + Messages" icon="comments" href="/ui-kit/react/react-router-conversation">
    Two-panel layout with a sidebar
  </Card>

  <Card title="Tab-Based Chat" icon="table-columns" href="/ui-kit/react/react-router-tab-based-chat">
    Tabbed navigation with Chats, Calls, Users
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>
</CardGroup>


# Tab-Based Chat
Source: https://www.cometchat.com/docs/ui-kit/react/react-router-tab-based-chat

Build a tab-based chat interface with Chat, Call Logs, and Users tabs in React Router.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                                                         |
  | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react`                                                                                                                 |
  | Framework    | React Router                                                                                                                                  |
  | Components   | `CometChatConversations`, `CometChatCallLogs`, `CometChatUsers`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Tabbed sidebar (Chat, Calls, Users) + message view                                                                                            |
  | Prerequisite | Complete [React Router Integration](/docs/ui-kit/react/integration-react-router) first                                                             |
  | SSR          | N/A — client-side SPA by default                                                                                                              |
  | Pattern      | Full-featured messaging app with multiple sections                                                                                            |
</Accordion>

This guide builds a tabbed messaging UI — Chat, Calls, and Users tabs in the sidebar, with a message view on the right. Good for full-featured apps that need more than just conversations.

This assumes you've already completed [React Router Integration](/docs/ui-kit/react/integration-react-router) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three sections working together:

1. **Tab bar** — switches between Chat, Calls, and Users
2. **Sidebar** — renders the list for the active tab
3. **Message view** — header + messages + composer for the selected item

***

## Full Code

Create a route component for the tabbed chat page. Init and login are completed in `src/main.tsx` (see [React Router Integration](/docs/ui-kit/react/integration-react-router)).

```tsx title="src/pages/TabbedChatPage.tsx" theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatConversations,
  CometChatUsers,
  CometChatCallLogs,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";
import "./TabbedChatPage.css";

type Tab = "chat" | "calls" | "users";

export default function TabbedChatPage() {
  const [activeTab, setActiveTab] = useState<Tab>("chat");
  const [selectedUser, setSelectedUser] = useState<CometChat.User | undefined>(undefined);
  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group | undefined>(undefined);

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setSelectedUser(entity as CometChat.User);
      setSelectedGroup(undefined);
    } else {
      setSelectedGroup(entity as CometChat.Group);
      setSelectedUser(undefined);
    }
  };

  const handleUserClick = (user: CometChat.User) => {
    setSelectedUser(user);
    setSelectedGroup(undefined);
  };

  const handleCallClick = (call: any) => {
    const initiator = call.getInitiator();
    const receiver = call.getReceiver();

    // Determine the other party in the call
    if (receiver instanceof CometChat.User) {
      setSelectedUser(receiver);
      setSelectedGroup(undefined);
    } else if (receiver instanceof CometChat.Group) {
      setSelectedUser(undefined);
      setSelectedGroup(receiver);
    } else if (initiator instanceof CometChat.User) {
      setSelectedUser(initiator);
      setSelectedGroup(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div className="tabbed-chat">
        <div className="sidebar">
          <div className="tab-bar">
            <button
              className={`tab-button ${activeTab === "chat" ? "tab-button--active" : ""}`}
              onClick={() => setActiveTab("chat")}
            >
              Chats
            </button>
            <button
              className={`tab-button ${activeTab === "calls" ? "tab-button--active" : ""}`}
              onClick={() => setActiveTab("calls")}
            >
              Calls
            </button>
            <button
              className={`tab-button ${activeTab === "users" ? "tab-button--active" : ""}`}
              onClick={() => setActiveTab("users")}
            >
              Users
            </button>
          </div>

          <div className="sidebar-list">
            {activeTab === "chat" && (
              <CometChatConversations onItemClick={handleConversationClick} />
            )}
            {activeTab === "calls" && (
              <CometChatCallLogs onItemClick={handleCallClick} />
            )}
            {activeTab === "users" && (
              <CometChatUsers onItemClick={handleUserClick} />
            )}
          </div>
        </div>

        {selectedUser || selectedGroup ? (
          <div className="messages-wrapper">
            <CometChatMessageHeader user={selectedUser} group={selectedGroup} />
            <CometChatMessageList user={selectedUser} group={selectedGroup} />
            <CometChatMessageComposer user={selectedUser} group={selectedGroup} />
          </div>
        ) : (
          <div className="empty-conversation">
            Select a conversation to start chatting
          </div>
        )}
      </div>
    </CometChatProvider>
  );
}
```

```css title="src/pages/TabbedChatPage.css" theme={null}
.tabbed-chat {
  display: flex;
  height: 100vh;
  width: 100%;
}

.sidebar {
  width: 360px;
  height: 100%;
  display: flex;
  flex-direction: column;
  border-right: 1px solid #eee;
}

.tab-bar {
  display: flex;
  border-bottom: 1px solid #eee;
  background: var(--cometchat-background-color-01, #fff);
}

.tab-button {
  flex: 1;
  padding: 12px 0;
  border: none;
  background: none;
  cursor: pointer;
  font: var(--cometchat-font-body-medium, 500 14px Roboto);
  color: var(--cometchat-text-color-secondary, #727272);
  border-bottom: 2px solid transparent;
  transition: color 0.2s, border-color 0.2s;
}

.tab-button:hover {
  color: var(--cometchat-text-color-primary, #141414);
}

.tab-button--active {
  color: var(--cometchat-text-color-highlight, #6851d6);
  border-bottom-color: var(--cometchat-primary-color, #6851d6);
}

.sidebar-list {
  flex: 1;
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

.messages-wrapper {
  flex: 1;
  height: 100%;
  display: flex;
  flex-direction: column;
}

.empty-conversation {
  flex: 1;
  display: flex;
  justify-content: center;
  align-items: center;
  background: var(--cometchat-background-color-03, #f5f5f5);
  color: var(--cometchat-text-color-secondary, #727272);
  font: var(--cometchat-font-body-regular, 400 14px Roboto);
}
```

Register the route in your `App.tsx`:

```tsx title="src/App.tsx" theme={null}
import { Routes, Route, Navigate } from "react-router-dom";
import TabbedChatPage from "./pages/TabbedChatPage";

function App() {
  // ... login logic from integration guide ...

  return (
    <Routes>
      <Route path="/chat" element={<TabbedChatPage />} />
      <Route path="*" element={<Navigate to="/chat" replace />} />
    </Routes>
  );
}

export default App;
```

***

## How It Works

1. **Tab state** — `activeTab` controls which list component renders in the sidebar.
2. **Conditional rendering** — only the active tab's component mounts. Switching tabs unmounts the previous list and mounts the new one.
3. **Unified selection** — all three tabs feed into the same `selectedUser` / `selectedGroup` state. Clicking any item (conversation, call log, or user) updates the message panel.
4. **Call log handling** — when a call log is clicked, the receiver (user or group) is extracted and passed to the message components.
5. **React Router** handles navigation — the tabbed chat page is a route component at `/chat`.

***

## Adding More Tabs

To add a Groups tab, import `CometChatGroups` and add another tab button + conditional render:

```tsx theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react";

// Add to Tab type:
type Tab = "chat" | "calls" | "users" | "groups";

// Add button in tab-bar:
<button
  className={`tab-button ${activeTab === "groups" ? "tab-button--active" : ""}`}
  onClick={() => setActiveTab("groups")}
>
  Groups
</button>

// Add in sidebar-list:
{activeTab === "groups" && (
  <CometChatGroups
    onItemClick={(group: CometChat.Group) => {
      setSelectedGroup(group);
      setSelectedUser(undefined);
    }}
  />
)}
```

You can follow the same pattern for any additional tabs (Settings, Contacts, etc.).

***

## Run

```bash theme={null}
npm run dev
```

Open `http://localhost:5173/chat`. You should see the tab bar at the top of the sidebar. Switch between Chats, Calls, and Users — clicking any item loads the message view on the right.

***

## Next Steps

<CardGroup>
  <Card title="Conversation List + Messages" icon="comments" href="/ui-kit/react/react-router-conversation">
    Two-panel layout without tabs
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and styles
  </Card>
</CardGroup>


# Tab-Based Chat
Source: https://www.cometchat.com/docs/ui-kit/react/react-tab-based-chat

Build a tab-based chat interface with Chat, Call Logs, and Users tabs in React.js.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                                                         |
  | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react`                                                                                                                 |
  | Framework    | React.js                                                                                                                                      |
  | Components   | `CometChatConversations`, `CometChatCallLogs`, `CometChatUsers`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Tabbed sidebar (Chat, Calls, Users) + message view                                                                                            |
  | Prerequisite | Complete [React.js Integration](/docs/ui-kit/react/integration-react) first                                                                        |
  | Pattern      | Full-featured messaging app with multiple sections                                                                                            |
</Accordion>

This guide builds a tabbed messaging UI — Chat, Calls, and Users tabs in the sidebar, with a message view on the right. Good for full-featured apps that need more than just conversations.

This assumes you've already completed [React.js Integration](/docs/ui-kit/react/integration-react) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three sections working together:

1. **Tab bar** — switches between Chat, Calls, and Users
2. **Sidebar** — renders the list for the active tab
3. **Message view** — header + messages + composer for the selected item

***

## Full Code

Replace your `src/App.tsx` with the following. Init and login must complete before the provider mounts — see the [React.js Integration](/docs/ui-kit/react/integration-react) guide for the `src/main.tsx` setup.

```tsx title="src/App.tsx" theme={null}
import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatConversations,
  CometChatUsers,
  CometChatCallLogs,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";
import "./App.css";

type Tab = "chat" | "calls" | "users";

function App() {
  const [activeTab, setActiveTab] = useState<Tab>("chat");
  const [selectedUser, setSelectedUser] = useState<CometChat.User | undefined>(undefined);
  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group | undefined>(undefined);

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setSelectedUser(entity as CometChat.User);
      setSelectedGroup(undefined);
    } else {
      setSelectedGroup(entity as CometChat.Group);
      setSelectedUser(undefined);
    }
  };

  const handleUserClick = (user: CometChat.User) => {
    setSelectedUser(user);
    setSelectedGroup(undefined);
  };

  const handleCallClick = (call: any) => {
    const initiator = call.getInitiator();
    const receiver = call.getReceiver();

    // Determine the other party in the call
    if (receiver instanceof CometChat.User) {
      setSelectedUser(receiver);
      setSelectedGroup(undefined);
    } else if (receiver instanceof CometChat.Group) {
      setSelectedUser(undefined);
      setSelectedGroup(receiver);
    } else if (initiator instanceof CometChat.User) {
      setSelectedUser(initiator);
      setSelectedGroup(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div className="tabbed-chat">
        <div className="sidebar">
          <div className="tab-bar">
            <button
              className={`tab-button ${activeTab === "chat" ? "tab-button--active" : ""}`}
              onClick={() => setActiveTab("chat")}
            >
              Chats
            </button>
            <button
              className={`tab-button ${activeTab === "calls" ? "tab-button--active" : ""}`}
              onClick={() => setActiveTab("calls")}
            >
              Calls
            </button>
            <button
              className={`tab-button ${activeTab === "users" ? "tab-button--active" : ""}`}
              onClick={() => setActiveTab("users")}
            >
              Users
            </button>
          </div>

          <div className="sidebar-list">
            {activeTab === "chat" && (
              <CometChatConversations onItemClick={handleConversationClick} />
            )}
            {activeTab === "calls" && (
              <CometChatCallLogs onItemClick={handleCallClick} />
            )}
            {activeTab === "users" && (
              <CometChatUsers onItemClick={handleUserClick} />
            )}
          </div>
        </div>

        {selectedUser || selectedGroup ? (
          <div className="messages-wrapper">
            <CometChatMessageHeader user={selectedUser} group={selectedGroup} />
            <CometChatMessageList user={selectedUser} group={selectedGroup} />
            <CometChatMessageComposer user={selectedUser} group={selectedGroup} />
          </div>
        ) : (
          <div className="empty-conversation">
            Select a conversation to start chatting
          </div>
        )}
      </div>
    </CometChatProvider>
  );
}

export default App;
```

```css title="src/App.css" theme={null}
.tabbed-chat {
  display: flex;
  height: 100vh;
  width: 100%;
}

.sidebar {
  width: 360px;
  height: 100%;
  display: flex;
  flex-direction: column;
  border-right: 1px solid #eee;
}

.tab-bar {
  display: flex;
  border-bottom: 1px solid #eee;
  background: var(--cometchat-background-color-01, #fff);
}

.tab-button {
  flex: 1;
  padding: 12px 0;
  border: none;
  background: none;
  cursor: pointer;
  font: var(--cometchat-font-body-medium, 500 14px Roboto);
  color: var(--cometchat-text-color-secondary, #727272);
  border-bottom: 2px solid transparent;
  transition: color 0.2s, border-color 0.2s;
}

.tab-button:hover {
  color: var(--cometchat-text-color-primary, #141414);
}

.tab-button--active {
  color: var(--cometchat-text-color-highlight, #6851d6);
  border-bottom-color: var(--cometchat-primary-color, #6851d6);
}

.sidebar-list {
  flex: 1;
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

.messages-wrapper {
  flex: 1;
  height: 100%;
  display: flex;
  flex-direction: column;
}

.empty-conversation {
  flex: 1;
  display: flex;
  justify-content: center;
  align-items: center;
  background: var(--cometchat-background-color-03, #f5f5f5);
  color: var(--cometchat-text-color-secondary, #727272);
  font: var(--cometchat-font-body-regular, 400 14px Roboto);
}
```

***

## How It Works

1. **Tab state** — `activeTab` controls which list component renders in the sidebar.
2. **Conditional rendering** — only the active tab's component mounts. Switching tabs unmounts the previous list and mounts the new one.
3. **Unified selection** — all three tabs feed into the same `selectedUser` / `selectedGroup` state. Clicking any item (conversation, call log, or user) updates the message panel.
4. **Call log handling** — when a call log is clicked, the receiver (user or group) is extracted and passed to the message components.

***

## Adding More Tabs

To add a Groups tab, import `CometChatGroups` and add another tab button + conditional render:

```tsx theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react";

// Add to Tab type:
type Tab = "chat" | "calls" | "users" | "groups";

// Add button in tab-bar:
<button
  className={`tab-button ${activeTab === "groups" ? "tab-button--active" : ""}`}
  onClick={() => setActiveTab("groups")}
>
  Groups
</button>

// Add in sidebar-list:
{activeTab === "groups" && (
  <CometChatGroups
    onItemClick={(group: CometChat.Group) => {
      setSelectedGroup(group);
      setSelectedUser(undefined);
    }}
  />
)}
```

You can follow the same pattern for any additional tabs (Settings, Contacts, etc.).

***

## Run

```bash theme={null}
npm run dev
```

Open `http://localhost:5173`. You should see the tab bar at the top of the sidebar. Switch between Chats, Calls, and Users — clicking any item loads the message view on the right.

***

## Next Steps

<CardGroup>
  <Card title="Conversation List + Messages" icon="comments" href="/ui-kit/react/react-conversation">
    Two-panel layout without tabs
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and styles
  </Card>
</CardGroup>


# Sound Manager
Source: https://www.cometchat.com/docs/ui-kit/react/sound-manager

Play notification sounds for incoming/outgoing messages and calls with custom sound URL support.

<Accordion title="AI Integration Quick Reference">
  | Field              | Value                                                                                                                                       |
  | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
  | Class              | `CometChatSoundManager`                                                                                                                     |
  | Package            | `@cometchat/chat-uikit-react`                                                                                                               |
  | Sound types        | `incomingMessage`, `outgoingMessage`, `incomingMessageFromOther`, `incomingCall`, `outgoingCall`                                            |
  | Custom sounds      | Pass URL as second argument: `CometChatSoundManager.play('incomingMessage', '/my-sound.mp3')`                                               |
  | Global config      | `disableSoundForMessages`, `customSoundForMessages`, `disableSoundForCalls`, `customSoundForCalls` via `config` prop on `CometChatProvider` |
  | Component override | Same props on individual components (props take precedence over global config)                                                              |
</Accordion>

## Overview

`CometChatSoundManager` handles audio notifications for chat events. It plays sounds when messages are sent/received and when calls are initiated/received. Components use it internally — you don't need to call it manually unless you want custom behavior.

***

## Sound Types

| Type                       | When it plays                                | Loops |
| -------------------------- | -------------------------------------------- | ----- |
| `outgoingMessage`          | User sends a message                         | No    |
| `incomingMessage`          | Message received in the active conversation  | No    |
| `incomingMessageFromOther` | Message received in a different conversation | No    |
| `incomingCall`             | Incoming call notification                   | Yes   |
| `outgoingCall`             | Outgoing call ringing                        | Yes   |

***

## Disabling & Customizing Sounds

Sound behavior can be configured at two levels:

1. **Global config** — Set on `CometChatProvider` via the `config` prop. Applies to all components.
2. **Component props** — Set directly on individual components. Takes precedence over global config.

### Global Config

Use the `config` prop on `CometChatProvider` to control sound behavior across all components:

```tsx theme={null}
<CometChatProvider
  config={{
    disableSoundForMessages: true,
    customSoundForMessages: "/sounds/custom-message.mp3",
    disableSoundForCalls: true,
    customSoundForCalls: "/sounds/custom-ringtone.mp3",
  }}
>
  <MyChatApp />
</CometChatProvider>
```

| Property                  | Type      | Description                                                                 |
| ------------------------- | --------- | --------------------------------------------------------------------------- |
| `disableSoundForMessages` | `boolean` | Disable sound for incoming messages across all components. Default: `false` |
| `customSoundForMessages`  | `string`  | Custom sound URL for incoming message notifications                         |
| `disableSoundForCalls`    | `boolean` | Disable sound for incoming/outgoing calls. Default: `false`                 |
| `customSoundForCalls`     | `string`  | Custom sound URL for calls                                                  |

### Component-Level Props (Override)

Individual components accept the same props. When set, they override the global config for that component only.

```tsx theme={null}
{/* Override global config for this specific component */}
<CometChatConversations
  disableSoundForMessages={false}
  customSoundForMessages="/sounds/conversation-alert.mp3"
/>

<CometChatIncomingCall
  disableSoundForCalls={false}
  customSoundForCalls="/sounds/incoming-ring.mp3"
/>
```

**Components that accept sound props:**

| Component                  | Props                                               |
| -------------------------- | --------------------------------------------------- |
| `CometChatConversations`   | `disableSoundForMessages`, `customSoundForMessages` |
| `CometChatMessageList`     | `disableSoundForMessages`, `customSoundForMessages` |
| `CometChatMessageComposer` | `disableSoundForMessage`, `customSoundForMessage`   |
| `CometChatIncomingCall`    | `disableSoundForCalls`, `customSoundForCalls`       |
| `CometChatOutgoingCall`    | `disableSoundForCalls`, `customSoundForCalls`       |

<Note>
  Component-level props always take precedence over the global config. If a prop is not set on a component, it falls back to the global config value.
</Note>

***

## Custom Sound URLs

Replace default sounds with your own audio files:

```tsx theme={null}
import { CometChatSoundManager } from "@cometchat/chat-uikit-react";

// Play a custom notification sound
CometChatSoundManager.play("incomingMessage", "/sounds/notification.mp3");

// Or use convenience methods
CometChatSoundManager.onIncomingMessage("/sounds/notification.mp3");
CometChatSoundManager.onOutgoingMessage("/sounds/sent.mp3");
```

***

## API Reference

### Static Methods

| Method                   | Signature                                        | Description                                   |
| ------------------------ | ------------------------------------------------ | --------------------------------------------- |
| `play`                   | `(sound: SoundType, customUrl?: string) => void` | Play a sound (with optional custom URL)       |
| `pause`                  | `() => void`                                     | Stop the currently playing sound              |
| `onOutgoingMessage`      | `(customUrl?: string) => void`                   | Play outgoing message sound                   |
| `onIncomingMessage`      | `(customUrl?: string) => void`                   | Play incoming message sound                   |
| `onIncomingOtherMessage` | `(customUrl?: string) => void`                   | Play incoming message from other conversation |
| `onIncomingCall`         | `(customUrl?: string) => void`                   | Play incoming call sound (loops)              |
| `onOutgoingCall`         | `(customUrl?: string) => void`                   | Play outgoing call sound (loops)              |

***

## Browser Autoplay Policy

Browsers require user interaction before playing audio. `CometChatSoundManager` checks `navigator.userActivation` before attempting playback. If the user hasn't interacted with the page yet, sounds are silently skipped.

***

## SSR Safety

All `Audio` API usage is guarded behind `typeof Audio !== 'undefined'` checks. The sound manager is safe to import in server-side rendering environments — it simply no-ops when `Audio` is unavailable.


# Color Resources
Source: https://www.cometchat.com/docs/ui-kit/react/theme/color-resources

Complete reference of all color CSS variables with light and dark theme values.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                             |
  | -------------- | ----------------------------------------------------------------- |
  | Override scope | `.cometchat` (global) or `.cometchat-{component}` (per-component) |
  | Key token      | `--cometchat-primary-color` — brand/accent color                  |
  | Light theme    | Defined in `:root, [data-theme='light']`                          |
  | Dark theme     | Defined in `[data-theme='dark']`                                  |
</Accordion>

## Overview

All colors in the UI Kit are defined as CSS custom properties. Override them to match your brand. Variables cascade — set on `.cometchat` to affect everything, or on a specific component class to scope the change.

```css title="src/cometchat-overrides.css" theme={null}
.cometchat {
  --cometchat-primary-color: #e91e63;
}
```

***

## Primary Colors

The primary color and its extended scale (50 = lightest, 900 = darkest).

| Token                                    | Light     | Dark      |
| ---------------------------------------- | --------- | --------- |
| `--cometchat-primary-color`              | `#6852d6` | `#6852d6` |
| `--cometchat-extended-primary-color-50`  | `#f5f2ff` | `#15102b` |
| `--cometchat-extended-primary-color-100` | `#ebe5ff` | `#1d173c` |
| `--cometchat-extended-primary-color-200` | `#d6ccff` | `#251e4d` |
| `--cometchat-extended-primary-color-300` | `#c2b2ff` | `#2e245e` |
| `--cometchat-extended-primary-color-400` | `#ad99ff` | `#362b6f` |
| `--cometchat-extended-primary-color-500` | `#997fff` | `#3e3180` |
| `--cometchat-extended-primary-color-600` | `#8566ff` | `#473892` |
| `--cometchat-extended-primary-color-700` | `#704cff` | `#4f3ea3` |
| `--cometchat-extended-primary-color-800` | `#5c33ff` | `#5745b4` |
| `--cometchat-extended-primary-color-900` | `#5d49be` | `#7460d9` |

***

## Neutral Colors

Gray scale used for backgrounds, borders, and text.

| Token                           | Light     | Dark      |
| ------------------------------- | --------- | --------- |
| `--cometchat-neutral-color-50`  | `#ffffff` | `#141414` |
| `--cometchat-neutral-color-100` | `#fafafa` | `#1a1a1a` |
| `--cometchat-neutral-color-200` | `#f5f5f5` | `#272727` |
| `--cometchat-neutral-color-300` | `#e8e8e8` | `#383838` |
| `--cometchat-neutral-color-400` | `#c4c4c4` | `#4c4c4c` |
| `--cometchat-neutral-color-500` | `#a1a1a1` | `#858585` |
| `--cometchat-neutral-color-600` | `#727272` | `#989898` |
| `--cometchat-neutral-color-700` | `#565656` | `#a8a8a8` |
| `--cometchat-neutral-color-800` | `#333333` | `#c8c8c8` |
| `--cometchat-neutral-color-900` | `#141414` | `#ffffff` |

***

## Alert Colors

| Token                            | Light     | Dark      | Purpose            |
| -------------------------------- | --------- | --------- | ------------------ |
| `--cometchat-info-color`         | `#0f73d6` | `#0d66bf` | Informational      |
| `--cometchat-warning-color`      | `#ffab00` | `#d08d04` | Warning / mentions |
| `--cometchat-success-color`      | `#09b26b` | `#0b9f5d` | Success            |
| `--cometchat-error-color`        | `#f44649` | `#c73c3e` | Error / danger     |
| `--cometchat-message-seen-color` | `#56e8a7` | `#56e8a7` | Read receipts      |

***

## Semantic Colors

These reference the neutral/primary scales and change automatically with the theme.

### Backgrounds

| Token                             | Maps to                        |
| --------------------------------- | ------------------------------ |
| `--cometchat-background-color-01` | `neutral-color-50` (base)      |
| `--cometchat-background-color-02` | `neutral-color-100` (surface)  |
| `--cometchat-background-color-03` | `neutral-color-200` (elevated) |
| `--cometchat-background-color-04` | `neutral-color-300` (highest)  |

### Borders

| Token                                | Maps to             |
| ------------------------------------ | ------------------- |
| `--cometchat-border-color-light`     | `neutral-color-200` |
| `--cometchat-border-color-default`   | `neutral-color-300` |
| `--cometchat-border-color-dark`      | `neutral-color-400` |
| `--cometchat-border-color-highlight` | `primary-color`     |

### Text

| Token                              | Maps to             |
| ---------------------------------- | ------------------- |
| `--cometchat-text-color-primary`   | `neutral-color-900` |
| `--cometchat-text-color-secondary` | `neutral-color-600` |
| `--cometchat-text-color-tertiary`  | `neutral-color-500` |
| `--cometchat-text-color-disabled`  | `neutral-color-400` |
| `--cometchat-text-color-white`     | `neutral-color-50`  |
| `--cometchat-text-color-highlight` | `primary-color`     |

### Icons

| Token                              | Maps to             |
| ---------------------------------- | ------------------- |
| `--cometchat-icon-color-primary`   | `neutral-color-900` |
| `--cometchat-icon-color-secondary` | `neutral-color-500` |
| `--cometchat-icon-color-tertiary`  | `neutral-color-400` |
| `--cometchat-icon-color-white`     | `neutral-color-50`  |
| `--cometchat-icon-color-highlight` | `primary-color`     |

***

## Buttons

| Token                                     | Light               | Dark                |
| ----------------------------------------- | ------------------- | ------------------- |
| `--cometchat-primary-button-background`   | `primary-color`     | `primary-color`     |
| `--cometchat-primary-button-text`         | `static-white`      | `static-white`      |
| `--cometchat-primary-button-icon`         | `static-white`      | `static-white`      |
| `--cometchat-secondary-button-background` | `neutral-color-900` | `neutral-color-900` |
| `--cometchat-secondary-button-text`       | `neutral-color-900` | `neutral-color-900` |
| `--cometchat-fab-button-background`       | `primary-color`     | `primary-color`     |
| `--cometchat-link-button`                 | `info-color`        | `info-color`        |

***

## Example: Brand Color Override

```css title="src/cometchat-overrides.css" theme={null}
/* Change the primary brand color globally — target .cometchat (the root wrapper) */
.cometchat {
  --cometchat-primary-color: #e91e63;
  --cometchat-extended-primary-color-500: #e91e63;
  --cometchat-extended-primary-color-600: #d81b60;
  --cometchat-extended-primary-color-700: #c2185b;
}
```

## Example: Dark Mode Override

```css theme={null}
[data-theme="dark"] {
  --cometchat-primary-color: #bb86fc;
  --cometchat-background-color-01: #121212;
  --cometchat-background-color-02: #1e1e1e;
}
```

<Note>
  Always target `.cometchat` or `[data-theme="..."]` for global overrides. For per-component overrides, use the component's BEM class name directly (e.g., `.cometchat-conversations`). See [Theming](/docs/ui-kit/react/theming#component-css-classes) for details.
</Note>


# Message Bubble Styling
Source: https://www.cometchat.com/docs/ui-kit/react/theme/message-bubble-styling

Customize incoming and outgoing message bubble colors, backgrounds, and styles using CSS variables and class selectors in the CometChat React UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field         | Value                                                                                                                   |
  | ------------- | ----------------------------------------------------------------------------------------------------------------------- |
  | Goal          | Customize message bubble appearance (colors, backgrounds) per direction and message type                                |
  | Where         | `App.css` (global) — imported in app entry via `import "./App.css";`                                                    |
  | Base selector | `.cometchat .cometchat-message-bubble-(incoming\|outgoing) .cometchat-message-bubble__body`                             |
  | Type modifier | Append `.cometchat-message-bubble__<TYPE>-message` to target specific types (`text`, `image`, `video`, `audio`, `file`) |
  | Key tokens    | `--cometchat-primary-color` (outgoing bg), `--cometchat-neutral-color-300` (incoming bg)                                |
  | Constraints   | Global CSS only (no CSS Modules), no `!important`, type selectors override generic bubble selectors                     |
</Accordion>

Message bubble styling uses distinct CSS classes for incoming and outgoing messages. Each message type (text, image, video, audio, file, etc.) has predefined classes for default styling, customizable via CSS variable overrides.

<Warning>
  **Prerequisites before applying any CSS customization:**

  1. All selectors assume the UI Kit renders under a `.cometchat` root wrapper
  2. Import your CSS file at the app entry: `import "./App.css";` in `App.tsx`
  3. Use **global CSS** (not CSS Modules with hashed class names) — hashed selectors won't match
</Warning>

***

## Selector Pattern

Use this table to construct the correct CSS selector for any message bubble target. AI agents should use this pattern to generalize — do not guess selectors.

| Target                        | Selector Pattern                                                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| All bubbles                   | `.cometchat .cometchat-message-bubble .cometchat-message-bubble__body`                                                   |
| Outgoing bubbles (all types)  | `.cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body`                                          |
| Incoming bubbles (all types)  | `.cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body`                                          |
| Specific type (outgoing)      | `.cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body.cometchat-message-bubble__<TYPE>-message` |
| Specific type (incoming)      | `.cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body.cometchat-message-bubble__<TYPE>-message` |
| Action bubbles (no direction) | `.cometchat .cometchat-message-bubble__body .cometchat-action-bubble`                                                    |

<Note>
  `<TYPE>`

  `<TYPE>` is one of `text`, `image`, `video`, `audio`, `file`
</Note>

<Note>
  Link Preview Bubbles

  It reuse the `text-message` type selector since link previews are rendered inside text messages.
</Note>

***

## CSS Variable Reference

These are the CSS variables (tokens) used across message bubble styling. This table tells you exactly what each token controls — do not assume a token affects something not listed here.

| Variable                                 | What It Controls                           | Default (Light) | Commonly Used On                                   |
| ---------------------------------------- | ------------------------------------------ | --------------- | -------------------------------------------------- |
| `--cometchat-primary-color`              | Outgoing bubble background, primary accent | `#6852d6`       | Outgoing bubbles (all types), action bubble accent |
| `--cometchat-neutral-color-300`          | Incoming bubble background                 | `#E8E8E8`       | Incoming bubbles (all types)                       |
| `--cometchat-extended-primary-color-900` | Outgoing bubble shade/gradient variant     | `#5d49be`       | Outgoing text bubble, link preview                 |
| `--cometchat-extended-primary-color-800` | Outgoing bubble secondary shade            | `#5745b4`       | Direct call outgoing bubble                        |
| `--cometchat-extended-primary-color-700` | Outgoing bubble tertiary shade             | `#4f3ea3`       | Poll outgoing bubble                               |
| `--cometchat-neutral-color-400`          | Incoming bubble secondary shade            | varies          | Link preview incoming                              |
| `--cometchat-primary-button-background`  | Primary button fill inside bubbles         | matches primary | Whiteboard/document incoming buttons               |
| `--cometchat-text-color-secondary`       | Secondary/caption text color               | varies          | Action bubble text                                 |
| `--cometchat-icon-color-secondary`       | Secondary icon color                       | varies          | Action bubble icons                                |
| `--cometchat-border-color-default`       | Default border color                       | varies          | Action bubble borders                              |

***

<Note>
  **CSS Specificity & Precedence Rules:**

  1. Message-type selectors (e.g., `__text-message`) override "All Message Bubbles" selectors
  2. Always keep the `.cometchat` prefix to avoid leaking styles into the host app
  3. Component-level variable overrides (`.cometchat-message-list { --var: val }`) override global overrides (`.cometchat { --var: val }`)
  4. CSS variable overrides only affect properties the UI Kit theme binds to that variable — they do NOT change layout or spacing
  5. `!important` should never be needed — if it is, your selector specificity is wrong
</Note>

***

## Bubble Structure

Each message bubble has this DOM structure:

```
.cometchat-message-bubble
  ├── .cometchat-message-bubble__leading-view (avatar)
  ├── .cometchat-message-bubble__header-view (sender name)
  ├── .cometchat-message-bubble__body-container
  │   ├── .cometchat-message-bubble__body-wrapper
  │   │   ├── .cometchat-message-bubble__body
  │   │   │   ├── .cometchat-message-bubble__body-reply-view (quoted message)
  │   │   │   ├── .cometchat-message-bubble__body-content-view (plugin bubble content)
  │   │   │   └── .cometchat-message-bubble__body-status-info-view (timestamp + receipts)
  │   │   ├── .cometchat-message-bubble__body-footer-view (reactions)
  │   │   ├── .cometchat-message-bubble__body-thread-view (reply count)
  │   │   └── .cometchat-message-bubble__body-bottom-view (moderation)
  │   └── .cometchat-message-bubble__options (context menu)
```

***

## Incoming & Outgoing Messages

Incoming and outgoing messages have different styling by default, allowing users to visually separate their own messages from others'. Here, we show both the default view and examples of customizations for these message bubbles.

Shown below is the default chat interface.

<Frame>
  <img />
</Frame>

***

### Styling

#### Outgoing Message Bubbles

**Selectors:**

```css theme={null}
.cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body
```

**Tokens used:**

| Token                                    | Controls                   |
| ---------------------------------------- | -------------------------- |
| `--cometchat-primary-color`              | Outgoing bubble background |
| `--cometchat-extended-primary-color-900` | Outgoing bubble shade      |

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

Use the following code to achieve the customization shown above.

```css title="App.css" theme={null}
.cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body {
  --cometchat-primary-color: #f76808;
  --cometchat-extended-primary-color-900: #fbaa75;
}
```

**Expected result:** All outgoing message bubbles change from purple to orange (#f76808) with a lighter orange shade (#fbaa75).

***

#### Incoming Message Bubbles

**Selectors:**

```css theme={null}
.cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body
```

**Tokens used:**

| Token                           | Controls                   |
| ------------------------------- | -------------------------- |
| `--cometchat-neutral-color-300` | Incoming bubble background |

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

Use the following code to achieve the customization shown above.

```css title="App.css" theme={null}
.cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body {
  --cometchat-neutral-color-300: #f76808;
}
```

**Expected result:** All incoming message bubbles change from white/light to orange (#f76808).

***

#### All Message Bubbles

**Selectors:**

```css theme={null}
.cometchat .cometchat-message-bubble .cometchat-message-bubble__body
```

**Tokens used:**

| Token                                    | Controls                   |
| ---------------------------------------- | -------------------------- |
| `--cometchat-neutral-color-300`          | Incoming bubble background |
| `--cometchat-primary-color`              | Outgoing bubble background |
| `--cometchat-extended-primary-color-900` | Outgoing bubble shade      |

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

Use the following code to achieve the customization shown above.

```css title="App.css" theme={null}
.cometchat .cometchat-message-bubble .cometchat-message-bubble__body {
  --cometchat-neutral-color-300: #f76808;
  --cometchat-primary-color: #f76808;
  --cometchat-extended-primary-color-900: #fbaa75;
}
```

**Expected result:** Both incoming and outgoing bubbles use orange (#f76808), with outgoing shade set to lighter orange (#fbaa75).

***

### Complete End-to-End Example

To apply custom bubble colors in your app:

**Step 1:** Add to `App.css`:

```css theme={null}
/* Custom outgoing bubbles */
.cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body {
  --cometchat-primary-color: #f76808;
  --cometchat-extended-primary-color-900: #fbaa75;
}

/* Custom incoming bubbles */
.cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body {
  --cometchat-neutral-color-300: #feede1;
}
```

**Step 2:** Ensure `App.tsx` imports the CSS:

```tsx theme={null}
import "./App.css";
// ... render CometChat UI Kit components
```

**Expected result:** Outgoing bubbles use orange (#f76808) with lighter shade (#fbaa75); incoming bubbles use light peach (#feede1).

***

## Message Types

CometChat UI Kit includes classes for various message types. Below are examples of default & customised views for each message type, along with the relevant CSS code snippets so that you can quickly get up to speed with CSS customization.

***

### Text Message Bubble

**Selectors:**

<Tabs>
  <Tab title="Outgoing">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body.cometchat-message-bubble__text-message
    ```
  </Tab>

  <Tab title="Incoming">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body.cometchat-message-bubble__text-message
    ```
  </Tab>
</Tabs>

**Tokens used:**

| Token                           | Controls                        |
| ------------------------------- | ------------------------------- |
| `--cometchat-primary-color`     | Outgoing text bubble background |
| `--cometchat-neutral-color-300` | Incoming text bubble background |

Shown below is the default chat interface.

<Frame>
  <img />
</Frame>

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

**Complete CSS:**

<Tabs>
  <Tab title="App.css">
    ```css theme={null}
    /* Outgoing Text Message Bubble */
    .cometchat
      .cometchat-message-bubble-outgoing
      .cometchat-message-bubble__body.cometchat-message-bubble__text-message {
      --cometchat-primary-color: #f76808;
    }

    /* Incoming Text Message Bubble */
    .cometchat
      .cometchat-message-bubble-incoming
      .cometchat-message-bubble__body.cometchat-message-bubble__text-message {
      --cometchat-neutral-color-300: #feede1;
    }
    ```
  </Tab>
</Tabs>

**Expected result:** Outgoing text bubbles change to orange (#f76808); incoming text bubbles change to light peach (#feede1).

***

### Image Message Bubble

Image messages render with the [Image Bubble](/docs/ui-kit/react/components/image-bubble) (`.cometchat-images-bubble`, with `--incoming` / `--outgoing` / `--single` modifiers) — the batch-aware component that lays out one or more images in a grid. The **bubble background** (visible behind the grid, in the gaps and the "+N" overflow tile) is set through the `__image-message` body selector below; target `.cometchat-images-bubble` for the media content itself.

**Selectors:**

<Tabs>
  <Tab title="Outgoing">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body.cometchat-message-bubble__image-message
    ```
  </Tab>

  <Tab title="Incoming">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body.cometchat-message-bubble__image-message
    ```
  </Tab>
</Tabs>

**Tokens used:**

| Token                           | Controls                         |
| ------------------------------- | -------------------------------- |
| `--cometchat-primary-color`     | Outgoing image bubble background |
| `--cometchat-neutral-color-300` | Incoming image bubble background |

Shown below is the default chat interface.

<Frame>
  <img />
</Frame>

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

**Complete CSS:**

<Tabs>
  <Tab title="App.css">
    ```css theme={null}
    /* Outgoing Image Message Bubble */
    .cometchat
      .cometchat-message-bubble-outgoing
      .cometchat-message-bubble__body.cometchat-message-bubble__image-message {
      --cometchat-primary-color: #f76808;
    }

    /* Incoming Image Message Bubble */
    .cometchat
      .cometchat-message-bubble-incoming
      .cometchat-message-bubble__body.cometchat-message-bubble__image-message {
      --cometchat-neutral-color-300: #feede1;
    }
    ```
  </Tab>
</Tabs>

**Expected result:** Outgoing image bubbles change to orange (#f76808); incoming image bubbles change to light peach (#feede1).

***

### Video Message Bubble

Video messages render with the [Video Bubble](/docs/ui-kit/react/components/video-bubble) (`.cometchat-videos-bubble`, with `--incoming` / `--outgoing` / `--single` modifiers) — the batch-aware component that lays out one or more video thumbnails in a grid. The **bubble background** is set through the `__video-message` body selector below; target `.cometchat-videos-bubble` for the media content itself.

**Selectors:**

<Tabs>
  <Tab title="Outgoing">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body.cometchat-message-bubble__video-message
    ```
  </Tab>

  <Tab title="Incoming">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body.cometchat-message-bubble__video-message
    ```
  </Tab>
</Tabs>

**Tokens used:**

| Token                           | Controls                         |
| ------------------------------- | -------------------------------- |
| `--cometchat-primary-color`     | Outgoing video bubble background |
| `--cometchat-neutral-color-300` | Incoming video bubble background |

Shown below is the default chat interface.

<Frame>
  <img />
</Frame>

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

**Complete CSS:**

<Tabs>
  <Tab title="App.css">
    ```css theme={null}
    /* Outgoing Video Message Bubble */
    .cometchat
      .cometchat-message-bubble-outgoing
      .cometchat-message-bubble__body.cometchat-message-bubble__video-message {
      --cometchat-primary-color: #f76808;
    }

    /* Incoming Video Message Bubble */
    .cometchat
      .cometchat-message-bubble-incoming
      .cometchat-message-bubble__body.cometchat-message-bubble__video-message {
      --cometchat-neutral-color-300: #feede1;
    }
    ```
  </Tab>
</Tabs>

**Expected result:** Outgoing video bubbles change to orange (#f76808); incoming video bubbles change to light peach (#feede1).

***

### Audio Message Bubble

Attached audio files render with the [Audio Bubble](/docs/ui-kit/react/components/audio-bubble) (`.cometchat-audios-bubble`) — stacked playback cards. A **single** audio card is transparent and shows the bubble background; when a message carries **multiple** audio files, each card gets its own background. The bubble background is set through the `__audio-message` body selector below.

<Note>
  Attached audio and **voice notes** share the same `__audio-message` body type class, so an `__audio-message` selector styles **both**. To target only attached audio, use `.cometchat-audios-bubble`; to target only voice notes, use `.cometchat-audio-bubble` (see [Voice Note Message Bubble](#voice-note-message-bubble)).
</Note>

**Selectors:**

<Tabs>
  <Tab title="Outgoing">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body.cometchat-message-bubble__audio-message
    ```
  </Tab>

  <Tab title="Incoming">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body.cometchat-message-bubble__audio-message
    ```
  </Tab>
</Tabs>

**Tokens used:**

| Token                                    | Controls                                                                              |
| ---------------------------------------- | ------------------------------------------------------------------------------------- |
| `--cometchat-primary-color`              | Outgoing bubble background & single card; incoming play button + download-icon accent |
| `--cometchat-neutral-color-300`          | Incoming bubble background (single card)                                              |
| `--cometchat-extended-primary-color-700` | Outgoing background of each card in a multi-audio message, and the expand toggle      |
| `--cometchat-neutral-color-350`          | Incoming background of each card in a multi-audio message, and the expand toggle      |
| `--cometchat-static-white`               | Outgoing card text, play-button fill, time & download icon                            |
| `--cometchat-neutral-color-600`          | Incoming time text                                                                    |

Shown below is the default chat interface.

<Frame>
  <img />
</Frame>

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

**Complete CSS:**

<Tabs>
  <Tab title="App.css">
    ```css theme={null}
    /* Outgoing Audio Message Bubble */
    .cometchat
      .cometchat-message-bubble-outgoing
      .cometchat-message-bubble__body.cometchat-message-bubble__audio-message {
      --cometchat-primary-color: #f76808; /* bubble + single-card background */
      --cometchat-extended-primary-color-700: #fbaa75; /* stacked-card background + toggle */
    }

    /* Incoming Audio Message Bubble */
    .cometchat
      .cometchat-message-bubble-incoming
      .cometchat-message-bubble__body.cometchat-message-bubble__audio-message {
      --cometchat-primary-color: #f76808; /* play button + download icon accent */
      --cometchat-neutral-color-300: #feede1; /* single-card bubble background */
      --cometchat-neutral-color-350: #fbd9c0; /* stacked-card background + toggle */
    }
    ```
  </Tab>
</Tabs>

**Expected result:** Outgoing audio bubbles change to orange (#f76808) with lighter-orange stacked cards (#fbaa75); incoming audio bubbles change to light peach (#feede1) with orange playback controls and peach stacked cards (#fbd9c0).

***

### File Message Bubble

File attachments render with the [File Bubble](/docs/ui-kit/react/components/file-bubble) (`.cometchat-files-bubble`) — stacked file cards with type icons. A **single** file card is transparent and shows the bubble background; when a message carries **multiple** files, each card gets its own background. The bubble background is set through the `__file-message` body selector below; target `.cometchat-files-bubble` for the card content.

**Selectors:**

<Tabs>
  <Tab title="Outgoing">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body.cometchat-message-bubble__file-message
    ```
  </Tab>

  <Tab title="Incoming">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body.cometchat-message-bubble__file-message
    ```
  </Tab>
</Tabs>

**Tokens used:**

| Token                                    | Controls                                                                        |
| ---------------------------------------- | ------------------------------------------------------------------------------- |
| `--cometchat-primary-color`              | Outgoing bubble background & single card; incoming download-icon accent         |
| `--cometchat-neutral-color-300`          | Incoming bubble background (single card)                                        |
| `--cometchat-extended-primary-color-700` | Outgoing background of each card in a multi-file message, and the expand toggle |
| `--cometchat-neutral-color-350`          | Incoming background of each card in a multi-file message, and the expand toggle |
| `--cometchat-static-white`               | Outgoing card name text & download icon                                         |
| `--cometchat-neutral-color-600`          | Incoming file meta (size / extension) text                                      |

Shown below is the default chat interface.

<Frame>
  <img />
</Frame>

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

**Complete CSS:**

<Tabs>
  <Tab title="App.css">
    ```css theme={null}
    /* Outgoing File Message Bubble */
    .cometchat
      .cometchat-message-bubble-outgoing
      .cometchat-message-bubble__body.cometchat-message-bubble__file-message {
      --cometchat-primary-color: #f76808; /* bubble + single-card background */
      --cometchat-extended-primary-color-700: #fbaa75; /* stacked-card background + toggle */
    }

    /* Incoming File Message Bubble */
    .cometchat
      .cometchat-message-bubble-incoming
      .cometchat-message-bubble__body.cometchat-message-bubble__file-message {
      --cometchat-primary-color: #f76808; /* download icon accent */
      --cometchat-neutral-color-300: #feede1; /* single-card bubble background */
      --cometchat-neutral-color-350: #fbd9c0; /* stacked-card background + toggle */
    }
    ```
  </Tab>
</Tabs>

**Expected result:** Outgoing file bubbles change to orange (#f76808) with lighter-orange stacked cards (#fbaa75); incoming file bubbles change to light peach (#feede1) with peach stacked cards (#fbd9c0) and an orange download-icon accent.

***

### Voice Note Message Bubble

Voice notes — audio messages recorded in the composer (tagged `audioType: "voice_note"`) — render with the [Voice Note Bubble](/docs/ui-kit/react/components/voice-note-bubble) (`.cometchat-audio-bubble`), a standalone waveform player. Its direction modifiers are `--sender` (outgoing) and `--receiver` (incoming).

<Note>
  Voice notes share the `__audio-message` body type class with attached audio, so an `__audio-message` selector styles **both**. To target **only voice notes**, use `.cometchat-audio-bubble`; for **only attached audio files**, use `.cometchat-audios-bubble`.
</Note>

**Selectors:**

<Tabs>
  <Tab title="Outgoing (sender)">
    ```css theme={null}
    .cometchat .cometchat-audio-bubble.cometchat-audio-bubble--sender
    ```
  </Tab>

  <Tab title="Incoming (receiver)">
    ```css theme={null}
    .cometchat .cometchat-audio-bubble.cometchat-audio-bubble--receiver
    ```
  </Tab>
</Tabs>

**Tokens used:**

| Token                                                             | Controls                                                                                                |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `--cometchat-primary-color`                                       | Outgoing bubble background (via fallback) & play/pause icon; incoming waveform progress + download icon |
| `--cometchat-neutral-color-300`                                   | Incoming bubble background                                                                              |
| `--cometchat-static-white`                                        | Outgoing waveform progress, play-button fill & time text                                                |
| `--cometchat-neutral-color-500` / `--cometchat-neutral-color-400` | Unplayed waveform track (outgoing / incoming)                                                           |
| `--cometchat-neutral-color-600`                                   | Incoming time text                                                                                      |
| `--cometchat-audio-bubble-background`                             | Overrides the bubble background independently of `--cometchat-primary-color` (both directions)          |

**Complete CSS:**

<Tabs>
  <Tab title="App.css">
    ```css theme={null}
    /* Outgoing Voice Note Bubble (sender) */
    .cometchat .cometchat-audio-bubble.cometchat-audio-bubble--sender {
      --cometchat-primary-color: #f76808; /* bubble background (via fallback) + play icon */
    }

    /* Incoming Voice Note Bubble (receiver) */
    .cometchat .cometchat-audio-bubble.cometchat-audio-bubble--receiver {
      --cometchat-primary-color: #f76808; /* waveform progress + download icon */
      --cometchat-neutral-color-300: #feede1; /* bubble background */
    }
    ```
  </Tab>
</Tabs>

**Expected result:** Outgoing voice notes use an orange bubble (#f76808) with a white waveform and controls; incoming voice notes use a light-peach bubble (#feede1) with orange waveform progress and controls.

***

### Action Message Bubble

Action messages (e.g., "User joined the group") use a different selector pattern — they are not directional (no incoming/outgoing).

**Selector:**

* `.cometchat .cometchat-message-bubble__body .cometchat-action-bubble`

**Tokens used:**

| Token                              | Controls                                                       |
| ---------------------------------- | -------------------------------------------------------------- |
| `--cometchat-primary-color`        | Action bubble accent color                                     |
| `background-color`                 | Action bubble background (direct CSS property, not a variable) |
| `--cometchat-text-color-secondary` | Action bubble text color                                       |
| `--cometchat-icon-color-secondary` | Action bubble icon color                                       |
| `--cometchat-border-color-default` | Action bubble border color                                     |

Shown below is the default chat interface.

<Frame>
  <img />
</Frame>

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

**Complete CSS:**

<Tabs>
  <Tab title="App.css">
    ```css theme={null}
    .cometchat .cometchat-message-bubble__body .cometchat-action-bubble {
      --cometchat-primary-color: #f76808;
      background-color: #feede1;
      --cometchat-text-color-secondary: #f76808;
      --cometchat-icon-color-secondary: #f76808;
      --cometchat-border-color-default: #f76808;
    }
    ```
  </Tab>
</Tabs>

**Expected result:** Action message banners change to light peach background (#feede1) with orange text, icons, and borders (#f76808).

***

### Extensions

#### Collaborative Whiteboard Bubble

**Selectors:**

<Tabs>
  <Tab title="Outgoing">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body.cometchat-message-bubble__text-message
    ```
  </Tab>

  <Tab title="Incoming">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body.cometchat-message-bubble__text-message
    ```
  </Tab>
</Tabs>

<Note>
  Collaborative whiteboard messages use the `text-message` type class internally.
</Note>

**Tokens used:**

| Token                                   | Controls                               |
| --------------------------------------- | -------------------------------------- |
| `--cometchat-primary-color`             | Bubble accent and background           |
| `--cometchat-primary-button-background` | Incoming whiteboard "Open" button fill |
| `--cometchat-neutral-color-300`         | Incoming bubble background             |

Shown below is the default chat interface.

<Frame>
  <img />
</Frame>

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

**Complete CSS:**

<Tabs>
  <Tab title="App.css">
    ```css theme={null}
    /* Outgoing Collaborative Whiteboard Bubble */
    .cometchat
      .cometchat-message-bubble-outgoing
      .cometchat-message-bubble__body.cometchat-message-bubble__text-message {
      --cometchat-primary-color: #f76808;
    }

    /* Incoming Collaborative Whiteboard Bubble */
    .cometchat
      .cometchat-message-bubble-incoming
      .cometchat-message-bubble__body.cometchat-message-bubble__text-message {
      --cometchat-primary-color: #f76808;
      --cometchat-primary-button-background: #f76808;
      --cometchat-neutral-color-300: #feede1;
    }
    ```
  </Tab>
</Tabs>

**Expected result:** Outgoing whiteboard bubbles change to orange (#f76808); incoming whiteboard bubbles change to light peach (#feede1) with orange button and accent.

***

#### Collaborative Document Bubble

**Selectors:**

<Tabs>
  <Tab title="Outgoing">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body.cometchat-message-bubble__text-message
    ```
  </Tab>

  <Tab title="Incoming">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body.cometchat-message-bubble__text-message
    ```
  </Tab>
</Tabs>

<Note>
  Collaborative document messages use the `text-message` type class internally.
</Note>

**Tokens used:**

| Token                                   | Controls                             |
| --------------------------------------- | ------------------------------------ |
| `--cometchat-primary-color`             | Bubble accent and background         |
| `--cometchat-primary-button-background` | Incoming document "Open" button fill |
| `--cometchat-neutral-color-300`         | Incoming bubble background           |

Shown below is the default chat interface.

<Frame>
  <img />
</Frame>

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

**Complete CSS:**

<Tabs>
  <Tab title="App.css">
    ```css theme={null}
    /* Outgoing Collaborative Document Bubble */
    .cometchat
      .cometchat-message-bubble-outgoing
      .cometchat-message-bubble__body.cometchat-message-bubble__text-message {
      --cometchat-primary-color: #f76808;
    }

    /* Incoming Collaborative Document Bubble */
    .cometchat
      .cometchat-message-bubble-incoming
      .cometchat-message-bubble__body.cometchat-message-bubble__text-message {
      --cometchat-primary-color: #f76808;
      --cometchat-primary-button-background: #f76808;
      --cometchat-neutral-color-300: #feede1;
    }
    ```
  </Tab>
</Tabs>

**Expected result:** Outgoing document bubbles change to orange (#f76808); incoming document bubbles change to light peach (#feede1) with orange button and accent.

***

#### Polls Bubble

**Selectors:**

<Tabs>
  <Tab title="Outgoing">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body.cometchat-message-bubble__text-message
    ```
  </Tab>

  <Tab title="Incoming">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body.cometchat-message-bubble__text-message
    ```
  </Tab>
</Tabs>

<Note>
  Poll messages use the `text-message` type class internally.
</Note>

**Tokens used:**

| Token                                    | Controls                         |
| ---------------------------------------- | -------------------------------- |
| `--cometchat-primary-color`              | Bubble accent and background     |
| `--cometchat-extended-primary-color-700` | Outgoing poll progress bar shade |
| `--cometchat-neutral-color-300`          | Incoming bubble background       |

Shown below is the default chat interface.

<Frame>
  <img />
</Frame>

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

**Complete CSS:**

<Tabs>
  <Tab title="App.css">
    ```css theme={null}
    /* Outgoing Poll Message Bubble */
    .cometchat
      .cometchat-message-bubble-outgoing
      .cometchat-message-bubble__body.cometchat-message-bubble__text-message {
      --cometchat-primary-color: #f76808;
      --cometchat-extended-primary-color-700: #fbaa75;
    }

    /* Incoming Poll Message Bubble */
    .cometchat
      .cometchat-message-bubble-incoming
      .cometchat-message-bubble__body.cometchat-message-bubble__text-message {
      --cometchat-primary-color: #f76808;
      --cometchat-neutral-color-300: #feede1;
    }
    ```
  </Tab>
</Tabs>

**Expected result:** Outgoing poll bubbles change to orange (#f76808) with lighter progress bars (#fbaa75); incoming poll bubbles change to light peach (#feede1) with orange accent.

***

#### Stickers Bubble

**Selectors:**

<Tabs>
  <Tab title="Outgoing">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body.cometchat-message-bubble__image-message
    ```
  </Tab>

  <Tab title="Incoming">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body.cometchat-message-bubble__image-message
    ```
  </Tab>
</Tabs>

<Note>
  Sticker messages use the `image-message` type class internally.
</Note>

**Tokens used:**

| Token                           | Controls                           |
| ------------------------------- | ---------------------------------- |
| `--cometchat-primary-color`     | Outgoing sticker bubble background |
| `--cometchat-neutral-color-300` | Incoming sticker bubble background |

Shown below is the default chat interface.

<Frame>
  <img />
</Frame>

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

**Complete CSS:**

<Tabs>
  <Tab title="App.css">
    ```css theme={null}
    /* Outgoing Sticker Bubble */
    .cometchat
      .cometchat-message-bubble-outgoing
      .cometchat-message-bubble__body.cometchat-message-bubble__image-message {
      --cometchat-primary-color: #f76808;
    }

    /* Incoming Sticker Bubble */
    .cometchat
      .cometchat-message-bubble-incoming
      .cometchat-message-bubble__body.cometchat-message-bubble__image-message {
      --cometchat-neutral-color-300: #feede1;
    }
    ```
  </Tab>
</Tabs>

**Expected result:** Outgoing sticker bubbles change to orange (#f76808); incoming sticker bubbles change to light peach (#feede1).

***

#### Link Preview Bubble

Link previews render inside text message bubbles, so they use the `text-message` type selector.

**Selectors:**

<Tabs>
  <Tab title="Outgoing">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body.cometchat-message-bubble__text-message
    ```
  </Tab>

  <Tab title="Incoming">
    ```css theme={null}
    .cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body.cometchat-message-bubble__text-message
    ```
  </Tab>
</Tabs>

**Tokens used:**

| Token                                    | Controls                                |
| ---------------------------------------- | --------------------------------------- |
| `--cometchat-primary-color`              | Outgoing link preview bubble background |
| `--cometchat-extended-primary-color-900` | Outgoing link preview shade             |
| `--cometchat-neutral-color-400`          | Incoming link preview secondary shade   |
| `--cometchat-neutral-color-300`          | Incoming link preview bubble background |

<Note>
  Styling link preview bubbles also affects regular text message bubbles since they share the same `__text-message` selector. This is by design — link previews are a sub-feature of text messages.
</Note>

Shown below is the default chat interface.

<Frame>
  <img />
</Frame>

The customized chat interface is displayed below.

<Frame>
  <img />
</Frame>

**Complete CSS:**

<Tabs>
  <Tab title="App.css">
    ```css theme={null}
    /* Outgoing Link Preview Bubble */
    .cometchat
      .cometchat-message-bubble-outgoing
      .cometchat-message-bubble__body.cometchat-message-bubble__text-message {
      --cometchat-primary-color: #f76808;
      --cometchat-extended-primary-color-900: #fbaa75;
    }

    /* Incoming Link Preview Bubble */
    .cometchat
      .cometchat-message-bubble-incoming
      .cometchat-message-bubble__body.cometchat-message-bubble__text-message {
      --cometchat-neutral-color-400: #fbaa75;
      --cometchat-neutral-color-300: #feede1;
    }
    ```
  </Tab>
</Tabs>

**Expected result:** Outgoing link preview bubbles change to orange (#f76808) with lighter shade (#fbaa75); incoming link preview bubbles change to light peach (#feede1) with orange secondary shade (#fbaa75).

***

## CSS Selectors Reference

Class names are plain, stable BEM names that you can target directly:

| Target                               | Selector                                           |
| ------------------------------------ | -------------------------------------------------- |
| Bubble wrapper                       | `.cometchat-message-bubble`                        |
| Leading view (avatar)                | `.cometchat-message-bubble__leading-view`          |
| Header view (sender name)            | `.cometchat-message-bubble__header-view`           |
| Sender name                          | `.cometchat-message-bubble__sender-name`           |
| Body container                       | `.cometchat-message-bubble__body-container`        |
| Body wrapper                         | `.cometchat-message-bubble__body-wrapper`          |
| Body                                 | `.cometchat-message-bubble__body`                  |
| Reply view (quoted message)          | `.cometchat-message-bubble__body-reply-view`       |
| Content view                         | `.cometchat-message-bubble__body-content-view`     |
| Status info (time + receipts)        | `.cometchat-message-bubble__body-status-info-view` |
| Footer (reactions)                   | `.cometchat-message-bubble__body-footer-view`      |
| Thread indicator                     | `.cometchat-message-bubble__body-thread-view`      |
| Bottom (moderation)                  | `.cometchat-message-bubble__body-bottom-view`      |
| Options (context menu)               | `.cometchat-message-bubble__options`               |
| Incoming direction                   | `.cometchat-message-bubble-incoming`               |
| Outgoing direction                   | `.cometchat-message-bubble-outgoing`               |
| Action message                       | `.cometchat-message-bubble-action`                 |
| Images bubble (media content)        | `.cometchat-images-bubble`                         |
| Videos bubble (media content)        | `.cometchat-videos-bubble`                         |
| Audios bubble (attached-audio cards) | `.cometchat-audios-bubble`                         |
| Files bubble (file cards)            | `.cometchat-files-bubble`                          |
| Voice note bubble (waveform)         | `.cometchat-audio-bubble`                          |

<Note>
  All class names follow BEM conventions and are stable across builds. You can target them with standard `.class-name` selectors in your CSS.
</Note>


# Theming
Source: https://www.cometchat.com/docs/ui-kit/react/theming

Customize colors, fonts, spacing, and component styles using CSS custom properties and the data-theme attribute.

<Accordion title="AI Integration Quick Reference">
  | Field           | Value                                                             |
  | --------------- | ----------------------------------------------------------------- |
  | Theme prop      | `theme="light"` or `theme="dark"` on `CometChatProvider`          |
  | Root selector   | `.cometchat` (wrapper div with `data-theme` attribute)            |
  | Token prefix    | `--cometchat-*`                                                   |
  | Built-in themes | `light` (default), `dark`                                         |
  | Custom theme    | Override CSS variables on `.cometchat` or `[data-theme="custom"]` |
</Accordion>

## Overview

The v7 UI Kit uses **CSS custom properties** (design tokens) for all visual styling. Every color, font, spacing value, and border radius is defined as a `--cometchat-*` variable. Components reference these tokens — never hardcoded values.

Theming works through the `data-theme` attribute on the `.cometchat` wrapper div. The built-in `light.css` and `dark.css` files define token values for each theme. You can override any token to create custom themes.

***

## Setting the Theme

Pass the `theme` prop to `CometChatProvider`:

```tsx theme={null}
<CometChatProvider theme="dark">
  <MyChatApp />
</CometChatProvider>
```

This sets `data-theme="dark"` on the wrapper, which activates the dark theme CSS variables.

***

## Switching Themes at Runtime

Use the `useTheme` hook inside any component within the provider:

```tsx theme={null}
import { useTheme } from "@cometchat/chat-uikit-react";

function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  return (
    <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
      Current: {theme}
    </button>
  );
}
```

***

## Customizing Tokens

Override CSS variables to change the look of all components at once:

```css title="src/cometchat-overrides.css" theme={null}
.cometchat {
  --cometchat-primary-color: #e91e63;
  --cometchat-font-family: "Inter", sans-serif;
  --cometchat-radius-3: 16px;
}
```

Import this file after the UI Kit styles:

```tsx theme={null}
import "./cometchat-overrides.css";
```

### Per-Theme Overrides

Target a specific theme with the `data-theme` selector:

```css theme={null}
[data-theme="dark"] .cometchat {
  --cometchat-primary-color: #bb86fc;
  --cometchat-background-color-01: #121212;
}
```

### Per-Component Overrides

Target a specific component by its BEM class name:

```css theme={null}
.cometchat-conversations {
  --cometchat-background-color-01: #f5f5f5;
}

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

Or wrap the component in your own class:

```css theme={null}
.my-sidebar {
  --cometchat-background-color-01: #f5f5f5;
}
```

***

## Design Token Categories

### Colors

| Token                                            | Purpose                                                                         |
| ------------------------------------------------ | ------------------------------------------------------------------------------- |
| `--cometchat-primary-color`                      | Brand color (buttons, links, highlights)                                        |
| `--cometchat-extended-primary-color-50` to `900` | Primary color scale (50 = lightest)                                             |
| `--cometchat-neutral-color-50` to `900`          | Gray scale for backgrounds, borders, text (includes an intermediate `350` step) |
| `--cometchat-info-color`                         | Informational (blue)                                                            |
| `--cometchat-warning-color`                      | Warning (amber)                                                                 |
| `--cometchat-success-color`                      | Success (green)                                                                 |
| `--cometchat-error-color`                        | Error (red)                                                                     |
| `--cometchat-static-black`                       | Always black regardless of theme                                                |
| `--cometchat-static-white`                       | Always white regardless of theme                                                |
| `--cometchat-static-white-70`                    | `--cometchat-static-white` at 70% opacity — for scrims/overlays on media        |
| `--cometchat-static-neutral-100` / `400` / `700` | Fixed neutral tones that stay constant across light and dark themes             |

### Semantic Colors

| Token                                                                                  | Purpose                                                     |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `--cometchat-background-color-01` to `04`                                              | Background layers (01 = base, 04 = elevated)                |
| `--cometchat-border-color-light` / `default` / `dark` / `highlight`                    | Border variants                                             |
| `--cometchat-text-color-primary` / `secondary` / `tertiary` / `disabled` / `highlight` | Text colors                                                 |
| `--cometchat-icon-color-primary` / `secondary` / `tertiary` / `highlight`              | Icon colors                                                 |
| `--cometchat-drop-overlay-background`                                                  | Scrim behind the drag-and-drop file overlay on the composer |

### Typography

| Token                                                       | Value format                                          |
| ----------------------------------------------------------- | ----------------------------------------------------- |
| `--cometchat-font-family`                                   | Font stack (default: `'Roboto', 'Inter', sans-serif`) |
| `--cometchat-font-title-bold`                               | `700 32px/38.4px var(--cometchat-font-family)`        |
| `--cometchat-font-heading1-bold` through `heading4-regular` | Heading scales                                        |
| `--cometchat-font-body-bold` / `medium` / `regular`         | Body text (14px)                                      |
| `--cometchat-font-caption1-bold` / `medium` / `regular`     | Small text (12px)                                     |
| `--cometchat-font-caption2-bold` / `medium` / `regular`     | Smallest text (10px)                                  |

### Spacing & Layout

| Token                                             | Purpose                                                  |
| ------------------------------------------------- | -------------------------------------------------------- |
| `--cometchat-spacing` to `--cometchat-spacing-20` | Spacing scale (2px increments: 2, 4, 8, 12, 16, ..., 80) |
| `--cometchat-padding` to `--cometchat-padding-10` | Padding (maps to spacing)                                |
| `--cometchat-margin` to `--cometchat-margin-20`   | Margin (maps to spacing)                                 |
| `--cometchat-radius` to `--cometchat-radius-6`    | Border radius scale                                      |
| `--cometchat-radius-max`                          | Fully rounded (1000px)                                   |

### Buttons

| Token                                     | Purpose                           |
| ----------------------------------------- | --------------------------------- |
| `--cometchat-primary-button-background`   | Primary button background         |
| `--cometchat-primary-button-text`         | Primary button text color         |
| `--cometchat-primary-button-icon`         | Primary button icon color         |
| `--cometchat-secondary-button-background` | Secondary button background       |
| `--cometchat-secondary-button-text`       | Secondary button text color       |
| `--cometchat-fab-button-background`       | Floating action button background |

***

## Component CSS Classes

The UI Kit uses plain, unhashed BEM class names in the DOM. All component class names follow the pattern `cometchat-{component}` with BEM modifiers (e.g., `cometchat-message-bubble__content--outgoing`). You can target them directly with standard class selectors.

### What Works

**1. The `.cometchat` wrapper class** — the root div. Override tokens here to affect all components:

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

**2. Plain class selectors** — target any component by its BEM class name:

```css theme={null}
.cometchat-conversations {
  --cometchat-background-color-01: #f5f5f5;
}

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

**3. Wrap in your own class** — add a wrapper div with your own class and set tokens there:

```tsx theme={null}
<div className="my-chat-sidebar">
  <CometChatConversations />
</div>
```

```css theme={null}
.my-chat-sidebar {
  --cometchat-background-color-01: #f5f5f5;
  --cometchat-primary-color: #1976d2;
}
```

<Note>
  CSS variable overrides work at any level of the tree. Set them on `.cometchat` (the root wrapper) to affect all components, or use class selectors / wrapper classes to scope the change. Variables cascade down — a value set on a parent will be inherited by all CometChat components within it.
</Note>

***

## Creating a Custom Theme

Define a complete set of tokens under a custom `data-theme` value:

```css title="src/themes/brand.css" theme={null}
[data-theme="brand"] {
  --cometchat-primary-color: #e91e63;
  --cometchat-extended-primary-color-500: #e91e63;
  --cometchat-background-color-01: #fce4ec;
  --cometchat-background-color-02: #f8bbd0;
  --cometchat-font-family: "Poppins", sans-serif;
  /* ... override all tokens as needed */
}
```

Then pass your theme name:

```tsx theme={null}
<CometChatProvider theme="brand">
```

<Note>
  When creating a custom theme, start from the light or dark theme file and override only what you need. Unset tokens will fall back to the `:root` defaults (light theme).
</Note>

***

## Next Steps

<CardGroup>
  <Card title="Color Resources" icon="palette" href="/ui-kit/react/theme/color-resources">
    Full color token reference with swatches
  </Card>

  <Card title="Message Bubble Styling" icon="message" href="/ui-kit/react/theme/message-bubble-styling">
    Customize bubble appearance, alignment, and spacing
  </Card>
</CardGroup>


# Troubleshooting
Source: https://www.cometchat.com/docs/ui-kit/react/troubleshooting

Solutions for common issues when using CometChat React UI Kit v7

## SSR Hydration Errors

### Symptom

You see a React hydration mismatch error in the console when rendering your app with a server-side rendering framework (Next.js, Remix, Astro SSR):

```
Error: Hydration failed because the initial UI does not match what was rendered on the server.
```

### Root Cause

`CometChatProvider` uses browser-only APIs (WebSocket connections, `window`, `localStorage`). When a parent component renders on the server, it produces different output than the client, causing a hydration mismatch.

### Solution

Mark the component boundary containing `CometChatProvider` as client-only. In Next.js App Router, add the `'use client'` directive at the top of the file:

```tsx theme={null}
'use client';

import { useEffect, useState } from 'react';
import { CometChatUIKit, UIKitSettingsBuilder, CometChatProvider } from '@cometchat/chat-uikit-react';

export function ChatProvider({ children }: { children: React.ReactNode }) {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      setReady(true);
    });
  }, []);

  if (!ready) return null;

  return (
    <CometChatProvider>
      {children}
    </CometChatProvider>
  );
}
```

For Astro, use a `client:only="react"` directive on the component that wraps `CometChatProvider`:

```astro theme={null}
<ChatApp client:only="react" />
```

This ensures `CometChatProvider` only renders in the browser where its required APIs are available.

***

## React StrictMode Double-Mount

### Symptom

You notice duplicate SDK event listeners firing, causing messages to appear twice or callbacks triggering multiple times during development.

### Root Cause

React StrictMode intentionally mounts, unmounts, and remounts components in development to help detect side effects that aren't properly cleaned up. If SDK listeners aren't cleaned up on unmount, the remount adds a second listener.

### Solution

All v7 hooks handle cleanup automatically. If you're writing custom hooks that attach SDK listeners, always return a cleanup function from `useEffect`:

```tsx theme={null}
import { useEffect, useId } from 'react';
import { CometChat } from '@cometchat/chat-sdk-javascript';

function useCustomMessageListener(onMessage: (msg: CometChat.BaseMessage) => void) {
  const listenerId = useId();

  useEffect(() => {
    CometChat.addMessageListener(
      listenerId,
      new CometChat.MessageListener({
        onTextMessageReceived: onMessage,
        onMediaMessageReceived: onMessage,
        onCustomMessageReceived: onMessage,
      })
    );

    // Cleanup removes the listener on unmount
    return () => {
      CometChat.removeMessageListener(listenerId);
    };
  }, [listenerId, onMessage]);
}
```

Key points:

* Use `useId()` for unique listener IDs — it's stable across StrictMode remounts within the same component instance.
* Always remove listeners in the cleanup function returned from `useEffect`.
* The built-in `useCometChatEvents` hook already handles this correctly.

***

## SDK Initialization Failures

### Symptom

The chat UI shows an error state or nothing renders. The console displays:

```
CometChat SDK initialization failed: ERR_INVALID_CREDENTIALS
```

or

```
CometChat SDK initialization failed: ERR_NETWORK
```

### Root Cause

**Invalid credentials:** The `appId`, `region`, or `authKey` passed to `UIKitSettingsBuilder` are incorrect, expired, or belong to a different environment (e.g., using production credentials in a development build).

**Network issues:** The client cannot reach CometChat's servers due to network restrictions, firewall rules, or the CometChat service being temporarily unavailable.

### Solution

Verify your credentials match your CometChat dashboard and add error handling to your init/login flow:

```tsx theme={null}
import { CometChatUIKit, UIKitSettingsBuilder } from '@cometchat/chat-uikit-react';

const settings = new UIKitSettingsBuilder()
  .setAppId(import.meta.env.VITE_COMETCHAT_APP_ID)
  .setRegion(import.meta.env.VITE_COMETCHAT_REGION)
  .setAuthKey(import.meta.env.VITE_COMETCHAT_AUTH_KEY)
  .build();

try {
  await CometChatUIKit.init(settings);
  await CometChatUIKit.login("cometchat-uid-1");
} catch (error) {
  console.error('CometChat initialization error:', error);
}
```

Checklist:

* Confirm `appId` and `region` match the values shown in your [CometChat Dashboard](https://app.cometchat.com)
* Ensure credentials are for the correct environment (development vs. production)
* Check that your network allows outbound WebSocket connections
* Verify the `authKey` has not been rotated since you last copied it

***

## Theme Not Applying

### Symptom

Components render with default styling and ignore the theme you've configured. Colors, fonts, or spacing don't match your custom theme.

### Root Cause

The theme is activated by the `data-theme` attribute on a parent element, which `CometChatProvider`'s `theme` prop sets for you. If the `theme` prop is missing — or set to a custom theme with no matching variable definitions — the theme won't apply.

### Solution

Set the `theme` prop on `CometChatProvider`:

```tsx theme={null}
import { CometChatProvider } from '@cometchat/chat-uikit-react';

function App() {
  return (
    <CometChatProvider theme="dark">
      {/* Components will use dark theme */}
    </CometChatProvider>
  );
}
```

If you're using a custom theme, make sure your CSS defines variables under a matching `[data-theme]` selector:

```css theme={null}
[data-theme="my-brand"] {
  --cometchat-primary-color: #6366f1;
  --cometchat-background-color: #0f0f23;
  --cometchat-text-color: #e2e8f0;
  --cometchat-border-color: #334155;
}
```

Then pass the custom theme name to the provider:

```tsx theme={null}
<CometChatProvider theme="my-brand">
```


# AI Assistant Chat History
Source: https://www.cometchat.com/docs/ui-kit/react-native/ai-assistant-chat-history

Display conversation history between users and AI assistants with CometChatAIAssistantChatHistory component in React Native UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field         | Value                                                                                                  |
  | ------------- | ------------------------------------------------------------------------------------------------------ |
  | Import        | `import { CometChatAIAssistantChatHistory } from "@cometchat/chat-uikit-react-native";`                |
  | Required prop | `user` (with `@agentic` role) or `group`                                                               |
  | Key actions   | `onMessageClicked`, `onNewChatButtonClick`, `onClose`, `onError`                                       |
  | Styling       | `style` prop accepts `ChatHistoryStyle` object                                                         |
  | Custom views  | `LoadingStateView` for custom loading indicator                                                        |
  | Prerequisite  | AI Assistant feature must be enabled in [CometChat Dashboard](https://app.cometchat.com/)              |
  | Related       | [Message List](/docs/ui-kit/react-native/message-list), [Conversations](/docs/ui-kit/react-native/conversations) |
</Accordion>

## Overview

`CometChatAIAssistantChatHistory` is a pre-built user interface element designed to display the conversation history between users and an AI assistant within a chat application. It provides a structured and visually appealing way to present past interactions, making it easy for users to review previous messages and context.

<Frame>
  <img />
</Frame>

***

## Usage

### Integration

`CometChatAIAssistantChatHistory`, as a Composite Component, offers flexible integration options, allowing it to be launched directly via button clicks or any user-triggered action.

The following code snippet exemplifies how you can seamlessly integrate the AI Assistant Chat History component into your application.

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    import React from 'react';
    import { View } from 'react-native';
    import { CometChatAIAssistantChatHistory } from '@cometchat/chat-uikit-react-native';
    import { CometChat } from '@cometchat/chat-sdk-react-native';

    const YourComponent = () => {
      const user = new CometChat.User({
        uid: "userId",
        name: "User Name",
        role: "@agentic" // User role must be @agentic to use AI Assistant features
      });

      return (
        <View style={{ flex: 1 }}>
          <CometChatAIAssistantChatHistory
            user={user}
            onClose={() => {
              // Handle close action
            }}
            onMessageClicked={(message) => {
              // Handle message click
            }}
            onNewChatButtonClick={() => {
              // Handle new chat button click
            }}
            onError={(error) => {
              // Handle error
            }}
          />
        </View>
      );
    };
    ```
  </Tab>
</Tabs>

If you're defining the User within the component, you'll need to ensure the user has the appropriate role set to use AI Assistant features.

***

### Actions

[Actions](/docs/ui-kit/react-native/components-overview#actions) dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the component to fit your specific needs.

##### onMessageClicked

Function invoked when a chat history item is clicked, typically used to open an AI assistant chat screen.

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { CometChatAIAssistantChatHistory } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    <CometChatAIAssistantChatHistory
      user={user}
      onMessageClicked={(message: CometChat.BaseMessage) => {
        // Handle message click
        console.log('Message clicked:', message);
      }}
    />
    ```
  </Tab>
</Tabs>

***

##### onNewChatButtonClick

Function triggered when the new chat button is clicked, typically used to start a new conversation with the AI assistant.

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    <CometChatAIAssistantChatHistory
      user={user}
      onNewChatButtonClick={() => {
        // Handle new chat button click
        console.log('Starting new chat');
      }}
    />
    ```
  </Tab>
</Tabs>

***

##### onClose

Function activated when the close button is clicked, usually to exit the chat history view.

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    <CometChatAIAssistantChatHistory
      user={user}
      onClose={() => {
        // Handle close action
        console.log('Closing chat history');
      }}
    />
    ```
  </Tab>
</Tabs>

***

##### onError

Function invoked when an error occurs during message fetching or any other operation.

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { CometChatAIAssistantChatHistory } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    <CometChatAIAssistantChatHistory
      user={user}
      onError={(error: CometChat.CometChatException) => {
        // Handle error
        console.error('Chat history error:', error);
      }}
    />
    ```
  </Tab>
</Tabs>

## Customization

To fit your app's design requirements, you can customize the appearance of the AI Assistant Chat History component. These customizations are categorized into two main areas: Style and Functionality.

### Style

Using Style you can customize the look and feel of the component in your app. These parameters typically control elements such as the color, size, shape, and fonts used within the component.

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { ChatHistoryStyle } from '@cometchat/chat-uikit-react-native';

    const customStyle: Partial<ChatHistoryStyle> = {
      containerStyle: {
        backgroundColor: '#FFFAF6',
      },
      headerStyle: {
        backgroundColor: '#FFFAF6',
      },
      headerTitleStyle: {
        color: '#000000',
        fontSize: 18,
        fontWeight: 'bold',
      },
      newChatButtonStyle: {
        backgroundColor: '#FFFAF6',
      },
      newChatTextStyle: {
        color: '#000000',
        fontSize: 16,
      },
      sectionHeaderStyle: {
        backgroundColor: '#FFFAF6',
      },
      sectionHeaderTextStyle: {
        color: '#666666',
        fontSize: 14,
      },
      messageItemStyle: {
        backgroundColor: '#FFFFFF',
      },
      messageTextStyle: {
        color: '#000000',
        fontSize: 16,
      },
    };

    <CometChatAIAssistantChatHistory
      user={user}
      style={customStyle}
    />
    ```
  </Tab>
</Tabs>

### Functionality

These are a set of small functional customizations that allow you to fine-tune the overall experience of the component. With these, you can control various aspects of the component's behavior.

Below is a list of customizations along with corresponding code snippets:

| Props            | Description                                                                                                                                      | Code                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| user             | Sets the user whose chat histories with the AI assistant need to be fetched. This is a required property for the component to function properly. | `user={userObject}`                             |
| group            | Sets the group whose chat histories with the AI assistant need to be fetched. Can be used instead of user for group chats.                       | `group={groupObject}`                           |
| LoadingStateView | Custom loading state view component to be displayed while fetching chat history                                                                  | `LoadingStateView={() => <YourCustomLoader />}` |

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="message" href="/ui-kit/react-native/message-list">
    Display the list of messages in a conversation
  </Card>

  <Card title="AI Features" icon="robot" href="/ui-kit/react-native/core-features">
    Overview of all AI-powered features
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/react-native/conversations">
    Display and manage the list of recent chats
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>


# Smart Chat Features
Source: https://www.cometchat.com/docs/ui-kit/react-native/ai-features

Integrate AI-powered conversation starters, smart replies, and conversation summaries into your React Native chat app.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                                                                                |
  | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package        | `@cometchat/chat-uikit-react-native`                                                                                                                                                                                 |
  | Required setup | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")` + AI features enabled in [CometChat Dashboard](/docs/fundamentals/ai-user-copilot/overview)                                                       |
  | AI features    | Conversation Starter, Smart Replies, Conversation Summary                                                                                                                                                            |
  | Key components | `CometChatMessageList` (Conversation Starter, Smart Replies), `CometChatMessageHeader` + `CometChatConversationSummary` (Conversation Summary)                                                                       |
  | Activation     | Enable each AI feature from the CometChat Dashboard, then pass the corresponding prop(s) to the component — Conversation Summary also needs `onConversationSummaryPress` and your own `CometChatConversationSummary` |
</Accordion>

CometChat AI features enhance user interaction and engagement in your application. Here's how the React Native UI Kit integrates these features.

<Frame>
  <img />
</Frame>

## Conversation Starter

When a user initiates a new chat, the UI kit displays a list of suggested opening lines that users can select, making it easier for them to start a conversation. These suggestions are powered by CometChat's AI, which predicts contextually relevant conversation starter options.

For a comprehensive understanding and guide on implementing and using the Conversation Starter, refer to our specific guide on the [Conversation Starter](/docs/fundamentals/ai-user-copilot/conversation-starter).

Once you have successfully activated the [Conversation Starter](/docs/fundamentals/ai-user-copilot/conversation-starter) from your CometChat Dashboard, pass `showConversationStarters` to the [MessageList](/docs/ui-kit/react-native/message-list) component to display the starters in an empty chat.

```tsx theme={null}
<CometChatMessageList
  user={user}
  showConversationStarters={true}
/>
```

<Frame>
  <img />
</Frame>

## Smart Replies

Smart Replies are AI-generated responses to messages. They predict what a user might want to say next by analyzing the context of the conversation, allowing for quicker and more convenient responses on mobile devices.

For a comprehensive understanding and guide on implementing and using Smart Replies, refer to our specific guide on the [Smart Replies](/docs/fundamentals/ai-user-copilot/smart-replies).

Once you have successfully activated the [Smart Replies](/docs/fundamentals/ai-user-copilot/smart-replies) from your CometChat Dashboard, pass `showSmartReplies` to the [MessageList](/docs/ui-kit/react-native/message-list) component. Smart reply chips appear above the composer after a message is received.

```tsx theme={null}
<CometChatMessageList
  user={user}
  showSmartReplies={true}
/>
```

<Frame>
  <img />
</Frame>

## Conversation Summary

The Conversation Summary feature provides concise summaries of long conversations, allowing users to catch up quickly on missed chats. This feature uses natural language processing to determine the main points in a conversation.

For a comprehensive understanding and guide on implementing and using the Conversation Summary, refer to our specific guide on the [Conversation Summary](/docs/fundamentals/ai-user-copilot/conversation-summary).

Once you have successfully activated the [Conversation Summary](/docs/fundamentals/ai-user-copilot/conversation-summary) from your CometChat Dashboard, wire it up in two parts:

1. Pass **both** `showConversationSummaryButton` and `onConversationSummaryPress` to the [MessageHeader](/docs/ui-kit/react-native/message-header). The summary item is added to the header's overflow menu (⋮) only when both props are present — the boolean on its own does nothing.
2. Render `CometChatConversationSummary` yourself and toggle it from that callback. The header does not ship a built-in summary panel; it only invokes your handler.

```tsx theme={null}
import { useState } from 'react';
import { CometChat } from '@cometchat/chat-sdk-react-native';
import { CometChatMessageHeader, CometChatConversationSummary } from '@cometchat/chat-uikit-react-native';

const [showSummaryPanel, setShowSummaryPanel] = useState(false);

const fetchConversationSummary = () =>
  CometChat.getConversationSummary(receiverId, receiverType, { lastNMessages: 1000 });

<CometChatMessageHeader
  user={user}
  showConversationSummaryButton={true}
  onConversationSummaryPress={() => setShowSummaryPanel((prev) => !prev)}
/>

{showSummaryPanel && (
  <CometChatConversationSummary getConversationSummary={fetchConversationSummary} />
)}
```

Place `CometChatConversationSummary` between the message list and the composer so the panel appears above the composer.

<Frame>
  <img />
</Frame>


# Apple Privacy Manifest
Source: https://www.cometchat.com/docs/ui-kit/react-native/apple-privacy-manifest-guide

Configure the required Apple Privacy Manifest for CometChat React Native UI Kit to comply with App Store requirements.

<Accordion title="AI Integration Quick Reference">
  | Field         | Value                                                                                                                                                                                                              |
  | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Package       | `@cometchat/chat-uikit-react-native`                                                                                                                                                                               |
  | File location | `ios/YourApp/PrivacyInfo.xcprivacy`                                                                                                                                                                                |
  | Required APIs | `NSPrivacyAccessedAPICategoryFileTimestamp` (C617.1), `NSPrivacyAccessedAPICategoryUserDefaults` (CA92.1), `NSPrivacyAccessedAPICategorySystemBootTime` (35F9.1), `NSPrivacyAccessedAPICategoryDiskSpace` (E174.1) |
  | Purpose       | Configure required Apple Privacy Manifest for App Store compliance                                                                                                                                                 |
  | Related       | [Getting Started](/docs/ui-kit/react-native/react-native-cli-integration) · [Expo Integration](/docs/ui-kit/react-native/expo-integration) · [All Guides](/docs/ui-kit/react-native/guide-overview)                               |
</Accordion>

## Overview

The Apple Privacy Manifest enhances privacy and transparency for apps on Apple's platforms. As part of Apple's commitment to user privacy and data security, they introduced the "App Privacy Details" section — a privacy label for each app.

The privacy manifest is a property list that records:

* The types of data collected by an app or third-party SDK
* The required reasons APIs an app or third-party SDK uses

For each type of data an app or third-party SDK collects and category of required reasons API it uses, the app or SDK needs to record the reasons in its bundled privacy manifest file.

***

## React Native UI Kit Privacy Requirements

If you are using the React Native UI Kit, you need to add the following entries to your Privacy Manifest file.

### Dependencies Requiring Privacy Declarations

1. **React Native Framework**

   React Native uses several APIs that require privacy declarations. See the React Native community [discussion](https://github.com/react-native-community/discussions-and-proposals/discussions/776) for more details.

2. **SPTPersistentCache**

   The React Native UI Kit uses a native module (a fork of react-native-video) that has an internal dependency on SPTPersistentCache. This library uses one of the APIs listed by Apple.

***

## Privacy Manifest File

Below is the complete Privacy Manifest that should be included in your application:

<Tabs>
  <Tab title="PrivacyInfo.xcprivacy">
    ```xml theme={null}
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
        <key>NSPrivacyAccessedAPITypes</key>
        <array>
            <dict>
                <key>NSPrivacyAccessedAPIType</key>
                <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
                <key>NSPrivacyAccessedAPITypeReasons</key>
                <array>
                    <string>C617.1</string>
                </array>
            </dict>
            <dict>
                <key>NSPrivacyAccessedAPIType</key>
                <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
                <key>NSPrivacyAccessedAPITypeReasons</key>
                <array>
                    <string>CA92.1</string>
                </array>
            </dict>
            <dict>
                <key>NSPrivacyAccessedAPIType</key>
                <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
                <key>NSPrivacyAccessedAPITypeReasons</key>
                <array>
                    <string>35F9.1</string>
                </array>
            </dict>
            <dict>
                <key>NSPrivacyAccessedAPIType</key>
                <string>NSPrivacyAccessedAPICategoryDiskSpace</string>
                <key>NSPrivacyAccessedAPITypeReasons</key>
                <array>
                    <string>E174.1</string>
                </array>
            </dict>
        </array>
        <key>NSPrivacyCollectedDataTypes</key>
        <array/>
        <key>NSPrivacyTracking</key>
        <false/>
    </dict>
    </plist>
    ```
  </Tab>
</Tabs>

***

## Creating the Privacy Manifest

<Steps>
  <Step title="Create a new file in Xcode">
    Open Xcode and choose **File > New > File...**

    <Frame>
      <img alt="Xcode File Menu" />
    </Frame>
  </Step>

  <Step title="Select App Privacy file type">
    Scroll down to the **Resource** section, select the **App Privacy** file type, and click **Next**.

    <Frame>
      <img alt="Select App Privacy File Type" />
    </Frame>
  </Step>

  <Step title="Select the target">
    Select your app target, then click **Create**.

    <Frame>
      <img alt="Select Target" />
    </Frame>
  </Step>

  <Step title="Keep the default filename">
    By default, the file is named `PrivacyInfo.xcprivacy`. Do not change this filename.
  </Step>

  <Step title="Replace the file content">
    This creates an empty Privacy Manifest file. Replace the content with the manifest XML provided above.

    <Frame>
      <img alt="Privacy Manifest Content" />
    </Frame>
  </Step>
</Steps>

***

## Next Steps

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/ui-kit/react-native/react-native-cli-integration">
    Complete UI Kit setup guide
  </Card>

  <Card title="Expo Integration" icon="mobile" href="/ui-kit/react-native/expo-integration">
    Configure for Expo development builds
  </Card>

  <Card title="All Guides" icon="book" href="/ui-kit/react-native/guide-overview">
    Browse all feature and formatter guides
  </Card>

  <Card title="Components Overview" icon="grid" href="/ui-kit/react-native/components-overview">
    Explore all available components
  </Card>
</CardGroup>


# Call Buttons
Source: https://www.cometchat.com/docs/ui-kit/react-native/call-buttons

Add voice and video call buttons with CometChatCallButtons component in React Native UI Kit, enabling users to initiate calls directly.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatCallButtons",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatCallButtons } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Voice and video call buttons that initiate calls to users or groups.",
    "props": {
      "data": {
        "user": {
          "type": "CometChat.User",
          "note": "User object for one-on-one calls"
        },
        "group": {
          "type": "CometChat.Group",
          "note": "Group object for group calls"
        }
      },
      "callbacks": {
        "onError": "(error: CometChat.CometChatException) => void"
      },
      "visibility": {
        "hideVoiceCallButton": { "type": "boolean", "default": false },
        "hideVideoCallButton": { "type": "boolean", "default": false }
      },
      "configuration": {
        "callSettingsBuilder": "Callback to configure call settings",
        "outgoingCallConfiguration": "Configuration for outgoing call component"
      }
    },
    "events": [
      {
        "name": "ccCallRejected",
        "payload": "{ call }",
        "description": "Initiated call rejected by receiver"
      },
      {
        "name": "ccCallFailled",
        "payload": "{ call }",
        "description": "Error occurred during initiated call"
      },
      {
        "name": "ccOutgoingCall",
        "payload": "{ call }",
        "description": "User initiates a voice/video call"
      }
    ],
    "compositionExample": {
      "description": "Call buttons for message header",
      "components": [
        "CometChatCallButtons",
        "CometChatOutgoingCall"
      ],
      "flow": "Button press initiates call -> OutgoingCall screen displayed"
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatCallButtons` is a [Component](/docs/ui-kit/react-native/components-overview#components) that provides users with the ability to make calls, access call-related functionalities, and control call settings. Clicking this button typically triggers the call to be placed to the desired recipient.

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { CometChatCallButtons } from "@cometchat/chat-uikit-react-native";

function CallButtonsDemo() {
  return <CometChatCallButtons group={group} />;
}
```

***

## Actions and Events

### Callback Props

#### onError

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

```tsx lines theme={null}
onError?: (e: CometChat.CometChatException) => void
```

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react-native";

function CallButtonsWithError() {
  const handleError = (e: CometChat.CometChatException) => {
    console.error("CallButtons error:", e);
  };

  return <CometChatCallButtons user={user} onError={handleError} />;
}
```

### Global UI Events

`CometChatUIEventHandler` emits events subscribable from anywhere in the application. Add listeners and remove them on cleanup.

| Event            | Fires when                                 | Payload    |
| ---------------- | ------------------------------------------ | ---------- |
| `ccCallRejected` | Initiated call is rejected by the receiver | `{ call }` |
| `ccCallFailled`  | Error occurs during the initiated call     | `{ call }` |
| `ccOutgoingCall` | User initiates a voice/video call          | `{ call }` |

When to use: sync external UI with call state changes. For example, update a call status indicator, show notifications, or log call events.

```tsx lines theme={null}
import { useEffect } from "react";
import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";

function useCallEvents() {
  useEffect(() => {
    const listenerId = "CALL_EVENTS_" + Date.now();

    CometChatUIEventHandler.addCallListener(listenerId, {
      ccCallRejected: ({ call }) => {
        console.log("Call rejected:", call);
      },
      ccOutgoingCall: ({ call }) => {
        console.log("Outgoing call:", call);
      },
      ccCallFailled: ({ call }) => {
        console.log("Call failed:", call);
      },
    });

    return () => {
      CometChatUIEventHandler.removeCallListener(listenerId);
    };
  }, []);
}
```

***

## 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 `CometChatCallButtons` component.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import {
  CometChatCallButtons,
  useTheme,
} from "@cometchat/chat-uikit-react-native";

function StylingDemo() {
  const theme = useTheme();

  return (
    <CometChatCallButtons
      group={group}
      style={{
        audioCallButtonIconStyle: {
          tintColor: theme.color.primary,
        },
        audioCallButtonIconContainerStyle: {
          backgroundColor: theme.color.extendedPrimary100,
          paddingHorizontal: theme.spacing.padding.p4,
          paddingVertical: theme.spacing.padding.p2,
          borderRadius: 8,
        },
        videoCallButtonIconStyle: {
          tintColor: theme.color.primary,
        },
        videoCallButtonIconContainerStyle: {
          backgroundColor: theme.color.extendedPrimary100,
          paddingHorizontal: theme.spacing.padding.p4,
          paddingVertical: theme.spacing.padding.p2,
          borderRadius: 8,
        },
      }}
    />
  );
}
```

### Visibility Props

| Property              | Description                                | Code                            |
| --------------------- | ------------------------------------------ | ------------------------------- |
| `hideVoiceCallButton` | Toggle visibility of the voice call button | `hideVoiceCallButton?: boolean` |
| `hideVideoCallButton` | Toggle visibility of the video call button | `hideVideoCallButton?: boolean` |

### Outgoing Call Configuration

You can customize the properties of the Outgoing Call component by making use of the `outgoingCallConfiguration` prop:

```tsx lines theme={null}
import {
  CometChatCallButtons,
  OutgoingCallConfiguration,
} from "@cometchat/chat-uikit-react-native";

function OutgoingCallConfigDemo() {
  const getOutgoingCallConfig = () => {
    return new OutgoingCallConfiguration({
      disableSoundForCalls: true,
    });
  };

  return (
    <CometChatCallButtons
      user={user}
      outgoingCallConfiguration={getOutgoingCallConfig()}
    />
  );
}
```

All exposed properties of `OutgoingCallConfiguration` can be found under [Outgoing Call](/docs/ui-kit/react-native/outgoing-call).

***

## Next Steps

<CardGroup>
  <Card title="Incoming Call" icon="phone-arrow-down-left" href="/ui-kit/react-native/incoming-call">
    Display and handle incoming calls
  </Card>

  <Card title="Outgoing Call" icon="phone-arrow-up-right" href="/ui-kit/react-native/outgoing-call">
    Display and manage outgoing calls
  </Card>

  <Card title="Call Logs" icon="clock-rotate-left" href="/ui-kit/react-native/call-logs">
    View call history and logs
  </Card>

  <Card title="Call Features" icon="video" href="/ui-kit/react-native/call-features">
    Overview of all calling features
  </Card>
</CardGroup>


# Call
Source: https://www.cometchat.com/docs/ui-kit/react-native/call-features

Integrate one-on-one and group audio/video calling into your React Native app using CometChat's Calls SDK and prebuilt UI components.

<Info>
  **Quick Reference for AI Agents & Developers**

  ```bash theme={null}
  # Install the Calls SDK (required for calling features)
  npm install @cometchat/calls-sdk-react-native
  ```

  ```tsx theme={null}
  import { CometChat } from "@cometchat/chat-sdk-react-native";
  import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";

  // Register a call listener to handle incoming calls
  CometChat.addCallListener(
    "call-listener-id",
    new CometChat.CallListener({
      onIncomingCallReceived: (call: CometChat.Call) => {
        console.log("Incoming call:", call);
      },
    })
  );
  ```

  * **Incoming Call** → [CometChatIncomingCall](/docs/ui-kit/react-native/incoming-call)
  * **Outgoing Call** → [CometChatOutgoingCall](/docs/ui-kit/react-native/outgoing-call)
  * **Call Buttons** → [CometChatCallButtons](/docs/ui-kit/react-native/call-buttons)
  * **Call Logs** → [CometChatCallLogs](/docs/ui-kit/react-native/call-logs)
</Info>

CometChat's Calls feature offers advanced functionality for seamlessly integrating one-on-one and group audio/video calling into your application. This document provides a technical overview of how these features are implemented using the React Native UI Kit.

<Note>
  **Calling features** require installing `@cometchat/calls-sdk-react-native` separately. The UI Kit auto-detects it and enables call UI components.
</Note>

## Integration

First, make sure that you've correctly integrated the UI Kit library into your project. If you haven't done this yet or are facing difficulties, refer to the [Getting Started](/docs/ui-kit/react-native/react-native-cli-integration) guide.

Once you've successfully integrated the UI Kit, the next step is to add the CometChat Calls SDK to your project. This is necessary to enable the calling features in the UI Kit:

<Tabs>
  <Tab title="Bash">
    ```sh theme={null}
    npm install @cometchat/calls-sdk-react-native
    ```
  </Tab>
</Tabs>

Once the dependency is added, the React Native UI Kit will automatically detect it and enable calling features. Your application will now support both audio and video calls, and the [CallButtons](/docs/ui-kit/react-native/call-buttons) component will appear within the [MessageHeader](/docs/ui-kit/react-native/message-header) component.

<Frame>
  <img />
</Frame>

## Add Necessary Permissions

### Android

Open `AndroidManifest.xml` located at `android/app/src/main` in your React Native project and add the following permissions:

<Tabs>
  <Tab title="AndroidManifest.xml">
    ```xml theme={null}
    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        package="com.org.name_of_your_app" >

        <uses-permission android:name="android.permission.INTERNET" />
        <uses-permission android:name="android.permission.CAMERA" />
        <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
        <uses-permission android:name="android.permission.RECORD_AUDIO" />
        <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

        <application>
            <activity>
            </activity>
            <meta-data />
        </application>
    </manifest>
    ```
  </Tab>
</Tabs>

### iOS

Open `Info.plist` located at `ios/{appname}` in your React Native project and add the following entries:

<Tabs>
  <Tab title="info.plist">
    ```xml theme={null}
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
      <dict>
        <key>NSCameraUsageDescription</key>
        <string>Access camera</string>
        <key>NSMicrophoneUsageDescription</key>
        <string>Access Microphone</string>
      </dict>
    </plist>
    ```
  </Tab>
</Tabs>

## Setup Minimum Android and iOS Versions

For Android, open the app-level `build.gradle` and set `minSdkVersion` to 24, and both `targetSdkVersion` and `compileSdkVersion` to 33.

<Tabs>
  <Tab title="Gradle">
    ```gradle theme={null}
    android {
        namespace "com.org.name_of_your_app"

        compileSdkVersion 33

        defaultConfig {

            minSdkVersion 24

            targetSdkVersion 33

        }

    }
    ```
  </Tab>
</Tabs>

For iOS, open the `.xcworkspace` in Xcode and set `IPHONEOS_DEPLOYMENT_TARGET` to 12.0.

Alternatively, you can specify it in the `post_install` hook of the Podfile:

<Tabs>
  <Tab title="Podfile">
    ```ruby theme={null}
    post_install do |installer|
      installer.pods_project.targets.each do |target|
        target.build_configurations.each do |build_configuration|
          build_configuration.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
          build_configuration.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64 i386'
          build_configuration.build_settings['ENABLE_BITCODE'] = 'NO'
        end
      end
    end
    ```
  </Tab>
</Tabs>

<Warning>
  **Apple Silicon (M1/M2/M3) users:** Excluding `arm64` from the simulator build prevents the app from running natively on Apple Silicon Macs. If you are developing on an Apple Silicon Mac, consider excluding only `i386` instead of `arm64 i386` to enable native simulator builds.
</Warning>

## Add the Call Listeners

In addition to CallButtons, the Calls UI Kit offers fully functional UI components for handling Incoming, Outgoing, and Ongoing calls. To receive call events in your desired component or screen, you must register a call listener using the `addCallListener()` method. The `onIncomingCallReceived()` event is triggered whenever an incoming call is received.

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import React, { useEffect, useRef, useState } from "react";
    import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatIncomingCall, CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";

    // Track whether the user is logged in
    const [loggedIn, setLoggedIn] = useState(false);
    // Track if there is an incoming call to display
    const [callReceived, setCallReceived] = useState(false);
    // Store the incoming call object for use in the UI
    const incomingCall = useRef<CometChat.Call | CometChat.CustomMessage | null>(
      null
    );
    // Unique ID for registering and removing the call listener
    var listenerID: string = "UNIQUE_LISTENER_ID";

    const App = (): React.ReactElement => {
      useEffect(() => {
        // Register the call listener when the component mounts or when login state changes
        CometChat.addCallListener(
          listenerID,
          new CometChat.CallListener({
            // Fired when an incoming call is received
            onIncomingCallReceived: (call: CometChat.Call) => {
              // Store the incoming call and update state.
              incomingCall.current = call;
              // Trigger UI to show incoming call screen
              setCallReceived(true);
            },
            // Fired when an outgoing call is rejected by the recipient
            onOutgoingCallRejected: () => {
              // Clear the call state if outgoing call is rejected.
              incomingCall.current = null; // Clear the call object
              setCallReceived(false); // Hide any call UI
            },
            onIncomingCallCancelled: () => {
              // Clear the call state if the incoming call is cancelled.
              incomingCall.current = null;
              setCallReceived(false);
            },
          })
        );

        // Register UI Kit-level call listener to handle call end events
        CometChatUIEventHandler.addCallListener(listenerID, {
          ccCallEnded: () => {
            incomingCall.current = null;
            setCallReceived(false);
          },
        });

        // Cleanup: remove both listeners when the component unmounts or before re-running
        return () => {
          CometChat.removeCallListener(listenerID);
          CometChatUIEventHandler.removeCallListener(listenerID);
        };
      }, [loggedIn]); // Re-run effect if the login state changes

      return (
        <SafeAreaProvider>
        <SafeAreaView style={{ flex: 1 }}>
          {/* Render the incoming call UI when logged in and a call has been received */}
          {loggedIn && callReceived && incomingCall.current ? (
            <CometChatIncomingCall
              call={incomingCall.current}
              onDecline={() => {
                // Handle call decline by clearing the incoming call state.
                incomingCall.current = null; // Clear the call object
                setCallReceived(false); // Hide the incoming call UI
              }}
            />
          ) : null}
        </SafeAreaView>
        </SafeAreaProvider>
      );
    };
    ```
  </Tab>
</Tabs>

## Features

### Incoming Call

The [Incoming Call](/docs/ui-kit/react-native/incoming-call) component of the CometChat UI Kit provides the functionality that lets users receive real-time audio and video calls in the app.

When a call is made to a user, the Incoming Call component triggers and displays a call screen. This call screen typically displays the caller information and provides the user with options to either accept or reject the incoming call.

<Frame>
  <img />
</Frame>

### Outgoing Call

The [Outgoing Call](/docs/ui-kit/react-native/outgoing-call) component of the CometChat UI Kit is designed to manage the outgoing call process within your application. When a user initiates an audio or video call to another user or group, this component displays an outgoing call screen, showcasing information about the recipient and the call status.

The Outgoing Call component automatically transitions into the ongoing call screen once the receiver accepts the call. This ensures a smooth flow from initiating the call to engaging in a conversation, without any additional steps required from the user.

<Frame>
  <img />
</Frame>

### Call Logs

The [Call Logs](/docs/ui-kit/react-native/call-logs) component provides records of call events such as who called whom, the time of the call, and the duration. This information can be fetched from the CometChat server and displayed in a structured format for users to view their past call activities.

<Frame>
  <img />
</Frame>

***

## Next Steps

<CardGroup>
  <Card title="Incoming Call" icon="phone-arrow-down-left" href="/ui-kit/react-native/incoming-call">
    Handle incoming audio and video calls
  </Card>

  <Card title="Outgoing Call" icon="phone-arrow-up-right" href="/ui-kit/react-native/outgoing-call">
    Manage outgoing call screens and transitions
  </Card>

  <Card title="Call Buttons" icon="phone" href="/ui-kit/react-native/call-buttons">
    Add call action buttons to your chat header
  </Card>

  <Card title="Call Logs" icon="clock-rotate-left" href="/ui-kit/react-native/call-logs">
    Display call history and past call activities
  </Card>
</CardGroup>


# Call Logs
Source: https://www.cometchat.com/docs/ui-kit/react-native/call-logs

Display and manage the list of call history with CometChatCallLogs component in React Native UI Kit, including missed, received, and outgoing calls.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatCallLogs",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatCallLogs } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Scrollable list of call history showing missed, received, and outgoing calls.",
    "props": {
      "data": {
        "callLogRequestBuilder": {
          "type": "CallLogRequestBuilder",
          "note": "Pass the builder, not the result of .build()"
        },
        "datePattern": {
          "type": "DatePattern",
          "note": "Custom date format for call timestamps"
        }
      },
      "callbacks": {
        "onItemPress": "(call: any) => void",
        "onItemLongPress": "(prop: { call: any }) => void",
        "onCallIconPress": "(item: any) => void",
        "onBack": "() => void",
        "onError": "(error: CometChat.CometChatException) => void",
        "onLoad": "(list: any[]) => void",
        "onEmpty": "() => void"
      },
      "visibility": {
        "showBackButton": { "type": "boolean", "default": true },
        "hideError": { "type": "boolean", "default": false },
        "hideHeader": { "type": "boolean", "default": false },
        "hideLoadingState": { "type": "boolean", "default": false }
      },
      "viewSlots": {
        "ItemView": "(call: any) => JSX.Element",
        "LeadingView": "(call: any) => JSX.Element",
        "TitleView": "(call: any) => JSX.Element",
        "SubtitleView": "(call: any) => JSX.Element",
        "TrailingView": "(call: any, defaultOnPress?: (call: any) => void) => JSX.Element",
        "LoadingView": "() => JSX.Element",
        "EmptyView": "() => JSX.Element",
        "ErrorView": "(e: CometChat.CometChatException) => JSX.Element",
        "AppBarOptions": "() => JSX.Element"
      }
    },
    "compositionExample": {
      "description": "Call history list with call-back functionality",
      "components": [
        "CometChatCallLogs",
        "CometChatOutgoingCall"
      ],
      "flow": "onItemPress initiates call to participant, onCallIconPress triggers call-back"
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatCallLogs` is a [Component](/docs/ui-kit/react-native/components-overview#components) that shows the list of Call Logs available. By default, names are shown for all listed users, along with their avatars if available.

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

function CallLogsDemo() {
  return <CometChatCallLogs />;
}
```

***

## Filtering Call Logs

Pass a `CallLogRequestBuilder` to `callLogRequestBuilder`. Pass the builder instance — not the result of `.build()`.

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";
import { CallLogRequestBuilder } from "@cometchat/chat-sdk-react-native";

function FilteredCallLogs() {
  const callLogRequestBuilder = new CallLogRequestBuilder()
    .setLimit(20)
    .setCallStatus("cancelled")
    .setAuthToken(loggedInUser.getAuthToken());

  return (
    <CometChatCallLogs
      callLogRequestBuilder={callLogRequestBuilder}
    />
  );
}
```

### Filter Recipes

| Recipe                | Code                                                       |
| --------------------- | ---------------------------------------------------------- |
| Limit to 20 per page  | `new CallLogRequestBuilder().setLimit(20)`                 |
| Only cancelled calls  | `new CallLogRequestBuilder().setCallStatus("cancelled")`   |
| Only incoming calls   | `new CallLogRequestBuilder().setCallDirection("incoming")` |
| Only outgoing calls   | `new CallLogRequestBuilder().setCallDirection("outgoing")` |
| Calls with recordings | `new CallLogRequestBuilder().setHasRecording(true)`        |
| Filter by user UID    | `new CallLogRequestBuilder().setUid("user_uid")`           |

***

## Actions and Events

### Callback Props

#### onItemPress

Fires when a call log row is tapped. By default initiates a call to the participant.

```tsx lines theme={null}
onItemPress?: (call: any) => void
```

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

function CallLogsWithPress() {
  const handleItemPress = (call: any) => {
    console.log("Selected call:", call);
  };

  return <CometChatCallLogs onItemPress={handleItemPress} />;
}
```

#### onItemLongPress

Fires when a call log item is long-pressed, allowing additional actions like delete or select.

```tsx lines theme={null}
onItemLongPress?: (prop: { call: any }) => void
```

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

function CallLogsWithLongPress() {
  const handleLongPress = (prop: { call: any }) => {
    console.log("Long pressed:", prop.call);
  };

  return <CometChatCallLogs onItemLongPress={handleLongPress} />;
}
```

#### onCallIconPress

Fires when the call icon is pressed.

```tsx lines theme={null}
onCallIconPress?: (item: any) => void
```

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

function CallLogsWithCallIcon() {
  const handleCallIconPress = (call: any) => {
    console.log("Call icon pressed:", call);
  };

  return <CometChatCallLogs onCallIconPress={handleCallIconPress} />;
}
```

#### onBack

Fires when the back button in the app bar is pressed.

```tsx lines theme={null}
onBack?: () => void
```

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

function CallLogsWithBack() {
  return (
    <CometChatCallLogs
      showBackButton={true}
      onBack={() => {
        console.log("Back pressed");
      }}
    />
  );
}
```

#### onError

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

```tsx lines theme={null}
onError?: (e: CometChat.CometChatException) => void
```

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function CallLogsWithError() {
  return (
    <CometChatCallLogs
      onError={(error: CometChat.CometChatException) => {
        console.error("CallLogs error:", error);
      }}
    />
  );
}
```

#### onLoad

Fires when the list is successfully fetched and loaded.

```tsx lines theme={null}
onLoad?: (list: any[]) => void
```

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

function CallLogsWithLoad() {
  const handleLoad = (list: any[]) => {
    console.log("Call logs loaded:", list.length);
  };

  return <CometChatCallLogs onLoad={handleLoad} />;
}
```

#### onEmpty

Fires when the call log list is empty.

```tsx lines theme={null}
onEmpty?: () => void
```

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

function CallLogsWithEmpty() {
  return (
    <CometChatCallLogs
      onEmpty={() => {
        console.log("No call logs available");
      }}
    />
  );
}
```

***

## Custom View Slots

Each slot replaces a section of the default UI. Slots that accept a call parameter receive the call log object for that row.

| Slot            | Signature                                          | Replaces                 |
| --------------- | -------------------------------------------------- | ------------------------ |
| `ItemView`      | `(call: any) => JSX.Element`                       | Entire list item row     |
| `LeadingView`   | `(call: any) => JSX.Element`                       | Avatar / left section    |
| `TitleView`     | `(call: any) => JSX.Element`                       | Caller name / title text |
| `SubtitleView`  | `(call: any) => JSX.Element`                       | Call type / details      |
| `TrailingView`  | `(call: any, defaultOnPress?) => JSX.Element`      | Duration / right section |
| `LoadingView`   | `() => JSX.Element`                                | Loading spinner          |
| `EmptyView`     | `() => JSX.Element`                                | Empty state              |
| `ErrorView`     | `(e: CometChat.CometChatException) => JSX.Element` | Error state              |
| `AppBarOptions` | `() => JSX.Element`                                | Header bar options       |

### LoadingView

Custom view displayed when data is being fetched.

```tsx lines theme={null}
LoadingView?: () => JSX.Element
```

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";
import { Text } from "react-native";

function LoadingViewDemo() {
  const getLoadingView = (): JSX.Element => {
    return <Text>Loading call logs...</Text>;
  };

  return <CometChatCallLogs LoadingView={getLoadingView} />;
}
```

### EmptyView

Custom view displayed when there are no call logs.

```tsx lines theme={null}
EmptyView?: () => JSX.Element
```

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";
import { Text } from "react-native";

function EmptyViewDemo() {
  const getEmptyView = (): JSX.Element => {
    return <Text>No calls yet. Make your first call!</Text>;
  };

  return <CometChatCallLogs EmptyView={getEmptyView} />;
}
```

### ErrorView

Custom view displayed when an error occurs.

```tsx lines theme={null}
ErrorView?: (e: CometChat.CometChatException) => JSX.Element
```

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { Text } from "react-native";

function ErrorViewDemo() {
  const getErrorView = (e: CometChat.CometChatException): JSX.Element => {
    return <Text>Error loading calls. Please try again.</Text>;
  };

  return <CometChatCallLogs ErrorView={getErrorView} />;
}
```

### ItemView

Custom view for the entire list item row.

```tsx lines theme={null}
ItemView?: (call: any) => JSX.Element
```

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";
import { View, Text } from "react-native";

function ItemViewDemo() {
  const getItemView = (call: any): JSX.Element => {
    return (
      <View style={{ padding: 16, flexDirection: 'row' }}>
        <Text style={{ flex: 1 }}>{call.getInitiator().getName()}</Text>
        <Text>{call.getStatus()}</Text>
      </View>
    );
  };

  return <CometChatCallLogs ItemView={getItemView} />;
}
```

### SubtitleView

Custom view for the call type / details.

```tsx lines theme={null}
SubtitleView?: (call: any) => JSX.Element
```

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";
import { Text } from "react-native";

function SubtitleViewDemo() {
  const getSubtitleView = (call: any): JSX.Element => {
    return (
      <Text style={{ color: '#727272', fontSize: 12 }}>
        {call.getStatus()} • {call.getDuration()}s
      </Text>
    );
  };

  return <CometChatCallLogs SubtitleView={getSubtitleView} />;
}
```

### TrailingView

Custom view for the duration / right section.

```tsx lines theme={null}
TrailingView?: (call: any, defaultOnPress?: (call: any) => void) => JSX.Element
```

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";
import { TouchableOpacity, Text } from "react-native";

function TrailingViewDemo() {
  const getTrailingView = (call: any, defaultOnPress?: (call: any) => void): JSX.Element => {
    return (
      <TouchableOpacity onPress={() => defaultOnPress?.(call)}>
        <Text>📞 Call Back</Text>
      </TouchableOpacity>
    );
  };

  return <CometChatCallLogs TrailingView={getTrailingView} />;
}
```

### AppBarOptions

Custom view for the header bar options.

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";
import { TouchableOpacity, Image } from "react-native";

function AppBarOptionsDemo() {
  return (
    <CometChatCallLogs
      AppBarOptions={() => {
        return (
          <TouchableOpacity onPress={() => console.log("Filter pressed")}>
            <Image source={FilterIcon} style={{ width: 24, height: 24 }} />
          </TouchableOpacity>
        );
      }}
    />
  );
}
```

***

## 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 `CometChatCallLogs` component.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

function StylingDemo() {
  return (
    <CometChatCallLogs
      hideBackButton={true}
      style={{
        titleSeparatorStyle: {
          borderBottomColor: "#F76808",
        },
        titleTextStyle: {
          color: "#F76808",
        },
        itemStyle: {
          avatarStyle: {
            containerStyle: {
              borderRadius: 8,
              backgroundColor: "#FBAA75",
            },
            imageStyle: {
              borderRadius: 8,
            },
          },
        },
      }}
    />
  );
}
```

### Visibility Props

| Property           | Description                                         | Code                         |
| ------------------ | --------------------------------------------------- | ---------------------------- |
| `showBackButton`   | Toggle visibility of the back button in the app bar | `showBackButton?: boolean`   |
| `hideError`        | Hide error state on fetching call logs              | `hideError?: boolean`        |
| `hideHeader`       | Toggle visibility for the toolbar/header bar        | `hideHeader?: boolean`       |
| `hideLoadingState` | Toggle visibility of loading state                  | `hideLoadingState?: boolean` |

### Outgoing Call Configuration

You can customize the properties of the OutGoing Call by making use of the `outgoingCallConfiguration` prop:

```tsx lines theme={null}
import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";
import { Text } from "react-native";

function OutgoingCallConfigDemo() {
  return (
    <CometChatCallLogs
      outgoingCallConfiguration={{
        SubtitleView: () => {
          return <Text style={{ color: '#FFC0CB' }}>Outgoing Call</Text>;
        },
        style: {
          containerStyle: {
            backgroundColor: '#FFE4EBF5',
          },
        },
      }}
    />
  );
}
```

***

## Next Steps

<CardGroup>
  <Card title="Incoming Call" icon="phone-arrow-down-left" href="/ui-kit/react-native/incoming-call">
    Display and handle incoming calls
  </Card>

  <Card title="Outgoing Call" icon="phone-arrow-up-right" href="/ui-kit/react-native/outgoing-call">
    Display and manage outgoing calls
  </Card>

  <Card title="Call Buttons" icon="phone" href="/ui-kit/react-native/call-buttons">
    Add voice and video call buttons to your UI
  </Card>

  <Card title="Call Features" icon="video" href="/ui-kit/react-native/call-features">
    Overview of all calling features
  </Card>
</CardGroup>


# Calling Integration
Source: https://www.cometchat.com/docs/ui-kit/react-native/calling-integration

Add voice and video calling to your React Native UI Kit application

## Overview

This guide walks you through adding voice and video calling capabilities to your React Native application using the CometChat UI Kit.

<Info>
  Make sure you've completed the [Getting Started](/docs/ui-kit/react-native/react-native-cli-integration) guide before proceeding.
</Info>

## Add the Calls SDK

Install the CometChat Calls SDK:

```bash theme={null}
npm install @cometchat/calls-sdk-react-native
```

Once added, the React Native UI Kit will automatically detect it and enable calling features. The [CallButtons](/docs/ui-kit/react-native/call-buttons) component will appear within the [MessageHeader](/docs/ui-kit/react-native/message-header) component.

<Tabs>
  <Tab title="iOS">
    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="Android">
    <Frame>
      <img />
    </Frame>
  </Tab>
</Tabs>

## Add Permissions

### Android

Add the following permissions to `android/app/src/main/AndroidManifest.xml`:

```xml theme={null}
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.org.name_of_your_app">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <application>
        <!-- ... -->
    </application>
</manifest>
```

### iOS

Add the following entries to `ios/{appname}/Info.plist`:

```xml theme={null}
<key>NSCameraUsageDescription</key>
<string>Access camera</string>
<key>NSMicrophoneUsageDescription</key>
<string>Access Microphone</string>
```

## Set Up Minimum Versions

### Android

In `android/app/build.gradle`, set the SDK versions:

```groovy theme={null}
android {
    compileSdkVersion 33

    defaultConfig {
        minSdkVersion 24
        targetSdkVersion 33
    }
}
```

### iOS

In Xcode, set `IPHONEOS_DEPLOYMENT_TARGET` to 12.0, or add to your Podfile:

```ruby theme={null}
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |build_configuration|
      build_configuration.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
      build_configuration.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64 i386'
      build_configuration.build_settings['ENABLE_BITCODE'] = 'NO'
    end
  end
end
```

<Warning>
  **Apple Silicon (M1/M2/M3) users:** Excluding `arm64` from the simulator build prevents the app from running natively on Apple Silicon Macs. If you are developing on an Apple Silicon Mac, consider excluding only `i386` instead of `arm64 i386` to enable native simulator builds.
</Warning>

## Set Up Call Listeners

Register a call listener to receive call events in your component:

```tsx theme={null}
import React, { useEffect, useRef, useState } from "react";
import { SafeAreaView } from "react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";

const App = (): React.ReactElement => {
  const [loggedIn, setLoggedIn] = useState(false);
  const [callReceived, setCallReceived] = useState(false);
  const incomingCall = useRef<CometChat.Call | null>(null);
  const listenerID = "UNIQUE_LISTENER_ID";

  useEffect(() => {
    CometChat.addCallListener(
      listenerID,
      new CometChat.CallListener({
        onIncomingCallReceived: (call: CometChat.Call) => {
          incomingCall.current = call;
          setCallReceived(true);
        },
        onOutgoingCallRejected: () => {
          incomingCall.current = null;
          setCallReceived(false);
        },
        onIncomingCallCancelled: () => {
          incomingCall.current = null;
          setCallReceived(false);
        },
      })
    );

    return () => {
      CometChat.removeCallListener(listenerID);
    };
  }, [loggedIn]);

  return (
    <SafeAreaView style={{ flex: 1 }}>
      {loggedIn && callReceived && incomingCall.current ? (
        <CometChatIncomingCall
          call={incomingCall.current}
          onDecline={() => {
            incomingCall.current = null;
            setCallReceived(false);
          }}
        />
      ) : null}
    </SafeAreaView>
  );
};
```


# Campaigns
Source: https://www.cometchat.com/docs/ui-kit/react-native/campaigns

Deliver targeted, rich notifications to users via an in-app notification feed powered by the CometChat Cards renderer.

CometChat Campaigns enables you to send rich, interactive notifications to users through an in-app notification feed. Each notification is rendered as a native card using the **CometChat Cards** library — supporting images, text, buttons, layouts, and interactive actions.

<Tip>
  **Design cards visually with [Card Builder](/docs/card-builder/overview).** Build your card layouts in the CometChat Dashboard and export the Card Schema JSON these notifications render — instead of writing it by hand.
</Tip>

<Note>
  Before proceeding, ensure you have completed the [UI Kit integration](/docs/ui-kit/react-native/react-native-cli-integration) and the [Dashboard Setup](/docs/campaigns#setup-flow) for Campaigns.
</Note>

<Frame>
  <img />
</Frame>

***

## Overview

Campaigns delivers notifications as **Card Schema JSON** — a structured format that defines the visual layout of each notification card. The system consists of three layers:

1. **CometChat Chat SDK** — Fetches feed items, manages read/delivered state, provides real-time listeners, handles push notification tracking
2. **CometChat Cards Library** — Renders Card Schema JSON into native React Native views
3. **CometChat UI Kit** — Provides the ready-to-use `CometChatNotificationFeed` component that wires everything together

### Architecture Flow

```
Dashboard / API → Campaign Created → Push + WebSocket Delivery
                                  ↓
                SDK: NotificationFeedRequestBuilder.fetchNext()
                                  ↓
                NotificationFeedItem.getContent() → Card Schema JSON
                                  ↓
                Cards Library: CometChatCardView
                                  ↓
                Native Rendered Card (images, text, buttons, layouts)
                                  ↓
                User taps button → onAction callback → Your code handles it
```

***

## How Cards Work

Each `NotificationFeedItem` from the SDK contains a `content` field — an object holding the Card Schema JSON. This JSON is passed directly to the CometChat Cards renderer which produces a native view.

The Cards library is a **pure renderer**:

* **Input**: Card Schema JSON string + theme mode + optional action callback
* **Output**: Native React Native view hierarchy

It does not execute actions, manage message state, or call any SDK methods. When users tap interactive elements (buttons, links), the library emits the action to your callback. You decide what happens — open a URL, navigate to a chat, make an API call, etc.

### Card Schema JSON Example

```json theme={null}
{
  "version": "1.0",
  "body": [
    {
      "type": "column",
      "backgroundColor": { "light": "transparent", "dark": "transparent" },
      "gap": 5,
      "items": [
        { "type": "text", "content": "📢 Announcement", "variant": "heading2", "id": "txt_99323141-2459-4e33-88d3-ca39c5fd2f50" },
        { "type": "text", "content": "Your announcement message here.", "variant": "body", "id": "txt_61a417bc-5e4a-4ba2-bfe7-b7bc64dbaf35" },
        { "type": "divider", "id": "div_80f5c7fb-fd10-41d1-8c2f-51498f0f62d0" },
        {
          "type": "button",
          "label": "Learn More",
          "backgroundColor": { "light": "transparent", "dark": "transparent" },
          "textColor": { "light": "#6C5CE7", "dark": "#6C5CE7" },
          "size": 40,
          "fontSize": 13,
          "borderRadius": 6,
          "padding": { "top": 0, "right": 16, "bottom": 0, "left": 16 },
          "action": { "type": "openUrl", "url": "" },
          "id": "btn_9b87a3f1-b0c6-45b9-a4c2-e22ea590f17f"
        }
      ],
      "id": "col_98fed9bd-1a95-4cee-aa81-84a9016e41f2"
    }
  ],
  "fallbackText": "",
  "style": {
    "background": { "light": "#E8E8E8", "dark": "#E8E8E8" },
    "borderRadius": 16,
    "borderColor": { "light": "#DFE6E9", "dark": "#DFE6E9" },
    "padding": 12
  }
}
```

The above JSON renders as:

<Frame>
  <img />
</Frame>

The schema supports **20 element types** (text, image, icon, avatar, badge, divider, spacer, chip, progressBar, codeBlock, markdown, row, column, grid, accordion, tabs, button, iconButton, link, table) and **9 action types** (openUrl, chatWithUser, chatWithGroup, sendMessage, copyToClipboard, downloadFile, initiateCall, apiCall, customCallback).

***

## How Cards Work in the UI Kit

The `CometChatNotificationFeed` component uses the **CometChat Cards** library internally to render each notification. Here's what happens under the hood:

1. The component fetches `NotificationFeedItem` objects from the SDK
2. For each item, it extracts the `content` field (Card Schema JSON)
3. It passes the JSON to `CometChatCardView` from the Cards library
4. The Cards renderer produces native UI — text, images, buttons, layouts — directly from the JSON
5. When users tap buttons/links inside a card, the action is emitted back to the component which handles navigation (open URL, navigate to chat, etc.)

You don't need to interact with the Cards library directly when using `CometChatNotificationFeed` — it's all wired up. But if you want to render cards outside the feed (e.g., a standalone card in a modal), you can use the Cards library directly. See the [SDK Campaigns documentation](/docs/sdk/react-native/campaigns#rendering-cards) for standalone usage.

***

## Handling Push Notifications for Campaigns

When a campaign push notification arrives via FCM/APNs, you should:

1. **Report delivery** — Call `CometChat.markPushNotificationDelivered()` when the notification is received
2. **Report click** — Call `CometChat.markPushNotificationClicked()` when the user taps the notification
3. **Deep link** — Use the announcement ID from the push payload to fetch the full item via `CometChat.getNotificationFeedItem(id)` and display it

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";

// When push notification is received
const pushNotification = new CometChat.PushNotification(pushPayloadData);
CometChat.markPushNotificationDelivered(pushNotification);

// When user taps the notification
CometChat.markPushNotificationClicked(pushNotification);

// Navigate to feed or show specific item
const item = await CometChat.getNotificationFeedItem(pushNotification.getId());
```

See the [SDK Campaigns documentation](/docs/sdk/react-native/campaigns) for the complete push notification tracking API.

***

## Sending Campaigns

Before integrating the frontend, you need to set up channels, categories, templates, and campaigns in the CometChat Dashboard. Follow the [Dashboard Setup Guide](/docs/campaigns#setup-flow) for step-by-step instructions with screenshots.

***

## Using the UI Kit Component

The easiest way to add a notification feed to your app is the `CometChatNotificationFeed` component. It handles fetching, rendering, pagination, filtering, real-time updates, and engagement reporting out of the box.

```tsx lines theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react-native";

function NotificationsScreen() {
  return (
    <CometChatNotificationFeed
      onItemClick={(item) => {
        // Handle item tap
      }}
      onBackPress={() => {
        // Navigate back
      }}
    />
  );
}
```

See the full [CometChatNotificationFeed component documentation](/docs/ui-kit/react-native/notification-feed) for all configuration options, styling, and customization.

***

## Next Steps

<CardGroup>
  <Card title="SDK Campaigns API" icon="code" href="/sdk/react-native/campaigns">
    Full API reference for feed items, categories, engagement, and push tracking
  </Card>

  <Card title="CometChatNotificationFeed" icon="bell" href="/ui-kit/react-native/notification-feed">
    Ready-to-use component with filtering, real-time updates, and styling
  </Card>
</CardGroup>


# Color Resources
Source: https://www.cometchat.com/docs/ui-kit/react-native/colors

Complete reference of CometChat React Native UI Kit color tokens for light and dark modes, custom themes, and brand styling.

<Accordion title="AI Integration Quick Reference">
  | Field           | Value                                                                                                                                                                                                                                                                  |
  | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Goal            | Override UI Kit color tokens to match a brand                                                                                                                                                                                                                          |
  | Provider        | `CometChatThemeProvider` — wrap app and pass `theme` prop                                                                                                                                                                                                              |
  | Import          | `import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";`                                                                                                                                                                                         |
  | Override colors | `theme={{ light: { color: { primary: "#F76808", textPrimary: "#7f7f00" } } }}`                                                                                                                                                                                         |
  | Key tokens      | `primary` (brand/accent), `neutral50` (surfaces), `background1` (main bg), `textPrimary`                                                                                                                                                                               |
  | Extended colors | Auto-generated from `primary` (extendedPrimary50–900) unless explicitly overridden                                                                                                                                                                                     |
  | Dark mode       | `theme={{ dark: { color: { ... } } }}` — separate palette for dark theme                                                                                                                                                                                               |
  | Constraints     | Colors must be hex values, extended colors auto-derive from primary                                                                                                                                                                                                    |
  | Source          | [GitHub theme types](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts) \| [Color helper](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/CometChatThemeHelper.ts) |
</Accordion>

The UI Kit's color palette uses theme tokens for consistent styling. Override these tokens via `CometChatThemeProvider` to match your brand.

<Warning>
  Prerequisites:

  1. Wrap your app with `CometChatThemeProvider`
  2. Colors must be supplied as hex values (e.g., `#F76808`)
  3. Extended primary colors auto-generate from `primary` unless explicitly overridden
</Warning>

***

## Color Token Reference

This table maps every commonly used token to what it visually controls.

| Token                     | What It Controls                                         | Default (Light) | Used By                                           |
| ------------------------- | -------------------------------------------------------- | --------------- | ------------------------------------------------- |
| `primary`                 | Brand accent, outgoing bubble bg, active states, buttons | `#6852D6`       | Outgoing bubbles, send button, active tabs        |
| `neutral50`               | White surface                                            | `#FFFFFF`       | Background color 01, cards                        |
| `neutral100`              | Light surface                                            | `#FAFAFA`       | Background color 02                               |
| `neutral200`              | Secondary surface                                        | `#F5F5F5`       | Background color 03                               |
| `neutral300`              | Incoming bubble background, borders                      | `#E8E8E8`       | Incoming message bubbles, background color 04     |
| `neutral400`              | Border dark                                              | `#DCDCDC`       | Borders, dividers                                 |
| `neutral500`              | Muted text, placeholders                                 | `#A1A1A1`       | Placeholder text, disabled states, icon secondary |
| `neutral600`              | Secondary text                                           | `#727272`       | Timestamps, subtitles                             |
| `neutral700`              | Tertiary text                                            | `#5B5B5B`       | Body text                                         |
| `neutral800`              | Strong text                                              | `#434343`       | Headings                                          |
| `neutral900`              | Strongest text                                           | `#141414`       | Text color primary                                |
| `background1`             | Main app background                                      | `neutral50`     | Root container background                         |
| `background2`             | Secondary/panel background                               | `neutral100`    | Sidebars, panels                                  |
| `background3`             | Tertiary background                                      | `neutral200`    | Nested panels, cards                              |
| `background4`             | Quaternary background                                    | `neutral300`    | Additional surface layer                          |
| `textPrimary`             | Primary text color                                       | `neutral900`    | Main body text                                    |
| `textSecondary`           | Secondary/caption text                                   | `neutral600`    | Timestamps, subtitles                             |
| `textTertiary`            | Tertiary text                                            | `neutral500`    | Hints, placeholders                               |
| `textHighlight`           | Highlighted text                                         | `primary`       | Links, mentions                                   |
| `iconPrimary`             | Primary icon color                                       | `neutral900`    | Main icons                                        |
| `iconSecondary`           | Secondary icon color                                     | `neutral500`    | Inactive icons                                    |
| `iconHighlight`           | Highlighted icon color                                   | `primary`       | Active icons                                      |
| `extendedPrimary50–900`   | Primary color scale (lightest to darkest)                | Auto-generated  | Hover states, gradients, shades                   |
| `info`                    | Informational states                                     | `#0B7BEA`       | Info callouts, links                              |
| `warning`                 | Warning states                                           | `#FFAB00`       | Warning callouts                                  |
| `success`                 | Success states                                           | `#09C26F`       | Online indicators, success messages               |
| `error`                   | Error states                                             | `#F44649`       | Error messages, validation                        |
| `staticBlack`             | Static black (doesn't change with theme)                 | `#141414`       | Fixed dark elements                               |
| `staticWhite`             | Static white (doesn't change with theme)                 | `#FFFFFF`       | Fixed light elements                              |
| `sendBubbleBackground`    | Outgoing bubble background                               | `primary`       | Sent message bubbles                              |
| `sendBubbleText`          | Outgoing bubble text                                     | `staticWhite`   | Sent message text                                 |
| `receiveBubbleBackground` | Incoming bubble background                               | `neutral300`    | Received message bubbles                          |
| `receiveBubbleText`       | Incoming bubble text                                     | `neutral900`    | Received message text                             |

***

## Overview

Colors in `CometChatTheme` allow you to maintain a consistent visual identity across your application by providing predefined colors for various UI elements, such as text, buttons, backgrounds, alerts, and more. These color definitions seamlessly adapt to both light and dark themes, ensuring an optimal user experience across different modes.

The color resources are divided into the following categories:

* **Primary Colors**: Define the main theme of the application.
* **Neutral Colors**: Used for backgrounds, borders, and secondary UI elements.
* **Alert Colors**: Highlight states like success, warning, error, or information.
* **Text Colors**: Used for typography.
* **Icon Colors**: Define icon appearances.
* **Button Colors**: Customize button backgrounds, icons, and text.

CometChat provides separate color definitions for **light mode** and **dark mode**, enabling automatic theme adaptation.

***

## Usage

### Default Colors

CometChat provides predefined color sets for both light and dark modes, ensuring optimal visual contrast and accessibility across your application.

These colors can be accessed through the `theme value`, which is obtained using the `useTheme()` hook.

Example: Colors

<Tabs>
  <Tab title="Light Mode Colors">
    ```ts theme={null}
    import { ColorValue } from "react-native";

    const primaryColor = "#6852D6";

    const extendedPrimaryColors = {
      extendedPrimary50: "<generated based on primaryColor>",
      extendedPrimary100: "<generated based on primaryColor>",
      //generated based on
    };

    const neutralColors = {
      neutral50: "#FFFFFF",
      neutral100: "#FAFAFA",
      //other colors
    };

    const alertColors = {
      info: "#0B7BEA",
      warning: "#FFAB00",
      //other colors
    };

    const staticColors = {
      staticBlack: "#141414",
      staticWhite: "#FFFFFF",
    };

    export const defaultColorLight = {
      primary: primaryColor,
      ...extendedPrimaryColors,
      ...neutralColors,
      ...alertColors,
      ...staticColors,

      background1: neutralColors.neutral50,
      background2: neutralColors.neutral100,
      background3: neutralColors.neutral200,
      background4: neutralColors.neutral300,
      //other derived colors
    };

    type EachColorValue<T extends typeof defaultColorLight> = {
      [P in keyof T]: ColorValue;
    };

    //color type
    export type Color = EachColorValue<typeof defaultColorLight>;
    ```
  </Tab>

  <Tab title="Dark Mode Colors">
    ```ts theme={null}
    import { Color } from "./light"; //type imported from light

    const primaryColor = "#6852D6";

    const extendedPrimaryColors = {
      extendedPrimary50: "<generated based on primaryColor>",
      extendedPrimary100: "<generated based on primaryColor>",
      //other derived colors
    };

    const neutralColors = {
      neutral50: "#141414",
      neutral100: "#1A1A1A",
      //other derived colors
    };

    const alertColors = {
      info: "#0D66BF",
      warning: "#D08D04",
      success: "#0B9F5D",
      error: "#C73C3E",
    };

    const staticColors = {
      staticBlack: "#141414",
      staticWhite: "#FFFFFF",
    };

    export const defaultColorDark: Color = {
      primary: primaryColor,
      ...extendedPrimaryColors,
      ...neutralColors,
      ...alertColors,
      ...staticColors,

      background1: neutralColors.neutral50,
      background2: neutralColors.neutral100,
      background3: neutralColors.neutral200,
      background4: neutralColors.neutral300,
      //other derived colors
    };
    ```
  </Tab>
</Tabs>

Extended colors `50-100` are generated based on the following blend percentages.

```typescript theme={null}
export enum Brightness {
  LIGHT = 0,
  DARK = 1,
}

getBlendColorsPercentage(brightness: Brightness): {
    [key: number]: number;
  } {
    return brightness === Brightness.LIGHT
      ? {
          50: 0.96,
          100: 0.88,
          200: 0.77,
          300: 0.66,
          400: 0.55,
          500: 0.44,
          600: 0.33,
          700: 0.22,
          800: 0.11,
          900: 0.11,
        }
      : {
          50: 0.8,
          100: 0.72,
          200: 0.64,
          300: 0.56,
          400: 0.48,
          500: 0.4,
          600: 0.32,
          700: 0.24,
          800: 0.16,
          900: 0.08,
        };
  }

  //baseColor is the primary color
  blendColors(baseColor: string, blendColor: string, percentage: number): string {
    const { r: rBase, g: gBase, b: bBase } = this.hexToRgb(baseColor);
    const { r: rBlend, g: gBlend, b: bBlend } = this.hexToRgb(blendColor);

    const r = Math.round(rBase * (1 - percentage) + rBlend * percentage);
    const g = Math.round(gBase * (1 - percentage) + gBlend * percentage);
    const b = Math.round(bBase * (1 - percentage) + bBlend * percentage);

    return this.rgbToHex(r, g, b);
  }
```

For more details on how other colors are generated, [click here](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/CometChatThemeHelper.ts).

<Note>
  Extended primary colors, as well as background, text, button, and other UI colors, are automatically derived from the provided primary and neutral colors. However, any colors explicitly overridden in the theme via `CometChatThemeProvider` will take precedence over the generated values.
</Note>

## Customizing Colors

You can override the default colors to align them with your application's branding.

<Warning>
  Colors must be supplied as hex values.
</Warning>

Example: Changing the primary and textPrimary colors.

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { SafeAreaView } from "react-native-safe-area-context";
    import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

    return (
      <SafeAreaView style={{ flex: 1 }}>
        <CometChatThemeProvider
          theme={{
            light: {
              color: {
                // The extended primary colors that are not explicitly defined will be auto-generated
                primary: "#b2b200",
                // Since textPrimary is explicitly defined, it won't be auto-generated
                textPrimary: "#7f7f00",
              },
            },
          }}
        >
          {/* Component */}
        </CometChatThemeProvider>
      </SafeAreaView>
    );
    ```
  </Tab>
</Tabs>

To learn more about the theme structure, visit the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

<Frame>
  <img />
</Frame>

***

## Next Steps

<CardGroup>
  <Card title="Introduction to Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Learn how CometChatThemeProvider manages light and dark modes
  </Card>

  <Card title="Message Bubble Styling" icon="message" href="/ui-kit/react-native/message-bubble-styling">
    Style individual message bubbles and their content
  </Card>

  <Card title="Localize" icon="globe" href="/ui-kit/react-native/localize">
    Translate UI strings and support multiple languages
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Explore all available UI Kit components
  </Card>
</CardGroup>


# Compact Message Composer
Source: https://www.cometchat.com/docs/ui-kit/react-native/compact-message-composer

Compact React Native message input with rich text, attachments, mentions, voice recording, and message editing.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatCompactMessageComposer",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatCompactMessageComposer } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Compact message input with optional rich text formatting (bold, italic, underline, strikethrough, links, lists, blockquotes, inline code, code blocks), auto-expanding input, attachments, mentions, voice recording, and message editing support.",
    "primaryOutput": {
      "prop": "onSendButtonPress",
      "type": "(message: CometChat.BaseMessage) => void"
    },
    "props": {
      "data": {
        "user": { "type": "CometChat.User", "default": "undefined" },
        "group": { "type": "CometChat.Group", "default": "undefined" },
        "parentMessageId": { "type": "string | number", "default": "undefined" },
        "text": { "type": "string", "default": "\"\"" },
        "initialComposertext": { "type": "string", "default": "\"\"" },
        "placeHolderText": { "type": "string", "default": "\"Enter your message here\"" }
      },
      "callbacks": {
        "onSendButtonPress": "(message: CometChat.BaseMessage) => void",
        "onChangeText": "(text: string) => void",
        "onError": "(error: CometChat.CometChatException) => void",
        "onVoiceRecordingStart": "() => void",
        "onVoiceRecordingEnd": "(recordedFile: string) => void",
        "onAttachmentClick": "() => void",
        "onMentionLimitReached": "() => void"
      },
      "visibility": {
        "hideVoiceRecordingButton": { "type": "boolean", "default": false },
        "hideCameraOption": { "type": "boolean", "default": false },
        "hideImageAttachmentOption": { "type": "boolean", "default": false },
        "hideVideoAttachmentOption": { "type": "boolean", "default": false },
        "hideAudioAttachmentOption": { "type": "boolean", "default": false },
        "hideFileAttachmentOption": { "type": "boolean", "default": false },
        "hidePollsAttachmentOption": { "type": "boolean", "default": false },
        "hideCollaborativeDocumentOption": { "type": "boolean", "default": false },
        "hideCollaborativeWhiteboardOption": { "type": "boolean", "default": false },
        "hideAttachmentButton": { "type": "boolean", "default": false },
        "hideStickersButton": { "type": "boolean", "default": false },
        "hideSendButton": { "type": "boolean", "default": false },
        "hideAuxiliaryButtons": { "type": "boolean", "default": false }
      },
      "richText": {
        "enableRichTextEditor": { "type": "boolean", "default": true },
        "hideRichTextFormattingOptions": { "type": "boolean", "default": false },
        "showTextSelectionMenuItems": { "type": "boolean", "default": true },
        "enterKeyBehavior": { "type": "EnterKeyBehavior", "default": "EnterKeyBehavior.NewLine", "note": "Android only" }
      },
      "autoExpand": {
        "maxLines": { "type": "number", "default": 5 },
        "minInputHeight": { "type": "number", "default": 40 },
        "maxInputHeight": { "type": "number", "default": 144 }
      },
      "configuration": {
        "imageQuality": { "type": "number (1-100)", "default": 20 },
        "auxiliaryButtonsAlignment": { "type": "\"left\" | \"right\"", "default": "\"left\"" },
        "maxMentionLimit": { "type": "number", "default": 10 }
      },
      "sound": {
        "disableSoundForOutgoingMessages": { "type": "boolean", "default": false },
        "customSoundForOutgoingMessage": { "type": "audio source", "default": "built-in" }
      },
      "behavior": {
        "disableTypingEvents": { "type": "boolean", "default": false },
        "disableMentions": { "type": "boolean", "default": false },
        "disableMentionAll": { "type": "boolean", "default": false },
        "mentionAllLabel": { "type": "string", "default": "\"all\"" }
      },
      "viewSlots": {
        "HeaderView": "({ user, group }) => JSX.Element",
        "FooterView": "({ user, group }) => JSX.Element",
        "AuxiliaryButtonView": "({ user, group, composerId }) => JSX.Element",
        "SecondaryButtonView": "({ user, group, composerId }) => JSX.Element",
        "SendButtonView": "({ user, group, composerId }) => JSX.Element"
      },
      "formatting": {
        "textFormatters": {
          "type": "CometChatTextFormatter[]",
          "default": "default formatters from data source"
        },
        "attachmentOptions": {
          "type": "CometChatMessageComposerAction[]",
          "note": "Custom attachment options list"
        },
        "addAttachmentOptions": {
          "type": "CometChatMessageComposerAction[]",
          "note": "Additional attachment options to append to defaults"
        }
      }
    },
    "events": [
      {
        "name": "ccMessageSent",
        "payload": "{ message: CometChat.BaseMessage, status: string }",
        "description": "Triggers when a message is sent with status: inProgress, success, or error"
      },
      {
        "name": "ccMessageEdited",
        "payload": "{ message: CometChat.BaseMessage, status: string }",
        "description": "Triggers when a message is edited with status: inProgress, success, or error"
      }
    ],
    "compositionExample": {
      "description": "Compact message composer wired with message header and list for complete chat view",
      "components": [
        "CometChatMessageHeader",
        "CometChatMessageList",
        "CometChatCompactMessageComposer"
      ],
      "flow": "Pass user or group prop to composer -> onSendButtonPress fires with CometChat.BaseMessage -> message appears in MessageList"
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatCompactMessageComposer` is a [Component](/docs/ui-kit/react-native/components-overview#components) that provides a compact, streamlined message input with optional rich text formatting capabilities. Its formatting toolbar supports bold, italic, underline, strikethrough, links, lists, blockquotes, inline code, and code blocks, along with auto-expanding input, attachments, mentions, voice recording, and message editing.

This is a compact variant of [CometChatMessageComposer](/docs/ui-kit/react-native/message-composer). It shares the same props API but adds rich text formatting controls, auto-expanding input configuration, and additional callbacks.

Wire it alongside `CometChatMessageHeader` and `CometChatMessageList` to build a standard chat view.

***

## Minimal Render

```tsx lines theme={null}
import { CometChatCompactMessageComposer } from "@cometchat/chat-uikit-react-native";

function CompactComposerDemo() {
  return <CometChatCompactMessageComposer user={chatUser} />;
}

export default CompactComposerDemo;
```

***

## Actions and Events

### Callback Props

#### onSendButtonPress

Fires when the send message button is clicked. Overrides the default send behavior.

```tsx lines theme={null}
onSendButtonPress?: (message: CometChat.BaseMessage) => void
```

```tsx lines theme={null}
import { CometChatCompactMessageComposer } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function CompactComposerWithCustomSend() {
  const onSendButtonPressHandler = (message: CometChat.BaseMessage) => {
    console.log("Custom send:", message);
  };

  return (
    <CometChatCompactMessageComposer
      user={chatUser}
      onSendButtonPress={onSendButtonPressHandler}
    />
  );
}
```

#### onError

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

```tsx lines theme={null}
onError?: (error: CometChat.CometChatException) => void
```

```tsx lines theme={null}
import { CometChatCompactMessageComposer } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function CompactComposerWithErrorHandler() {
  return (
    <CometChatCompactMessageComposer
      user={chatUser}
      onError={(error: CometChat.CometChatException) => {
        console.error("Composer error:", error);
      }}
    />
  );
}
```

#### onChangeText

Fires as the user types in the composer input.

```tsx lines theme={null}
onChangeText?: (text: string) => void
```

```tsx lines theme={null}
import { CometChatCompactMessageComposer } from "@cometchat/chat-uikit-react-native";

function CompactComposerWithTextTracking() {
  return (
    <CometChatCompactMessageComposer
      user={chatUser}
      onChangeText={(text: string) => {
        console.log("Text changed:", text);
      }}
    />
  );
}
```

#### onMentionLimitReached

Fires when the maximum mention limit per message is reached.

```tsx lines theme={null}
onMentionLimitReached?: () => void
```

```tsx lines theme={null}
import { CometChatCompactMessageComposer } from "@cometchat/chat-uikit-react-native";

function CompactComposerWithMentionLimit() {
  return (
    <CometChatCompactMessageComposer
      user={chatUser}
      maxMentionLimit={5}
      onMentionLimitReached={() => {
        console.log("Mention limit reached");
      }}
    />
  );
}
```

### Global UI Events

`CometChatUIEventHandler` emits events subscribable from anywhere in the application. Add listeners and remove them on cleanup.

| Event             | Fires when          | Payload                                              |
| ----------------- | ------------------- | ---------------------------------------------------- |
| `ccMessageSent`   | A message is sent   | `{ message: CometChat.BaseMessage, status: string }` |
| `ccMessageEdited` | A message is edited | `{ message: CometChat.BaseMessage, status: string }` |

When to use: sync external UI with message state changes. For example, update a notification badge when messages are sent, or trigger analytics when a message is edited.

```tsx lines theme={null}
import { useEffect } from "react";
import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";

function useCompactComposerEvents() {
  useEffect(() => {
    const listenerId = "COMPACT_COMPOSER_EVENTS_" + Date.now();

    CometChatUIEventHandler.addMessageListener(listenerId, {
      ccMessageSent: (item) => {
        console.log("Message sent:", item);
      },
      ccMessageEdited: (item) => {
        console.log("Message edited:", item);
      },
    });

    return () => {
      CometChatUIEventHandler.removeMessageListener(listenerId);
    };
  }, []);
}
```

<Note>
  In React 18 StrictMode, `useEffect` runs twice on mount in development. The component handles listener cleanup internally, but any additional listeners added alongside the component need cleanup in the `useEffect` return function to avoid duplicate event handling.
</Note>

***

## Rich Text Formatting

The CompactMessageComposer includes a built-in rich text editor. Rich text is enabled by default via `enableRichTextEditor={true}`.

### Formatting Toolbar

The toolbar provides the following formatting tools:

| Tool          | Description                                                   |
| ------------- | ------------------------------------------------------------- |
| Bold          | Bold text                                                     |
| Italic        | Italic text                                                   |
| Underline     | Underline text                                                |
| Strikethrough | Strikethrough text                                            |
| Link          | Wrap the selected text in a link — opens a prompt for the URL |
| Numbered List | Convert the current line/block to an ordered list             |
| Bulleted List | Convert the current line/block to an unordered list           |
| Blockquote    | Convert the current line/block to a blockquote                |
| Code          | Inline code                                                   |
| Code Block    | Multi-line fenced code block                                  |

### Toolbar Visibility Modes

The toolbar supports multiple display modes controlled via props:

| `enableRichTextEditor` | `hideRichTextFormattingOptions` | Result                                             |
| ---------------------- | ------------------------------- | -------------------------------------------------- |
| `false`                | -                               | Plain text, no formatting UI                       |
| `true`                 | `true`                          | Toolbar always visible above input                 |
| `true`                 | `false`                         | No toolbar UI, only text selection menu items work |

### Text Selection Menu Items

On React Native, the `showTextSelectionMenuItems` prop controls whether Bold, Italic, Underline, and Strikethrough options appear in the native text selection context menu (long-press popup). This is enabled by default.

### Enter Key Behavior (Android Only)

The `enterKeyBehavior` prop controls what happens when the Enter key is pressed on Android. On iOS, Enter always inserts a new line.

```tsx lines theme={null}
import { CometChatCompactMessageComposer, EnterKeyBehavior } from "@cometchat/chat-uikit-react-native";

// Send message on Enter (Android)
<CometChatCompactMessageComposer
  user={chatUser}
  enterKeyBehavior={EnterKeyBehavior.SendMessage}
/>

// New line on Enter (default)
<CometChatCompactMessageComposer
  user={chatUser}
  enterKeyBehavior={EnterKeyBehavior.NewLine}
/>
```

### Toolbar Configuration Examples

```tsx lines theme={null}
// Toolbar always visible above input
<CometChatCompactMessageComposer
  user={chatUser}
  enableRichTextEditor={true}
  hideRichTextFormattingOptions={true}
/>
```

```tsx lines theme={null}
// Rich text enabled with text selection menu items only
<CometChatCompactMessageComposer
  user={chatUser}
  enableRichTextEditor={true}
  showTextSelectionMenuItems={true}
/>
```

```tsx lines theme={null}
// Plain text only (no formatting)
<CometChatCompactMessageComposer
  user={chatUser}
  enableRichTextEditor={false}
/>
```

***

## Auto-Expanding Input

The CompactMessageComposer input auto-expands as the user types, up to a configurable maximum.

| Prop             | Type     | Default                          | Description                                                         |
| ---------------- | -------- | -------------------------------- | ------------------------------------------------------------------- |
| `maxLines`       | `number` | `5`                              | Maximum lines before scrolling is enabled                           |
| `minInputHeight` | `number` | `40`                             | Minimum height for the input in pixels                              |
| `maxInputHeight` | `number` | `144` (calculated from maxLines) | Maximum height for the input. Overrides `maxLines` if both provided |

```tsx lines theme={null}
<CometChatCompactMessageComposer
  user={chatUser}
  maxLines={3}
  minInputHeight={36}
  maxInputHeight={120}
/>
```

***

## Custom View Slots

Each slot replaces a section of the default UI. Slots that accept parameters receive the relevant data for customization.

| Slot                   | Signature                                      | Replaces                                           |
| ---------------------- | ---------------------------------------------- | -------------------------------------------------- |
| `HeaderView`           | `({ user, group }) => JSX.Element`             | Area above the composer input                      |
| `FooterView`           | `({ user, group }) => JSX.Element`             | Area below the composer input                      |
| `AuxiliaryButtonView`  | `({ user, group, composerId }) => JSX.Element` | Sticker button area                                |
| `SecondaryButtonView`  | `({ user, group, composerId }) => JSX.Element` | Attachment button area                             |
| `SendButtonView`       | `({ user, group, composerId }) => JSX.Element` | Send button                                        |
| `attachmentOptions`    | `CometChatMessageComposerAction[]`             | Default attachment options list                    |
| `addAttachmentOptions` | `CometChatMessageComposerAction[]`             | Additional attachment options appended to defaults |
| `textFormatters`       | `CometChatTextFormatter[]`                     | Text formatting in composer                        |

### textFormatters

Custom text formatters for the composer input. To configure the existing Mentions look and feel check out [CometChatMentionsFormatter](/docs/ui-kit/react-native/mentions-formatter-guide).

```tsx lines theme={null}
import {
  CometChatCompactMessageComposer,
  CometChatTextFormatter,
  CometChatMentionsFormatter,
} from "@cometchat/chat-uikit-react-native";

const getTextFormatters = () => {
  const textFormatters: CometChatTextFormatter[] = [];
  const mentionsFormatter = new CometChatMentionsFormatter();
  mentionsFormatter.setMentionsStyle({
    textStyle: { color: "#D6409F" },
    selfTextStyle: { color: "#30A46C" },
  });
  textFormatters.push(mentionsFormatter);
  return textFormatters;
};

return (
  <CometChatCompactMessageComposer
    user={chatUser}
    textFormatters={getTextFormatters()}
  />
);
```

### attachmentOptions

Override the default attachment options with custom actions.

```tsx lines theme={null}
import { CometChatCompactMessageComposer } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const getCustomAttachmentOptions = ({
  user,
  group,
  composerId,
}: {
  user?: CometChat.User;
  group?: CometChat.Group;
  composerId: Map<any, any>;
}): CometChatMessageComposerAction[] => {
  return [
    {
      id: "location",
      icon: LocationIcon,
      title: "Share Location",
      style: { iconStyle: { tintColor: "grey" } },
      onPress: () => {
        // handle location share
      },
    },
  ];
};

return (
  <CometChatCompactMessageComposer
    user={chatUser}
    attachmentOptions={getCustomAttachmentOptions}
  />
);
```

### addAttachmentOptions

Extends the default attachment options with additional actions.

```tsx lines theme={null}
import { CometChatCompactMessageComposer } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const getAdditionalAttachmentOptions = ({
  user,
  group,
  composerId,
}: {
  user?: CometChat.User;
  group?: CometChat.Group;
  composerId: Map<any, any>;
}): CometChatMessageComposerAction[] => {
  return [
    {
      id: "location",
      icon: LocationIcon,
      title: "Share Location",
      style: { iconStyle: { tintColor: "grey" } },
      onPress: () => {
        // handle location share
      },
    },
  ];
};

return (
  <CometChatCompactMessageComposer
    user={chatUser}
    addAttachmentOptions={getAdditionalAttachmentOptions}
  />
);
```

### AuxiliaryButtonView

Replace the sticker button area with a custom view.

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatCompactMessageComposer } from "@cometchat/chat-uikit-react-native";
import { TouchableOpacity, Image, StyleSheet } from "react-native";

const styles = StyleSheet.create({
  button: {
    height: 25,
    width: 25,
    borderRadius: 0,
    backgroundColor: "transparent",
  },
  image: {
    height: 23,
    width: 24,
    tintColor: "#7E57C2",
  },
});

const customAuxiliaryButtonView = ({
  user,
  group,
  composerId,
}: {
  user?: CometChat.User;
  group?: CometChat.Group;
  composerId: string | number;
}): JSX.Element => {
  return (
    <TouchableOpacity style={styles.button} onPress={() => {}}>
      <Image source={LocationIcon} style={styles.image} />
    </TouchableOpacity>
  );
};

return (
  <CometChatCompactMessageComposer
    user={chatUser}
    AuxiliaryButtonView={customAuxiliaryButtonView}
  />
);
```

<Note>
  The CompactMessageComposer Component utilizes the AuxiliaryButton to provide sticker functionality. Overriding the AuxiliaryButton will replace the sticker functionality.
</Note>

### SendButtonView

Replace the send button with a custom view.

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatCompactMessageComposer } from "@cometchat/chat-uikit-react-native";
import { TouchableOpacity, Image, StyleSheet } from "react-native";

const styles = StyleSheet.create({
  button: {
    height: 25,
    width: 25,
    borderRadius: 0,
    backgroundColor: "transparent",
  },
  image: {
    height: 23,
    width: 24,
    tintColor: "#7E57C2",
  },
});

const customSendButtonView = ({
  user,
  group,
  composerId,
}: {
  user?: CometChat.User;
  group?: CometChat.Group;
  composerId: string | number;
}): JSX.Element => {
  return (
    <TouchableOpacity style={styles.button} onPress={() => {}}>
      <Image source={SendButtonIcon} style={styles.image} />
    </TouchableOpacity>
  );
};

return (
  <CometChatCompactMessageComposer
    user={chatUser}
    SendButtonView={customSendButtonView}
  />
);
```

### HeaderView

Custom view above the composer input.

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatCompactMessageComposer } from "@cometchat/chat-uikit-react-native";
import { View, Text, StyleProp, ViewStyle } from "react-native";

const viewStyle: StyleProp<ViewStyle> = {
  flexDirection: "row",
  alignItems: "flex-start",
  justifyContent: "center",
  padding: 5,
  borderColor: "black",
  borderWidth: 1,
  backgroundColor: "white",
  borderRadius: 10,
  margin: 2,
  marginLeft: 7.4,
  height: 30,
  width: "95.5%",
};

const customHeaderView = ({
  user,
  group,
}: {
  user?: CometChat.User;
  group?: CometChat.Group;
}) => {
  return (
    <View style={viewStyle}>
      <Text style={{ color: "#6851D6", fontWeight: "bold" }}>Chat Bot</Text>
    </View>
  );
};

return (
  <CometChatCompactMessageComposer
    user={chatUser}
    HeaderView={customHeaderView}
  />
);
```

### FooterView

Custom view below the composer input.

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatCompactMessageComposer } from "@cometchat/chat-uikit-react-native";
import { View, Text } from "react-native";

const customFooterView = ({
  user,
  group,
}: {
  user?: CometChat.User;
  group?: CometChat.Group;
}) => {
  return (
    <View style={{ padding: 8 }}>
      <Text style={{ fontSize: 12, color: "#999" }}>End-to-end encrypted</Text>
    </View>
  );
};

return (
  <CometChatCompactMessageComposer
    user={chatUser}
    FooterView={customFooterView}
  />
);
```

***

## Styling

Using the `style` prop you can customize the look and feel of the component in your app. These parameters typically control elements such as the color, size, shape, and fonts used within the component.

```tsx lines theme={null}
<CometChatCompactMessageComposer
  user={chatUser}
  style={{
    containerStyle: { backgroundColor: "#F5F5F5" },
    messageInputStyles: {
      containerStyle: { borderColor: "#6851D6" },
      textStyle: { color: "#333333" },
      placeHolderTextColor: "#999999",
    },
  }}
/>
```

### Visibility Props

| Property                            | Description                              | Code                                              |
| ----------------------------------- | ---------------------------------------- | ------------------------------------------------- |
| `user`                              | User object for 1-on-1 conversation      | `user={chatUser}`                                 |
| `group`                             | Group object for group conversation      | `group={chatGroup}`                               |
| `disableTypingEvents`               | Disable/enable typing events             | `disableTypingEvents={true}`                      |
| `disableSoundForOutgoingMessages`   | Toggle sound for outgoing messages       | `disableSoundForOutgoingMessages={true}`          |
| `initialComposertext`               | Set predefined text                      | `initialComposertext="Your custom text"`          |
| `placeHolderText`                   | Placeholder text for the input           | `placeHolderText="Type a message..."`             |
| `customSoundForOutgoingMessage`     | Custom sound for outgoing messages       | `customSoundForOutgoingMessage="your-sound"`      |
| `hideVoiceRecordingButton`          | Hide voice recording option              | `hideVoiceRecordingButton={true}`                 |
| `hideCameraOption`                  | Hide camera option from attachments      | `hideCameraOption={true}`                         |
| `hideImageAttachmentOption`         | Hide image attachment option             | `hideImageAttachmentOption={true}`                |
| `hideVideoAttachmentOption`         | Hide video attachment option             | `hideVideoAttachmentOption={true}`                |
| `hideAudioAttachmentOption`         | Hide audio attachment option             | `hideAudioAttachmentOption={true}`                |
| `hideFileAttachmentOption`          | Hide file attachment option              | `hideFileAttachmentOption={true}`                 |
| `hidePollsAttachmentOption`         | Hide polls attachment option             | `hidePollsAttachmentOption={true}`                |
| `hideCollaborativeDocumentOption`   | Hide collaborative document option       | `hideCollaborativeDocumentOption={true}`          |
| `hideCollaborativeWhiteboardOption` | Hide collaborative whiteboard option     | `hideCollaborativeWhiteboardOption={true}`        |
| `hideAttachmentButton`              | Hide attachment button                   | `hideAttachmentButton={true}`                     |
| `hideStickersButton`                | Hide stickers button                     | `hideStickersButton={true}`                       |
| `hideSendButton`                    | Hide send button                         | `hideSendButton={true}`                           |
| `hideAuxiliaryButtons`              | Hide auxiliary buttons                   | `hideAuxiliaryButtons={true}`                     |
| `disableMentions`                   | Disable mentions functionality           | `disableMentions={true}`                          |
| `disableMentionAll`                 | Disable @all mention                     | `disableMentionAll={true}`                        |
| `mentionAllLabel`                   | Custom label for @all mention            | `mentionAllLabel="everyone"`                      |
| `imageQuality`                      | Image quality for camera (1-100)         | `imageQuality={50}`                               |
| `auxiliaryButtonsAlignment`         | Alignment of auxiliary buttons           | `auxiliaryButtonsAlignment="right"`               |
| `enableRichTextEditor`              | Enable/disable rich text formatting      | `enableRichTextEditor={true}`                     |
| `hideRichTextFormattingOptions`     | Always-visible toolbar mode              | `hideRichTextFormattingOptions={true}`            |
| `showTextSelectionMenuItems`        | Formatting in native text selection menu | `showTextSelectionMenuItems={true}`               |
| `enterKeyBehavior`                  | Android Enter key behavior               | `enterKeyBehavior={EnterKeyBehavior.SendMessage}` |
| `maxLines`                          | Maximum lines before scrolling           | `maxLines={3}`                                    |
| `minInputHeight`                    | Minimum input height in pixels           | `minInputHeight={36}`                             |
| `maxInputHeight`                    | Maximum input height in pixels           | `maxInputHeight={120}`                            |
| `maxMentionLimit`                   | Maximum mentions per message             | `maxMentionLimit={5}`                             |

***

## Configuration

`SingleLineMessageComposerConfiguration` can be used to pass configuration when embedding the CompactMessageComposer inside other components:

```tsx lines theme={null}
import { SingleLineMessageComposerConfiguration } from "@cometchat/chat-uikit-react-native";

const config = new SingleLineMessageComposerConfiguration({
  disableTypingEvents: true,
  hideVoiceRecording: true,
  disableMentions: false,
  maxLines: 3,
  placeHolderText: "Write something...",
});
```

***

## Next Steps

<CardGroup>
  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/react-native/message-composer">
    Full-featured multi-line message composer component
  </Card>

  <Card title="Message List" icon="message" href="/ui-kit/react-native/message-list">
    Display the list of messages in a conversation
  </Card>

  <Card title="Mentions Formatter" icon="at" href="/ui-kit/react-native/mentions-formatter-guide">
    Implement @mentions in your chat application
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>


# Component Styling
Source: https://www.cometchat.com/docs/ui-kit/react-native/component-styling

Customize the appearance of individual CometChat React Native UI Kit components using theme overrides for colors, typography, icons, and layout styles.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                            |
  | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
  | Goal             | Style individual UI Kit components via theme overrides                                                                           |
  | Provider         | `CometChatThemeProvider` — pass component styles in `theme` prop                                                                 |
  | Import           | `import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";`                                                   |
  | Pattern          | `theme={{ light: { <componentStyles>: { ... } } }}`                                                                              |
  | Conversations    | `conversationStyles: { itemStyle: { avatarStyle: { containerStyle: { borderRadius: 8 } } } }`                                    |
  | Users            | `userStyles: { titleStyle: { color: "#F76808" }, itemStyle: { ... } }`                                                           |
  | Groups           | `groupStyles: { titleStyle: { ... }, itemStyle: { ... } }`                                                                       |
  | Message List     | `messageListStyles: { containerStyle: { ... }, outgoingMessageBubbleStyles: { ... } }`                                           |
  | Message Composer | `messageComposerStyles: { sendIconContainerStyle: { ... }, attachmentIconStyle: { ... } }`                                       |
  | Precedence       | Style prop > Custom theme > Default theme (deep merge)                                                                           |
  | Source           | [GitHub theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts) |
</Accordion>

Style individual UI Kit components by passing component-specific style objects in the theme.

<Warning>
  Prerequisites:

  1. Wrap your app with `CometChatThemeProvider`
  2. Component styles are passed via `theme={{ light: { <componentStyles>: { ... } } }}`
  3. Style props on components take precedence over theme styles
</Warning>

***

## Component Style Keys

| Component           | Theme Key                  | Common Style Properties                                                            |
| ------------------- | -------------------------- | ---------------------------------------------------------------------------------- |
| Conversations       | `conversationStyles`       | `containerStyle`, `itemStyle`, `avatarStyle`                                       |
| Users               | `userStyles`               | `titleStyle`, `titleSeparatorStyle`, `itemStyle`                                   |
| Groups              | `groupStyles`              | `titleStyle`, `titleSeparatorStyle`, `itemStyle`                                   |
| Group Members       | `groupMemberStyle`         | `titleStyle`, `titleSeparatorStyle`, `backButtonIconStyle`                         |
| Message Header      | `messageHeaderStyles`      | `titleTextStyle`, `avatarStyle`, `callButtonStyle`                                 |
| Message List        | `messageListStyles`        | `containerStyle`, `incomingMessageBubbleStyles`, `outgoingMessageBubbleStyles`     |
| Message Composer    | `messageComposerStyles`    | `sendIconContainerStyle`, `attachmentIconStyle`, `voiceRecordingIconStyle`         |
| Thread Header       | `threadHeaderStyles`       | `containerStyle`, `replyCountBarStyle`, `messageBubbleContainerStyle`              |
| Call Logs           | `callLogsStyles`           | `titleTextStyle`, `titleSeparatorStyle`, `itemStyle`                               |
| Incoming Call       | `incomingCallStyle`        | `containerStyle`, `avatarStyle`, `acceptCallButtonStyle`, `declineCallButtonStyle` |
| Outgoing Call       | `outgoingCallStyle`        | `avatarStyle`, `endCallButtonStyle`                                                |
| Call Buttons        | `callButtonStyles`         | `audioCallButtonIconStyle`, `videoCallButtonIconStyle`                             |
| Avatar              | `avatarStyle`              | `containerStyle`, `imageStyle`                                                     |
| Badge               | `badgeStyle`               | `containerStyle`, `textStyle`                                                      |
| Status Indicator    | `statusIndicatorStyle`     | `containerStyleOnline`, `containerStyleOffline`                                    |
| Date                | `dateStyles`               | `textStyle`, `containerStyle`                                                      |
| Receipt             | `receiptStyles`            | `readIconStyle`, `deliveredIconStyle`, `sentIconStyle`                             |
| Action Sheet        | `actionSheetStyle`         | `optionsItemStyle`                                                                 |
| AI Chat History     | `chatHistoryStyles`        | `containerStyle`, `headerStyle`, `messageItemStyle`                                |
| Confirm Dialog      | `confirmDialogStyles`      | `containerStyle`, `titleStyle`, `messageStyle`                                     |
| Media Recorder      | `mediaRecorderStyle`       | `animationStyle`, `playIconStyle`, `pauseIconStyle`                                |
| Message Information | `messageInformationStyles` | `containerStyle`, `titleStyle`, `messageBubbleContainerStyle`                      |
| Reaction List       | `reactionListStyles`       | `tabStyle`, `reactionListItemStyle`                                                |

***

## Overview

CometChat UIKit enables developers to seamlessly integrate customizable components into their applications. Each component is designed to ensure a consistent user experience while offering flexibility to adapt to your app's design system. You can modify attributes such as colors, fonts, sizes, icons, and more using the theme provider or programmatically. Below is a detailed guide for styling individual components within the UIKit.

## Components

### Conversations

The `CometChatConversations` component provides a list of recent chats, showing participants, message previews, and timestamps. It supports default themes while offering deep customization for text appearance, icons, and overall layout. With this component, you can create an intuitive and visually appealing chat list that matches your app's branding.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatConversations,
  CometChatUIKit,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

///code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          typography: {
            heading4: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          conversationStyles: {
            itemStyle: {
              avatarStyle: {
                containerStyle: {
                  borderRadius: 8,
                  backgroundColor: "#FBAA75",
                },
                imageStyle: {
                  borderRadius: 8,
                },
              },
            },
          },
        },
      }}
    >
      {loggedIn && <CometChatConversations></CometChatConversations>}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Users

The `CometChatUsers` component displays a scrollable list of users. It is ideal for showcasing available contacts for messaging, calls, or group creation. Developers can style elements like user avatars, status indicators, and list backgrounds to align with their design guidelines.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatUsers,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          typography: {
            heading4: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          userStyles: {
            titleStyle: {
              color: "#FBAA75",
            },
            titleSeparatorStyle: {
              borderBottomColor: "#FBAA75",
            },
            itemStyle: {
              avatarStyle: {
                containerStyle: {
                  borderRadius: 8,
                  backgroundColor: "#FBAA75",
                },
                imageStyle: {
                  borderRadius: 8,
                },
              },
            },
          },
        },
      }}
    >
      {loggedIn && <CometChatUsers showLetterHeader={false}></CometChatUsers>}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Groups

The `CometChatGroups` component allows you to display and interact with chat groups. Each group item highlights key details like the group name, participant count, and last active time. Customization options include avatar styles, fonts, borders, and background colors, ensuring the component blends seamlessly with your app.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatGroups,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          typography: {
            heading4: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          groupStyles: {
            titleStyle: {
              color: "#FBAA75",
            },
            titleSeparatorStyle: {
              borderBottomColor: "#FBAA75",
            },
            itemStyle: {
              avatarStyle: {
                containerStyle: {
                  borderRadius: 8,
                  backgroundColor: "#FBAA75",
                },
                imageStyle: {
                  borderRadius: 8,
                },
              },
            },
          },
        },
      }}
    >
      {loggedIn && <CometChatGroups></CometChatGroups>}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Message Header

The `CometChatMessageHeader` component provides essential information about the active chat, such as the recipient's name, avatar, and status (online/offline). It often includes options like back navigation, search, or menu buttons. Customization options allow you to style the header background, text appearance, and icons to match your app's overall design.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatConversations,
  CometChatMessageHeader,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          typography: {
            heading4: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          messageHeaderStyles: {
            titleTextStyle: {
              color: "#F76808",
            },
            avatarStyle: {
              containerStyle: {
                borderRadius: 8,
                backgroundColor: "#FBAA75",
              },
            },
            callButtonStyle: {
              audioCallButtonIconStyle: {
                tintColor: "#F76808",
              },
              videoCallButtonIconStyle: {
                tintColor: "#F76808",
              },
            },
          },
        },
      }}
    >
      {loggedIn && (
        <View style={{ flex: 1 }}>
          <CometChatConversations
            style={{
              containerStyle: {
                display: messageUser || messageGroup ? "none" : "flex",
              },
            }}
            onItemPress={(item: CometChat.Conversation) => {
              if (
                item.getConversationType() ==
                CometChatUiKitConstants.ConversationTypeConstants.user
              ) {
                setMessageUser(item.getConversationWith() as CometChat.User);
                return;
              }
              setMessageGroup(item.getConversationWith() as CometChat.Group);
            }}
          ></CometChatConversations>
          {(messageUser || messageGroup) && (
            <CometChatMessageHeader
              user={messageUser}
              group={messageGroup}
            ></CometChatMessageHeader>
          )}
        </View>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Message List

The `CometChatMessageList` component displays the sequence of messages in a conversation, supporting text, media, reactions, and more. It includes smooth scrolling, timestamps, and grouping for better readability. Developers can customize bubble colors, text appearance, timestamps, and alignment to provide a tailored chat experience.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatConversations,
  CometChatMessageList,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          typography: {
            heading4: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          messageListStyles: {
            containerStyle: {
              backgroundColor: "#FEEDE1",
            },
            outgoingMessageBubbleStyles: {
              containerStyle: {
                backgroundColor: "#F76808",
              },
            },
          },
        },
      }}
    >
      {loggedIn && (
        <View style={{ flex: 1 }}>
          <CometChatConversations
            style={{
              containerStyle: {
                display: messageUser || messageGroup ? "none" : "flex",
              },
            }}
            onItemPress={(item: CometChat.Conversation) => {
              if (
                item.getConversationType() ==
                CometChatUiKitConstants.ConversationTypeConstants.user
              ) {
                setMessageUser(item.getConversationWith() as CometChat.User);
                return;
              }
              setMessageGroup(item.getConversationWith() as CometChat.Group);
            }}
          ></CometChatConversations>
          {(messageUser || messageGroup) && (
            <CometChatMessageList
              user={messageUser}
              group={messageGroup}
            ></CometChatMessageList>
          )}
        </View>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

#### Message Options (Long Press)

To style the action sheet that appears when long-pressing a message, use `messageOptionsStyles` within `messageListStyles`:

```javascript theme={null}
<CometChatThemeProvider
  theme={{
    light: {
      messageListStyles: {
        messageOptionsStyles: {
          optionsItemStyle: {
            containerStyle: { backgroundColor: "#FEEDE1" },
            iconStyle: { tintColor: "#F76808" },
            titleStyle: { color: "#1A1A1A" },
          },
        },
      },
    },
  }}
>
  {/* Components */}
</CometChatThemeProvider>
```

<Note>
  `messageOptionsStyles` is separate from the top-level `actionSheetStyle`. The top-level `actionSheetStyle` applies to attachment options and other standalone action sheets, while `messageOptionsStyles` specifically styles the message long-press options.
</Note>

### Message Composer

The `CometChatMessageComposer` component enables users to compose and send messages, including text, attachments, and stickers. This highly interactive component supports customization of input box styles, button appearances, and interaction feedback, ensuring it blends seamlessly with your app's chat UI.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatConversations,
  CometChatMessageComposer,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          typography: {
            heading4: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          messageComposerStyles: {
            voiceRecordingIconStyle: {
              tintColor: "#F76808",
            },
            attachmentIconStyle: {
              tintColor: "#F76808",
            },
            sendIconContainerStyle: {
              backgroundColor: "#F76808",
            },
            stickerIcon: {
              inactive: (
                <StickerIcon
                  height={24}
                  width={24}
                  color="#F76808"
                ></StickerIcon>
              ),
            },
          },
        },
      }}
    >
      {loggedIn && (
        <View style={{ flex: 1 }}>
          <CometChatConversations
            style={{
              containerStyle: {
                display: messageUser || messageGroup ? "none" : "flex",
              },
            }}
            onItemPress={(item: CometChat.Conversation) => {
              if (
                item.getConversationType() ==
                CometChatUiKitConstants.ConversationTypeConstants.user
              ) {
                setMessageUser(item.getConversationWith() as CometChat.User);
                return;
              }
              setMessageGroup(item.getConversationWith() as CometChat.Group);
            }}
          ></CometChatConversations>
          {(messageUser || messageGroup) && (
            <CometChatMessageComposer
              user={messageUser}
              group={messageGroup}
            ></CometChatMessageComposer>
          )}
        </View>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Group Members

The `CometChatGroupMembers` component lists participants in a chat group with details like names, avatars, and roles (e.g., admin or member). It supports customizable styles for list items, fonts, and background colors, ensuring it integrates with your app's group management interface.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatConversations,
  CometChatGroupMembers,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          color: {
            primary: "#F76808",
          },
          typography: {
            heading4: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          groupMemberStyle: {
            titleSeparatorStyle: {
              borderBottomColor: "#F76808",
            },
            titleStyle: {
              color: "#F76808",
            },
            backButtonIconStyle: {
              tintColor: "#F76808",
            },
          },
        },
      }}
    >
      {loggedIn && (
        <View style={{ flex: 1 }}>
          <CometChatConversations
            style={{
              containerStyle: {
                display: messageUser || messageGroup ? "none" : "flex",
              },
            }}
            conversationsRequestBuilder={new CometChat.ConversationsRequestBuilder()
              .setConversationType("group")
              .setLimit(30)}
            onItemPress={(item: CometChat.Conversation) => {
              setMessageGroup(item.getConversationWith() as CometChat.Group);
            }}
          ></CometChatConversations>
          {messageGroup && (
            <CometChatGroupMembers
              group={messageGroup!}
            ></CometChatGroupMembers>
          )}
        </View>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Thread Header

The `CometChatThreadHeader` component is used in threaded message views, displaying information about the parent message and its context. It provides a seamless way to navigate between the thread and the main conversation while maintaining context.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatThemeProvider,
  CometChatThreadHeader,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          typography: {
            heading4: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          threadHeaderStyles: {
            containerStyle: {
              backgroundColor: "#FEEDE1",
            },
            messageBubbleContainerStyle: {
              backgroundColor: "#FEEDE1",
            },
            replyCountBarStyle: {
              backgroundColor: "#FBA46B",
            },
            replyCountTextStyle: {
              color: "#FFFFFF",
            },
            outgoingMessageBubbleStyles: {
              containerStyle: {
                backgroundColor: "#F76808",
              },
            },
          },
        },
      }}
    >
      {loggedIn && (
        <View style={{ flex: 1 }}>
          <CometChatConversations
            style={{
              containerStyle: {
                display: messageUser || messageGroup ? "none" : "flex",
              },
            }}
            onItemPress={(item: CometChat.Conversation) => {
              if (
                item.getConversationType() ==
                CometChatUiKitConstants.ConversationTypeConstants.user
              ) {
                setMessageUser(item.getConversationWith() as CometChat.User);
                return;
              }
              setMessageGroup(item.getConversationWith() as CometChat.Group);
            }}
          ></CometChatConversations>
          {(messageUser || messageGroup) && !parentMessage && (
            <>
              <CometChatMessageHeader
                user={messageUser}
                group={messageGroup}
              ></CometChatMessageHeader>
              <CometChatMessageList
                user={messageUser}
                group={messageGroup}
                onThreadRepliesPress={(
                  msg: CometChat.BaseMessage,
                  view: any
                ) => {
                  setParentMessage(msg);
                }}
              ></CometChatMessageList>
              <CometChatMessageComposer
                user={messageUser}
                group={messageGroup}
              ></CometChatMessageComposer>
            </>
          )}
          {(messageUser || messageGroup) && parentMessage && (
            <CometChatThreadHeader
              parentMessage={parentMessage}
            ></CometChatThreadHeader>
          )}
        </View>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Call Logs

The `CometChatCallLogs` component provides a list of recent calls (voice or video), showing details like call type, duration, participants, and timestamps. Developers can style text, icons, and background elements, making it easy to match the app's design system.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatCallLogs,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          typography: {
            heading4: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          callLogsStyles: {
            titleSeparatorStyle: {
              borderBottomColor: "#F76808",
            },
            titleTextStyle: {
              color: "#F76808",
            },
            itemStyle: {
              avatarStyle: {
                containerStyle: {
                  borderRadius: 8,
                  backgroundColor: "#FBAA75",
                },
                imageStyle: {
                  borderRadius: 8,
                },
              },
            },
          },
        },
      }}
    >
      {loggedIn && (
        <View style={{ flex: 1 }}>
          <CometChatCallLogs></CometChatCallLogs>
        </View>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Incoming Call

The `CometChatIncomingCall` component displays a notification for an incoming call. It typically includes caller details like name, avatar, and call type (audio/video), along with buttons to accept or decline the call.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatIncomingCall,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          typography: {
            heading4: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          incomingCallStyle: {
            containerStyle: {
              backgroundColor: theme.color.extendedPrimary100,
            },
            avatarStyle: {
              containerStyle: {
                backgroundColor: theme.color.extendedPrimary500,
                borderRadius: 8,
              },
              imageStyle: {
                borderRadius: 8,
              },
            },
            declineCallButtonStyle: {
              backgroundColor: theme.color.staticWhite,
            },
            declineCallTextStyle: {
              color: theme.color.error,
            },
            acceptCallButtonStyle: {
              backgroundColor: theme.color.primary,
            },
          },
        },
      }}
    >
      {callReceived && (
        <CometChatIncomingCall
          call={incomingCall.current!}
          onDecline={(call) => {
            setCallReceived(false);
          }}
        />
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Outgoing Call

The `CometChatOutgoingCall` component displays a status view for calls initiated by the user, showing the recipient's details, call type, and call status (e.g., ringing or connecting).

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatConversations,
  CometChatMessageHeader,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          typography: {
            heading1: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          outgoingCallStyle: {
            avatarStyle: {
              containerStyle: {
                borderRadius: 8,
              },
              imageStyle: {
                borderRadius: 8,
              },
            },
            endCallButtonStyle: {
              borderRadius: 8,
            },
          },
        },
      }}
    >
      {loggedIn && (
        <View style={{ flex: 1 }}>
          <CometChatConversations
            style={{
              containerStyle: {
                display: messageUser || messageGroup ? "none" : "flex",
              },
            }}
            onItemPress={(item: CometChat.Conversation) => {
              if (
                item.getConversationType() ==
                CometChatUiKitConstants.ConversationTypeConstants.user
              ) {
                setMessageUser(item.getConversationWith() as CometChat.User);
                return;
              }
              setMessageGroup(item.getConversationWith() as CometChat.Group);
            }}
          ></CometChatConversations>
          {(messageUser || messageGroup) && (
            <CometChatMessageHeader
              user={messageUser}
              group={messageGroup}
            ></CometChatMessageHeader>
          )}
        </View>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Call Button

The `CometChatCallButton` component initiates voice or video calls with a single click. It supports various customization options for button color and icon styles, making it adaptable to different screen layouts and themes. These components further enhance the versatility of CometChat UIKit, ensuring that all aspects of messaging and calling functionality are cohesive, user-friendly, and fully customizable.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatCallButtons,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView
    style={{ flex: 1, alignItems: "center", justifyContent: "center" }}
  >
    <CometChatThemeProvider
      theme={{
        light: {
          callButtonStyles: {
            audioCallButtonIconStyle: {
              tintColor: theme.color.primary,
            },
            audioCallButtonIconContainerStyle: {
              backgroundColor: theme.color.extendedPrimary100,
              paddingHorizontal: theme.spacing.padding.p4,
              paddingVertical: theme.spacing.padding.p2,
              borderRadius: 8,
            },
            videoCallButtonIconStyle: {
              tintColor: theme.color.primary,
            },
            videoCallButtonIconContainerStyle: {
              backgroundColor: theme.color.extendedPrimary100,
              paddingHorizontal: theme.spacing.padding.p4,
              paddingVertical: theme.spacing.padding.p2,
              borderRadius: 8,
            },
          },
        },
      }}
    >
      {loggedIn && <CometChatCallButtons></CometChatCallButtons>}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### AI Assistant Chat History

The `CometChatAIAssistantChatHistory` component displays the history of interactions with an AI assistant. It provides a seamless way to view past conversations, ensuring users can easily reference previous AI responses.

<Frame>
  <img alt="AI assistant chat history styling preview" />
</Frame>

```javascript theme={null}
import {
  CometChatAIAssistantChatHistory,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          typography: {
            heading4: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          chatHistoryStyles: {
            containerStyle: {
              backgroundColor: '#FFFAF6',
            },
            headerStyle: {
              backgroundColor: '#FFFAF6',
            },
            headerTitleStyle: {
              color: '#F76808',
            },
            newChatButtonStyle: {
              backgroundColor: '#FEEDE1',
            },
            newChatTextStyle: {
              color: '#F76808',
            },
            sectionHeaderStyle: {
              backgroundColor: '#FFFAF6',
            },
            sectionHeaderTextStyle: {
              color: '#888888',
            },
            messageItemStyle: {
              backgroundColor: '#FFFAF6',
            },
            messageTextStyle: {
              color: '#333333',
            },
          },
        },
      }}
    >
      {loggedIn && (
        <CometChatAIAssistantChatHistory
          user={selectedUser}
          onItemClick={(conversation) => {
            // Handle chat history item click
            console.log('Chat history item clicked:', conversation);
          }}
          onNewChatButtonClick={() => {
            // Handle new chat button click
            console.log('New chat button clicked');
          }}
        />
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

## Base Components

### Avatar

The `CometChatAvatar` component is used across the UIKit to represent users, groups, or placeholders visually. This highly reusable component supports various shapes (circle or square), sizes, borders, and fallback icons, allowing complete design consistency for profile or group images.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatAvatar,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView
    style={{ flex: 1, alignItems: "center", justifyContent: "center" }}
  >
    <CometChatThemeProvider
      theme={{
        light: {
          avatarStyles: {
            containerStyle: {
              borderRadius: 8,
              backgroundColor: "#FBAA75",
            },
            imageStyle: {
              borderRadius: 8,
            },
          },
        },
      }}
    >
      {loggedIn && (
        <CometChatAvatar
          name="Some Name"
          image=":ImageSourcePropType"
        ></CometChatAvatar>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Status Indicator

The `CometChatStatusIndicator` component visually represents user presence (online, offline, or custom states). It can be styled for different shapes, sizes, and colors to reflect your app's visual preferences while maintaining clarity in conveying status information.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatStatusIndicator,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView
    style={{ flex: 1, alignItems: "center", justifyContent: "center" }}
  >
    <CometChatThemeProvider
      theme={{
        light: {
          statusIndicatorStyles: {
            containerStyleOnline: {
              backgroundColor: "#FFAB00",
            },
          },
        },
      }}
    >
      {loggedIn && (
        <CometChatStatusIndicator
          style={{
            containerStyle: {
              position: "relative",
              borderRadius: 2,
            },
          }}
          type={CometChatUiKitConstants.USER_ONLINE_STATUS}
        ></CometChatStatusIndicator>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Badge

The `CometChatBadge` component displays notifications or counts, such as unread messages. It can be styled for background colors, border radius, text size, and colors, allowing you to create visually distinct indicators for different notifications.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatBadge,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView
    style={{ flex: 1, alignItems: "center", justifyContent: "center" }}
  >
    <CometChatThemeProvider
      theme={{
        light: {
          badgeStyles: {
            containerStyle: {
              borderRadius: 4,
              backgroundColor: theme.color.error,
            },
          },
        },
      }}
    >
      {loggedIn && <CometChatBadge count={244}></CometChatBadge>}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Date

The `CometChatDate` component formats and displays timestamps in conversation lists and message threads. It ensures time-related information is clear and consistent. Developers can customize its text appearance, alignment, and colors to fit various contexts.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatDate,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView
    style={{ flex: 1, alignItems: "center", justifyContent: "center" }}
  >
    <CometChatThemeProvider
      theme={{
        light: {
          dateStyles: {
            textStyle: {
              color: "#141414",
            },
          },
        },
      }}
    >
      {loggedIn && (
        <CometChatDate
          timeStamp={Date.now()}
          pattern={"dayDateTimeFormat"}
        ></CometChatDate>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Receipts

The `CometChatReceipts` component indicates message delivery and read statuses using intuitive icons. These can be styled for icon size, tint, and alignment, ensuring they remain clear and consistent with your app's UI.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatReceipt,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView
    style={{ flex: 1, alignItems: "center", justifyContent: "center" }}
  >
    <CometChatThemeProvider
      theme={{
        light: {
          receiptStyles: {
            readIconStyle: {
              tintColor: "#FFAB00",
            },
          },
        },
      }}
    >
      {loggedIn && (
        <CometChatReceipt
          receipt={CometChatUiKitConstants.MessageReceipt.READ}
        ></CometChatReceipt>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Media Recorder

The `CometChatMediaRecorder` component facilitates the recording of audio and video messages. It supports full customization of its recording controls, including button sizes, shapes, and colors, making it an integral part of your media-rich chat experience.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatMediaRecorder,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView
    style={{ flex: 1, alignItems: "center", justifyContent: "center" }}
  >
    <CometChatThemeProvider
      theme={{
        light: {
          mediaRecorderStyle: {
            animationStyle: {
              innerAnimationContainerStyle: {
                backgroundColor: "#EDEAFA",
                borderRadius: 20,
              },
              outerAnimationContainerStyle: {
                backgroundColor: "#F9F8FD",
                borderRadius: 20,
              },
              animatedIconStyle: {
                containerStyle: {
                  borderRadius: 20,
                  backgroundColor: "#F44649",
                },
              },
            },
            pauseIconStyle: {
              containerStyle: {
                height: 60,
                width: 60,
                borderRadius: 8,
                alignItems: "center",
                justifyContent: "center",
              },
            },
            deleteIconStyle: {
              containerStyle: {
                borderRadius: 8,
              },
            },
            stopIconStyle: {
              containerStyle: {
                borderRadius: 8,
              },
            },
          },
        },
      }}
    >
      {loggedIn && <CometChatMediaRecorder></CometChatMediaRecorder>}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Reaction List

The `CometChatReactionList` component provides a visual representation of emoji reactions on messages. It supports customization for reaction sizes, spacing, and colors, enabling you to build an engaging and personalized messaging environment.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatReactionList,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView
    style={{ flex: 1, alignItems: "center", justifyContent: "center" }}
  >
    <CometChatThemeProvider
      theme={{
        light: {
          color: {
            primary: "#F76808",
          },
          reactionListStyles: {
            tabStyle: {
              selectedItemStyle: {
                borderBottomColor: "#F76808",
              },
              selectedItemTextStyle: {
                color: "#F76808",
              },
            },
          },
        },
      }}
    >
      {loggedIn && <CometChatReactionList message={messageWithReactions} />}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Message Information

The `CometChatMessageInformation` component displays metadata for messages, such as delivery timestamps, sender details, and read receipts. Customization options include text styles, colors, and alignment, making it adaptable to various app layouts.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatMessageInformation,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          color: {
            primary: "#F76808",
          },
          typography: {
            heading4: {
              bold: {
                fontFamily: "TimesNewRoman-Bold",
              },
              medium: {
                fontFamily: "TimesNewRoman",
              },
              regular: {
                fontFamily: "TimesNewRoman",
              },
            },
          },
          messageInformationStyles: {
            titleStyle: {
              color: "#F76808",
            },
            messageBubbleContainerStyle: {
              backgroundColor: "#FEEDE1",
            },
          },
        },
      }}
    >
      {loggedIn && (
        <CometChatMessageInformation message={messageWithReactions} />
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Bottom Sheet

The `CometChatBottomSheet` component is a wrapper around the React Native Modal that provides a bottom sheet experience. While the Modal component offers basic functionality for displaying content in a popup overlay, `CometChatBottomSheet` enhances this by offering features like smooth slide-in animations and a background overlay. It picks up most of its styling from the theme, ensuring a consistent design with minimal configuration. This component simplifies the implementation of bottom sheet interactions.

```javascript theme={null}
import {
  CometChatBottomSheet,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView
    style={{ flex: 1, alignItems: "center", justifyContent: "center" }}
  >
    <CometChatThemeProvider>
      {loggedIn && (
        <CometChatBottomSheet
          style={{
            minHeight: Dimensions.get("screen").height * 0.3,
          }}
          doNotOccupyEntireHeight={true}
        >
          {/*child component*/}
        </CometChatBottomSheet>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

### Action Sheet

The `CometChatActionSheet` component is a customizable action sheet designed to display a list of actionable options. Often integrated with the [CometChatBottomSheet](/docs/ui-kit/react-native/component-styling#bottom-sheet), it provides a structured and interactive menu for user actions.

```javascript theme={null}
import {
  CometChatBottomSheet,
  CometChatActionSheet,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView
    style={{ flex: 1, alignItems: "center", justifyContent: "center" }}
  >
    <CometChatThemeProvider
      theme={{
        light: {
          actionSheetStyle: {
            optionsItemStyle: {
              containerStyle: {
                backgroundColor: "yellow",
              },
            },
          },
        },
      }}
    >
      {loggedIn && (
        <CometChatBottomSheet
          style={{
            minHeight: Dimensions.get("screen").height * 0.3,
          }}
          doNotOccupyEntireHeight={true}
        >
          <CometChatActionSheet
            actions={[
              {
                id: "1",
                title: "First Option",
                onPress: () => {
                  console.log("First Option Pressed");
                },
              },
            ]}
          ></CometChatActionSheet>
        </CometChatBottomSheet>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Mentions

The `CometChatMentions` component highlights referenced users or groups within messages. With customizable styles for text color and background, you can ensure mentions stand out clearly in chats while maintaining a cohesive visual theme.

<Frame>
  <img />
</Frame>

```javascript theme={null}
import {
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { SafeAreaView } from "react-native-safe-area-context";

//code
return (
  <SafeAreaView style={{ flex: 1 }}>
    <CometChatThemeProvider
      theme={{
        light: {
          messageListStyles: {
            incomingMessageBubbleStyles: {
              textBubbleStyles: {
                mentionsStyle: {
                  textStyle: {
                    color: "#D6409F",
                  },
                  selfTextStyle: {
                    color: "#30A46C",
                  },
                },
              },
            },
            outgoingMessageBubbleStyles: {
              textBubbleStyles: {
                mentionsStyle: {
                  textStyle: {
                    color: "#D6409F",
                  },
                  selfTextStyle: {
                    color: "#30A46C",
                  },
                },
              },
            },
          },
        },
      }}
    >
      {loggedIn && (
        <View style={{ flex: 1 }}>
          <CometChatConversations
            style={{
              containerStyle: {
                display: messageUser || messageGroup ? "none" : "flex",
              },
            }}
            onItemPress={(item: CometChat.Conversation) => {
              if (
                item.getConversationType() ==
                CometChatUiKitConstants.ConversationTypeConstants.user
              ) {
                setMessageUser(item.getConversationWith() as CometChat.User);
                return;
              }
              setMessageGroup(item.getConversationWith() as CometChat.Group);
            }}
          ></CometChatConversations>
          {(messageUser || messageGroup) && (
            <>
              <CometChatMessageHeader
                user={messageUser}
                group={messageGroup}
              ></CometChatMessageHeader>
              <CometChatMessageList
                user={messageUser}
                group={messageGroup}
              ></CometChatMessageList>
              <CometChatMessageComposer
                user={messageUser}
                group={messageGroup}
              ></CometChatMessageComposer>
            </>
          )}
        </View>
      )}
    </CometChatThemeProvider>
  </SafeAreaView>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

***

## Next Steps

<CardGroup>
  <Card title="Introduction to Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Learn how CometChatThemeProvider manages light and dark modes
  </Card>

  <Card title="Colors" icon="palette" href="/ui-kit/react-native/colors">
    Customize primary, neutral, alert, and other color tokens
  </Card>

  <Card title="Message Bubble Styling" icon="message" href="/ui-kit/react-native/message-bubble-styling">
    Style individual message bubbles and their content
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Explore all available UI Kit components
  </Card>
</CardGroup>


# Overview
Source: https://www.cometchat.com/docs/ui-kit/react-native/components-overview

Browse all prebuilt UI components in the CometChat React Native UI Kit — conversations, messages, users, groups, calls, and AI.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                             |
  | ---------------- | --------------------------------------------------------------------------------- |
  | Package          | `@cometchat/chat-uikit-react-native`                                              |
  | Required setup   | `CometChatUIKit.init()` + `CometChatUIKit.login()` before rendering any component |
  | Callback actions | `on<Event>={(param) => {}}` (e.g., `onItemPress`)                                 |
  | Data filtering   | `<entity>RequestBuilder={new CometChat.<Entity>RequestBuilder()}`                 |
  | Toggle features  | `hide<Feature>={true}` or `<feature>Visibility={false}`                           |
  | Custom rendering | `<Slot>View={(<params>) => JSX}` (PascalCase)                                     |
  | Style overrides  | `style={{ containerStyle: {}, itemStyle: {} }}`                                   |
  | Calling          | Requires separate `@cometchat/calls-sdk-react-native` package                     |
</Accordion>

## Architecture

The UI Kit is a set of independent components that compose into chat layouts. A typical two-panel layout uses four core components:

* **CometChatConversations** — sidebar listing recent conversations (users and groups)
* **CometChatMessageHeader** — toolbar showing avatar, name, online 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 in CometChatConversations yields a `CometChat.Conversation` object. Extract the `User` or `Group` via `getConversationWith()` and pass it as a prop to CometChatMessageHeader, CometChatMessageList, and CometChatMessageComposer.

Components communicate through a publish/subscribe event bus (`CometChatUIEventHandler`). A component emits events that other components or application code can subscribe to without direct references. See [Events](/docs/ui-kit/react-native/events) for the full list.

Each component accepts callback props (`on<Event>`), view slot props (`<Slot>View`) for replacing UI sections, `RequestBuilder` props for data filtering, and `style` props for customization.

***

## Component Catalog

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

### Conversations and Lists

| Component              | Purpose                                 | Key Props                                               | Page                                                |
| ---------------------- | --------------------------------------- | ------------------------------------------------------- | --------------------------------------------------- |
| CometChatConversations | Scrollable list of recent conversations | `conversationsRequestBuilder`, `onItemPress`, `onError` | [Conversations](/docs/ui-kit/react-native/conversations) |
| CometChatUsers         | Scrollable list of users                | `usersRequestBuilder`, `onItemPress`, `onError`         | [Users](/docs/ui-kit/react-native/users)                 |
| CometChatGroups        | Scrollable list of groups               | `groupsRequestBuilder`, `onItemPress`, `onError`        | [Groups](/docs/ui-kit/react-native/groups)               |
| CometChatGroupMembers  | Scrollable list of group members        | `group`, `groupMemberRequestBuilder`, `onItemPress`     | [Group Members](/docs/ui-kit/react-native/group-members) |

### Messages

| Component                       | Purpose                                                                                | Key Props                                                    | Page                                                                      |
| ------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------- |
| CometChatMessageHeader          | Toolbar with avatar, name, status, typing indicator                                    | `user`, `group`, `showBackButton`                            | [Message Header](/docs/ui-kit/react-native/message-header)                     |
| CometChatMessageList            | Scrollable message list with reactions, receipts, threads                              | `user`, `group`, `messageRequestBuilder`, `goToMessageId`    | [Message List](/docs/ui-kit/react-native/message-list)                         |
| CometChatMessageComposer        | Rich text input with attachments, mentions, voice notes                                | `user`, `group`, `onSendButtonPress`, `placeholderText`      | [Message Composer](/docs/ui-kit/react-native/message-composer)                 |
| CometChatCompactMessageComposer | Compact message input with rich text formatting, auto-expanding input, and attachments | `user`, `group`, `onSendButtonPress`, `enableRichTextEditor` | [Compact Message Composer](/docs/ui-kit/react-native/compact-message-composer) |
| CometChatThreadHeader           | Parent message bubble and reply count for threaded view                                | `parentMessage`, `onClose`                                   | [Thread Header](/docs/ui-kit/react-native/threaded-messages-header)            |

### Calling

| Component             | Purpose                                        | Key Props                                               | Page                                                |
| --------------------- | ---------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------- |
| CometChatCallButtons  | Voice and video call initiation buttons        | `user`, `group`, `onVoiceCallPress`, `onVideoCallPress` | [Call Buttons](/docs/ui-kit/react-native/call-buttons)   |
| CometChatIncomingCall | Incoming call notification with accept/decline | `call`, `onAccept`, `onDecline`                         | [Incoming Call](/docs/ui-kit/react-native/incoming-call) |
| CometChatOutgoingCall | Outgoing call screen with cancel control       | `call`, `onClosePress`                                  | [Outgoing Call](/docs/ui-kit/react-native/outgoing-call) |
| CometChatCallLogs     | Scrollable list of call history                | `callLogsRequestBuilder`, `onItemPress`                 | [Call Logs](/docs/ui-kit/react-native/call-logs)         |

### AI

| Component                       | Purpose                           | Key Props                                          | Page                                                                        |
| ------------------------------- | --------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------- |
| CometChatAIAssistantChatHistory | AI assistant conversation history | `user`, `onMessageClicked`, `onNewChatButtonClick` | [AI Assistant Chat History](/docs/ui-kit/react-native/ai-assistant-chat-history) |

***

## Component API Pattern

All components share a consistent API surface.

### Actions

Actions control component behavior. They split into two categories:

**Predefined Actions** are built into the component and execute automatically on user interaction (e.g., tapping send dispatches the message). No configuration needed.

**User-Defined Actions** are callback props that fire on specific events. Override them to customize behavior:

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

### Events

Events enable decoupled communication between components. A component emits events that other parts of the application can subscribe to without direct references.

```tsx lines theme={null}
import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";

useEffect(() => {
  const listenerId = "MESSAGE_LISTENER_" + Date.now();
  
  CometChatUIEventHandler.addMessageListener(listenerId, {
    ccMessageSent: ({ message }) => {
      console.log("Message sent:", message);
    },
  });

  return () => {
    CometChatUIEventHandler.removeMessageListener(listenerId);
  };
}, []);
```

Each component page documents its emitted events in the Events section.

### Filters

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

```tsx lines theme={null}
<CometChatMessageList
  user={chatUser}
  messageRequestBuilder={
    new CometChat.MessagesRequestBuilder().setLimit(20)
  }
/>
```

### Custom View Slots

Components expose named view slots (PascalCase) to replace sections of the default UI:

```tsx lines theme={null}
<CometChatMessageHeader
  user={chatUser}
  TitleView={(user, group) => <CustomTitle />}
  SubtitleView={(user, group) => <CustomSubtitle />}
  LeadingView={(user, group) => <CustomAvatar />}
/>
```

### Style Overrides

Every component accepts a `style` prop for customization:

```tsx lines theme={null}
<CometChatConversations
  style={{
    containerStyle: { backgroundColor: "#FAFAFA" },
    itemStyle: {
      avatarStyle: { containerStyle: { borderRadius: 8 } },
    },
  }}
/>
```

<Tip>
  All default icons are implemented as SVGs.

  For these icons, only the following imageStyle properties are supported:

  * tintColor
  * height
  * width

  Any extra properties provided in imageStyle will be ignored for default icons.

  For custom icons, you can provide either JSX components or an ImageSourcePropType. JSX Components are rendered as-is with no additional styles applied. ImageSourcePropType (e.g., PNG, JPEG) will have the entire imageStyle applied as expected.
</Tip>

***

## Next Steps

<CardGroup>
  <Card title="Core Features" icon="comments" href="/ui-kit/react-native/core-features">
    Chat features included out of the box
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and styles
  </Card>

  <Card title="Extensions" icon="puzzle-piece" href="/ui-kit/react-native/extensions">
    Add-on features like polls, stickers, and translation
  </Card>

  <Card title="Methods" icon="code" href="/ui-kit/react-native/methods">
    Initialize, authenticate, and send messages
  </Card>
</CardGroup>


# Conversations
Source: https://www.cometchat.com/docs/ui-kit/react-native/conversations

Display CometChat React Native UI Kit conversations with last messages, unread counts, typing indicators, presence, and callbacks.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatConversations",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatConversations } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Scrollable list of recent one-on-one and group conversations for the logged-in user.",
    "primaryOutput": {
      "prop": "onItemPress",
      "type": "(conversation: CometChat.Conversation) => void"
    },
    "props": {
      "data": {
        "conversationsRequestBuilder": {
          "type": "CometChat.ConversationsRequestBuilder",
          "default": "SDK default (30 per page)",
          "note": "Pass the builder, not the result of .build()"
        },
        "datePattern": {
          "type": "(conversation: CometChat.Conversation) => string",
          "note": "Custom function to format conversation timestamps"
        }
      },
      "callbacks": {
        "onItemPress": "(conversation: CometChat.Conversation) => void",
        "onItemLongPress": "(conversation: CometChat.Conversation) => void",
        "onBack": "() => void",
        "onSelection": "(conversations: Array<CometChat.Conversation>) => void",
        "onError": "(error: CometChat.CometChatException) => void",
        "onEmpty": "() => void",
        "onLoad": "(list: CometChat.Conversation[]) => void",
        "onSearchBarClicked": "() => void",
        "onSearchTextChanged": "(searchText: string) => void",
        "onSubmit": "(conversations: Array<CometChat.Conversation>) => void"
      },
      "visibility": {
        "hideBackButton": { "type": "boolean", "default": true },
        "hideHeader": { "type": "boolean", "default": false },
        "hideError": { "type": "boolean", "default": false },
        "receiptsVisibility": { "type": "boolean", "default": true },
        "hideSubmitButton": { "type": "boolean", "default": true },
        "usersStatusVisibility": { "type": "boolean", "default": true },
        "groupTypeVisibility": { "type": "boolean", "default": true },
        "deleteConversationOptionVisibility": { "type": "boolean", "default": true },
        "showSearchBar": { "type": "boolean", "default": false },
        "searchText": { "type": "string", "default": "\"\"" }
      },
      "sound": {
        "disableSoundForMessages": { "type": "boolean", "default": false },
        "customSoundForMessages": { "type": "audio source", "default": "built-in" }
      },
      "selection": {
        "selectionMode": {
          "type": "SelectionMode",
          "values": ["single", "multiple", "none"],
          "default": "none"
        }
      },
      "viewSlots": {
        "ItemView": "(conversation: CometChat.Conversation) => JSX.Element",
        "LeadingView": "(conversation: CometChat.Conversation) => JSX.Element",
        "TitleView": "(conversation: CometChat.Conversation) => JSX.Element",
        "SubtitleView": "(conversation: CometChat.Conversation) => JSX.Element",
        "TrailingView": "(conversation: CometChat.Conversation) => JSX.Element",
        "LoadingView": "() => JSX.Element",
        "EmptyView": "() => JSX.Element",
        "ErrorView": "() => JSX.Element",
        "AppBarOptions": "() => JSX.Element",
        "SearchView": "() => JSX.Element"
      },
      "formatting": {
        "textFormatters": {
          "type": "CometChatTextFormatter[]",
          "default": "default formatters from data source"
        }
      }
    },
    "events": [
      {
        "name": "ccConversationDeleted",
        "payload": "CometChat.Conversation",
        "description": "Conversation deleted from list"
      }
    ],
    "sdkListeners": [
      "onTextMessageReceived",
      "onMediaMessageReceived",
      "onCustomMessageReceived",
      "onTypingStarted",
      "onTypingEnded",
      "onMessagesDelivered",
      "onMessagesRead",
      "onUserOnline",
      "onUserOffline",
      "onGroupMemberJoined",
      "onGroupMemberLeft",
      "onGroupMemberKicked",
      "onGroupMemberBanned",
      "onMemberAddedToGroup"
    ],
    "compositionExample": {
      "description": "Navigation-based conversations wired to message view",
      "components": [
        "CometChatConversations",
        "CometChatMessageHeader",
        "CometChatMessageList",
        "CometChatMessageComposer"
      ],
      "flow": "onItemPress emits CometChat.Conversation -> extract User/Group via getConversationWith() -> navigate to Messages screen with user or group prop"
    },
    "types": {
      "SelectionMode": {
        "single": "Select one conversation at a time",
        "multiple": "Select multiple conversations",
        "none": "No selection mode"
      }
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatConversations` is a sidebar list component. It renders recent conversations and emits the selected `CometChat.Conversation` via `onItemPress`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a standard chat layout.

```tsx lines theme={null}
import { useState } from "react";
import { View, Text, StyleSheet } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { SafeAreaProvider } from "react-native-safe-area-context";
import {
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ChatApp() {
  const [selectedUser, setSelectedUser] = useState<CometChat.User>();
  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group>();

  const handleItemPress = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (entity instanceof CometChat.User) {
      setSelectedUser(entity);
      setSelectedGroup(undefined);
    } else if (entity instanceof CometChat.Group) {
      setSelectedGroup(entity);
      setSelectedUser(undefined);
    }
  };

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <SafeAreaProvider>
        <CometChatThemeProvider>
          <View style={styles.container}>
            <View style={styles.sidebar}>
              <CometChatConversations onItemPress={handleItemPress} />
            </View>
            {selectedUser || selectedGroup ? (
              <View style={styles.chatArea}>
                <CometChatMessageHeader user={selectedUser} group={selectedGroup} />
                <CometChatMessageList user={selectedUser} group={selectedGroup} />
                <CometChatMessageComposer user={selectedUser} group={selectedGroup} />
              </View>
            ) : (
              <View style={styles.placeholder}>
                <Text>Select a conversation</Text>
              </View>
            )}
          </View>
        </CometChatThemeProvider>
      </SafeAreaProvider>
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, flexDirection: "row" },
  sidebar: { width: 350 },
  chatArea: { flex: 1 },
  placeholder: { flex: 1, justifyContent: "center", alignItems: "center" },
});
```

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";

function ConversationsDemo() {
  return <CometChatConversations />;
}

export default ConversationsDemo;
```

***

## Filtering Conversations

Pass a `CometChat.ConversationsRequestBuilder` to `conversationsRequestBuilder`. Pass the builder instance — not the result of `.build()`.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function FilteredConversations() {
  return (
    <CometChatConversations
      conversationsRequestBuilder={
        new CometChat.ConversationsRequestBuilder()
          .setConversationType("user")
          .setLimit(10)
      }
    />
  );
}
```

### Filter Recipes

| Recipe                   | Code                                                                                               |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| Only user conversations  | `new CometChat.ConversationsRequestBuilder().setConversationType("user")`                          |
| Only group conversations | `new CometChat.ConversationsRequestBuilder().setConversationType("group")`                         |
| Limit to 10 per page     | `new CometChat.ConversationsRequestBuilder().setLimit(10)`                                         |
| With specific tags       | `new CometChat.ConversationsRequestBuilder().setTags(["vip"])`                                     |
| Filter by user tags      | `new CometChat.ConversationsRequestBuilder().withUserAndGroupTags(true).setUserTags(["premium"])`  |
| Filter by group tags     | `new CometChat.ConversationsRequestBuilder().withUserAndGroupTags(true).setGroupTags(["support"])` |

Default page size is 30. The component uses infinite scroll — the next page loads as the user scrolls to the bottom.

Refer to [ConversationRequestBuilder](/docs/sdk/react-native/retrieve-conversations) for the full builder API.

***

## Actions and Events

### Callback Props

#### onItemPress

Fires when a conversation row is tapped. Primary navigation hook — set the active conversation and render the message view.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ConversationsWithPress() {
  const handleItemPress = (conversation: CometChat.Conversation) => {
    console.log("Selected:", conversation.getConversationId());
  };

  return <CometChatConversations onItemPress={handleItemPress} />;
}
```

#### onItemLongPress

Fires when a conversation item is long-pressed, allowing additional actions like delete or select.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ConversationsWithLongPress() {
  const handleLongPress = (conversation: CometChat.Conversation) => {
    console.log("Long pressed:", conversation.getConversationId());
  };

  return <CometChatConversations onItemLongPress={handleLongPress} />;
}
```

#### onSelection

Fires when conversations are selected/deselected in selection mode. Requires `selectionMode` to be set.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ConversationsWithSelection() {
  const handleSelection = (conversations: Array<CometChat.Conversation>) => {
    console.log("Selected:", conversations.length);
  };

  return (
    <CometChatConversations
      selectionMode="multiple"
      onSelection={handleSelection}
    />
  );
}
```

#### onError

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

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ConversationsWithErrorHandler() {
  return (
    <CometChatConversations
      onError={(error: CometChat.CometChatException) => {
        console.error("CometChatConversations error:", error);
      }}
    />
  );
}
```

#### onEmpty

Fires when the conversation list is empty.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";

function ConversationsWithEmptyHandler() {
  return (
    <CometChatConversations
      onEmpty={() => console.log("No conversations")}
    />
  );
}
```

#### onLoad

Fires when the list is successfully fetched and loaded.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ConversationsWithLoadHandler() {
  const handleLoad = (list: CometChat.Conversation[]) => {
    console.log("Conversations loaded:", list.length);
  };

  return <CometChatConversations onLoad={handleLoad} />;
}
```

### Global UI Events

`CometChatUIEventHandler` emits events subscribable from anywhere in the application. Subscribe in a `useEffect` and unsubscribe on cleanup.

| Event                   | Fires when                              | Payload                  |
| ----------------------- | --------------------------------------- | ------------------------ |
| `ccConversationDeleted` | A conversation is deleted from the list | `CometChat.Conversation` |

When to use: sync external UI with conversation state changes. For example, update an unread count badge in a tab bar when a conversation is deleted, or remove a conversation from a custom sidebar.

```tsx lines theme={null}
import { useEffect } from "react";
import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function useConversationEvents() {
  useEffect(() => {
    const listenerId = "CONVERSATION_EVENTS_" + Date.now();
    
    CometChatUIEventHandler.addConversationListener(listenerId, {
      ccConversationDeleted: (conversation: CometChat.Conversation) => {
        console.log("Deleted:", conversation.getConversationId());
      },
    });

    return () => {
      CometChatUIEventHandler.removeConversationListener(listenerId);
    };
  }, []);
}
```

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual attachment needed unless additional side effects are required.

| SDK Listener                                                                                                         | Internal behavior                                                          |
| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived`                                       | Moves conversation to top, updates last message preview and unread count   |
| `onTypingStarted` / `onTypingEnded`                                                                                  | Shows/hides typing indicator in the subtitle                               |
| `onMessagesDelivered` / `onMessagesRead`                                                                             | Updates receipt ticks (unless `receiptsVisibility={false}`)                |
| `onUserOnline` / `onUserOffline`                                                                                     | Updates online/offline status dot (unless `usersStatusVisibility={false}`) |
| `onGroupMemberJoined` / `onGroupMemberLeft` / `onGroupMemberKicked` / `onGroupMemberBanned` / `onMemberAddedToGroup` | Updates group conversation metadata                                        |

Automatic: new messages, typing indicators, receipts, user presence, group membership changes.

Manual: deleting a conversation via the SDK directly (not through the component's context menu) requires emitting `ccConversationDeleted` for the UI to update.

***

## Custom View Slots

Each slot replaces a section of the default UI. Slots that accept a conversation parameter receive the `CometChat.Conversation` object for that row.

| Slot            | Signature                                               | Replaces                          |
| --------------- | ------------------------------------------------------- | --------------------------------- |
| `ItemView`      | `(conversation: CometChat.Conversation) => JSX.Element` | Entire list item row              |
| `LeadingView`   | `(conversation: CometChat.Conversation) => JSX.Element` | Avatar / left section             |
| `TitleView`     | `(conversation: CometChat.Conversation) => JSX.Element` | Name / title text                 |
| `SubtitleView`  | `(conversation: CometChat.Conversation) => JSX.Element` | Last message preview              |
| `TrailingView`  | `(conversation: CometChat.Conversation) => JSX.Element` | Timestamp / badge / right section |
| `LoadingView`   | `() => JSX.Element`                                     | Loading spinner                   |
| `EmptyView`     | `() => JSX.Element`                                     | Empty state                       |
| `ErrorView`     | `() => JSX.Element`                                     | Error state                       |
| `AppBarOptions` | `() => JSX.Element`                                     | Header bar options                |
| `SearchView`    | `() => JSX.Element`                                     | Search bar                        |

### ItemView

Replace the entire list item row.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import {
  CometChatConversations,
  CometChatAvatar,
  useTheme,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function CustomItemViewConversations() {
  const theme = useTheme();

  const getItemView = (conversation: CometChat.Conversation) => {
    const conversationWith = conversation.getConversationWith();
    return (
      <View
        style={{
          flexDirection: "row",
          flex: 1,
          paddingHorizontal: 16,
          paddingVertical: 12,
          alignItems: "center",
          borderWidth: 1,
          borderColor: theme.color.borderLight,
        }}>
        <CometChatAvatar
          name={conversationWith.getName()}
          image={{
            uri:
              conversationWith instanceof CometChat.User
                ? conversationWith.getAvatar()
                : conversationWith.getIcon(),
          }}
          style={{
            containerStyle: { borderRadius: 8 },
            imageStyle: { borderRadius: 8 },
          }}
        />
        <Text
          style={{
            flex: 1,
            color: theme.color.textPrimary,
            fontSize: 16,
            marginLeft: 12,
            fontWeight: "500",
          }}
          numberOfLines={1}
          ellipsizeMode="tail">
          {conversationWith.getName()}
        </Text>
      </View>
    );
  };

  return <CometChatConversations ItemView={getItemView} />;
}
```

### LeadingView

Replace the avatar / left section.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function LeadingViewConversations() {
  const getLeadingView = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    return (
      <View
        style={{
          width: 40,
          height: 40,
          borderRadius: 20,
          backgroundColor: "#6852D6",
          justifyContent: "center",
          alignItems: "center",
        }}>
        <Text style={{ color: "white", fontWeight: "bold" }}>
          {entity.getName().charAt(0)}
        </Text>
      </View>
    );
  };

  return <CometChatConversations LeadingView={getLeadingView} />;
}
```

### TrailingView

Replace the timestamp / badge / right section.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function TrailingViewConversations() {
  const getTrailingView = (conversation: CometChat.Conversation) => {
    const unreadCount = conversation.getUnreadMessageCount();
    if (unreadCount === 0) return null;
    
    return (
      <View
        style={{
          backgroundColor: "#F76808",
          borderRadius: 10,
          paddingHorizontal: 8,
          paddingVertical: 4,
        }}>
        <Text style={{ color: "white", fontSize: 12, fontWeight: "bold" }}>
          {unreadCount}
        </Text>
      </View>
    );
  };

  return <CometChatConversations TrailingView={getTrailingView} />;
}
```

### TitleView

Replace the name / title text.

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function TitleViewConversations() {
  const getTitleView = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    const isUser = entity instanceof CometChat.User;
    
    return (
      <View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
        <Text style={{ fontWeight: "bold", fontSize: 16 }}>
          {entity.getName()}
        </Text>
        {isUser && (entity as CometChat.User).getStatus() === "online" && (
          <View
            style={{
              width: 8,
              height: 8,
              borderRadius: 4,
              backgroundColor: "#09C26F",
            }}
          />
        )}
      </View>
    );
  };

  return <CometChatConversations TitleView={getTitleView} />;
}
```

### SubtitleView

Replace the last message preview text.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { Text } from "react-native";

function SubtitleViewConversations() {
  const getSubtitleView = (conversation: CometChat.Conversation) => {
    const conversationWith = conversation.getConversationWith();
    if (conversationWith instanceof CometChat.User) {
      return (
        <Text style={{ fontSize: 12, color: "#727272" }}>
          Last Active: {new Date(conversationWith.getLastActiveAt() * 1000).toLocaleString()}
        </Text>
      );
    } else if (conversationWith instanceof CometChat.Group) {
      return (
        <Text style={{ fontSize: 12, color: "#727272" }}>
          {conversationWith.getMembersCount()} members
        </Text>
      );
    }
    return null;
  };

  return <CometChatConversations SubtitleView={getSubtitleView} />;
}
```

### AppBarOptions

Custom view for the header bar options.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { TouchableOpacity, Text } from "react-native";

function AppBarOptionsConversations() {
  return (
    <CometChatConversations
      AppBarOptions={() => (
        <TouchableOpacity onPress={() => console.log("Settings pressed")}>
          <Text style={{ color: "#6852D6", fontWeight: "500" }}>Settings</Text>
        </TouchableOpacity>
      )}
    />
  );
}
```

### options

Custom context menu actions for each conversation item.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function OptionsConversations() {
  const getOptions = (conversation: CometChat.Conversation) => [
    {
      text: "Delete",
      onPress: () => console.log("Delete:", conversation.getConversationId()),
      textStyle: { color: "red" },
    },
    {
      text: "Mute",
      onPress: () => console.log("Mute:", conversation.getConversationId()),
    },
  ];

  return <CometChatConversations options={getOptions} />;
}
```

### addOptions

Extends the default context menu actions with additional options.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function AddOptionsConversations() {
  const addOptions = (conversation: CometChat.Conversation) => [
    {
      text: "Archive",
      onPress: () => console.log("Archive:", conversation.getConversationId()),
    },
    {
      text: "Pin",
      onPress: () => console.log("Pin:", conversation.getConversationId()),
    },
  ];

  return <CometChatConversations addOptions={addOptions} />;
}
```

### datePattern

Custom date format for displaying timestamps.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import {
  CometChatConversations,
  CometChatConversationUtils,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function DatePatternConversations() {
  const generateDateString = (conversation: CometChat.Conversation) => {
    const lastMessage = CometChatConversationUtils.getLastMessage(conversation);
    const conversationWith = conversation.getConversationWith();
    const days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
    const timeStamp = lastMessage?.updatedAt || conversationWith.createdAt;
    const date = new Date(timeStamp * 1000);
    const day = days[date.getUTCDay()];
    const hours = date.getUTCHours();
    const minutes = String(date.getUTCMinutes()).padStart(2, "0");
    return `${day}, ${hours}:${minutes}`;
  };

  return <CometChatConversations datePattern={generateDateString} />;
}
```

### textFormatters

Custom text formatters for the conversation subtitle.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import {
  CometChatConversations,
  CometChatTextFormatter,
  CometChatMentionsFormatter,
} from "@cometchat/chat-uikit-react-native";

function TextFormattersConversations() {
  const getTextFormatters = () => {
    const textFormatters: CometChatTextFormatter[] = [];
    const mentionsFormatter = new CometChatMentionsFormatter();
    mentionsFormatter.setMentionsStyle({
      textStyle: { color: "#D6409F" },
      selfTextStyle: { color: "#30A46C" },
    });
    textFormatters.push(mentionsFormatter);
    return textFormatters;
  };

  return <CometChatConversations textFormatters={getTextFormatters()} />;
}
```

See [CometChatMentionsFormatter](/docs/ui-kit/react-native/mentions-formatter-guide) for mention formatting.

***

## Common Patterns

### Custom empty state with CTA

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { View, Text, TouchableOpacity } from "react-native";

function EmptyStateConversations() {
  return (
    <CometChatConversations
      EmptyView={() => (
        <View style={{ flex: 1, justifyContent: "center", alignItems: "center", padding: 40 }}>
          <Text style={{ fontSize: 16, marginBottom: 16 }}>No conversations yet</Text>
          <TouchableOpacity
            style={{ backgroundColor: "#6852D6", paddingHorizontal: 20, paddingVertical: 10, borderRadius: 8 }}
            onPress={() => console.log("Start conversation")}>
            <Text style={{ color: "white" }}>Start a conversation</Text>
          </TouchableOpacity>
        </View>
      )}
    />
  );
}
```

### Hide all chrome — minimal list

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";

function MinimalConversations() {
  return (
    <CometChatConversations
      receiptsVisibility={false}
      usersStatusVisibility={false}
      groupTypeVisibility={false}
      deleteConversationOptionVisibility={false}
      hideHeader={true}
    />
  );
}
```

### Conversations with search

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";

function SearchableConversations() {
  return (
    <CometChatConversations
      showSearchBar={true}
      onSearchTextChanged={(text) => console.log("Search:", text)}
    />
  );
}
```

### Multi-select with submit

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function MultiSelectConversations() {
  const handleSubmit = (conversations: Array<CometChat.Conversation>) => {
    console.log("Selected conversations:", conversations.length);
  };

  return (
    <CometChatConversations
      selectionMode="multiple"
      hideSubmitButton={false}
      onSubmit={handleSubmit}
    />
  );
}
```

***

## Styling

The component uses the theme system from `CometChatThemeProvider`. Pass a `style` prop to customize the appearance.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatConversations } from "@cometchat/chat-uikit-react-native";

function StyledConversations() {
  return (
    <CometChatConversations
      style={{
        containerStyle: {
          backgroundColor: "#FAFAFA",
        },
        itemStyle: {
          avatarStyle: {
            containerStyle: {
              borderRadius: 8,
              backgroundColor: "#FBAA75",
            },
            imageStyle: {
              borderRadius: 8,
            },
          },
          badgeStyle: {
            containerStyle: {
              backgroundColor: "#F76808",
            },
          },
        },
      }}
    />
  );
}
```

### Style Properties

| Property         | Type        | Description                                                                                |
| ---------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `containerStyle` | `ViewStyle` | Style for the root container                                                               |
| `headerStyle`    | `ViewStyle` | Style for the header section                                                               |
| `titleStyle`     | `TextStyle` | Style for the header title                                                                 |
| `itemStyle`      | `object`    | Style for list items (includes `avatarStyle`, `badgeStyle`, `titleStyle`, `subtitleStyle`) |
| `searchStyle`    | `object`    | Style for the search bar                                                                   |

<Note>
  **Avatar style override in Conversations:** `CometChatConversations` generates its own internal avatar style that overrides the base theme's `avatarStyle`. To customize avatar appearance specifically within the conversation list, you must set `avatarStyle` through the `itemStyle` prop on `CometChatConversations` (i.e., `style.itemStyle.avatarStyle`). Setting `avatarStyle` at the theme level via `CometChatThemeProvider` will not take effect for the conversation list.
</Note>

***

## Props

All props are optional unless noted.

### conversationsRequestBuilder

Controls which conversations load and in what order.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `CometChat.ConversationsRequestBuilder` |
| Default | SDK default (30 per page)               |

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

***

### customSoundForMessages

Custom sound file for incoming message notifications.

|         |                |
| ------- | -------------- |
| Type    | `audio source` |
| Default | Built-in sound |

***

### datePattern

Custom function to format conversation timestamps.

|         |                                                    |
| ------- | -------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => string` |
| Default | Component default                                  |

***

### deleteConversationOptionVisibility

Shows/hides the delete option in the context menu.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### disableSoundForMessages

Disables the notification sound for incoming messages.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### EmptyView

Custom component displayed when there are no conversations.

|         |                      |
| ------- | -------------------- |
| Type    | `() => JSX.Element`  |
| Default | Built-in empty state |

***

### ErrorView

Custom component displayed when an error occurs.

|         |                      |
| ------- | -------------------- |
| Type    | `() => JSX.Element`  |
| Default | Built-in error state |

***

### groupTypeVisibility

Shows/hides the group type icon (public/private/password).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### hideBackButton

Hides the back button in the header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### hideError

Hides the error state view.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideHeader

Hides the entire header bar.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideSubmitButton

Hides the submit button when selection mode is enabled.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### ItemView

Custom renderer for the entire list item row.

|         |                                                         |
| ------- | ------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => JSX.Element` |
| Default | Built-in list item                                      |

***

### LeadingView

Custom renderer for the avatar / left section.

|         |                                                         |
| ------- | ------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => JSX.Element` |
| Default | Built-in avatar                                         |

***

### LoadingView

Custom component displayed during the loading state.

|         |                            |
| ------- | -------------------------- |
| Type    | `() => JSX.Element`        |
| Default | Built-in loading indicator |

***

### onBack

Callback fired when the back button is pressed.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onEmpty

Callback fired when the conversation list is empty.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onError

Callback fired when the component encounters an error.

|         |                                                 |
| ------- | ----------------------------------------------- |
| Type    | `(error: CometChat.CometChatException) => void` |
| Default | `undefined`                                     |

***

### onItemLongPress

Callback fired when a conversation row is long-pressed.

|         |                                                  |
| ------- | ------------------------------------------------ |
| Type    | `(conversation: CometChat.Conversation) => void` |
| Default | `undefined`                                      |

***

### onItemPress

Callback fired when a conversation row is tapped.

|         |                                                  |
| ------- | ------------------------------------------------ |
| Type    | `(conversation: CometChat.Conversation) => void` |
| Default | `undefined`                                      |

***

### onLoad

Callback fired when conversations are loaded.

|         |                                            |
| ------- | ------------------------------------------ |
| Type    | `(list: CometChat.Conversation[]) => void` |
| Default | `undefined`                                |

***

### onSearchBarClicked

Callback fired when the search bar is clicked. Requires `showSearchBar={true}`.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onSearchTextChanged

Callback fired when search text changes. Requires `showSearchBar={true}`.

|         |                                |
| ------- | ------------------------------ |
| Type    | `(searchText: string) => void` |
| Default | `undefined`                    |

***

### onSelection

Callback fired when conversations are selected/deselected. Requires `selectionMode` to be set.

|         |                                                          |
| ------- | -------------------------------------------------------- |
| Type    | `(conversations: Array<CometChat.Conversation>) => void` |
| Default | `undefined`                                              |

***

### onSubmit

Callback fired when the submit button is pressed. Requires `selectionMode` to be set.

|         |                                                          |
| ------- | -------------------------------------------------------- |
| Type    | `(conversations: Array<CometChat.Conversation>) => void` |
| Default | `undefined`                                              |

***

### receiptsVisibility

Shows/hides message read/delivery receipt indicators.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### SearchView

Custom search bar component.

|         |                     |
| ------- | ------------------- |
| Type    | `() => JSX.Element` |
| Default | Built-in search bar |

***

### selectionMode

Enables single or multi-select mode on list items.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `"single" \| "multiple" \| "none"` |
| Default | `"none"`                           |

***

### searchText

Current search text value for the search bar.

|         |          |
| ------- | -------- |
| Type    | `string` |
| Default | `""`     |

***

### showSearchBar

Shows a search bar at the top of the list.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### SubtitleView

Custom renderer for the last message preview text.

|         |                                                         |
| ------- | ------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => JSX.Element` |
| Default | Built-in subtitle                                       |

***

### textFormatters

Custom text formatters for the conversation subtitle.

|         |                                     |
| ------- | ----------------------------------- |
| Type    | `CometChatTextFormatter[]`          |
| Default | Default formatters from data source |

***

### TitleView

Custom renderer for the name / title text.

|         |                                                         |
| ------- | ------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => JSX.Element` |
| Default | Built-in title                                          |

***

### TrailingView

Custom renderer for the timestamp / badge / right section.

|         |                                                         |
| ------- | ------------------------------------------------------- |
| Type    | `(conversation: CometChat.Conversation) => JSX.Element` |
| Default | Built-in trailing view                                  |

***

### usersStatusVisibility

Shows/hides the online/offline status indicator.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="message" href="/ui-kit/react-native/message-list">
    Display the full chat interface after selecting a conversation
  </Card>

  <Card title="Users" icon="users" href="/ui-kit/react-native/users">
    Display and interact with user lists
  </Card>

  <Card title="Groups" icon="user-group" href="/ui-kit/react-native/groups">
    Display and manage group conversations
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>


# Core
Source: https://www.cometchat.com/docs/ui-kit/react-native/core-features

Explore CometChat React Native UI Kit core messaging features, including media sharing, receipts, typing indicators, and more.

<Info>
  **Quick Reference for AI Agents & Developers**

  Key components powering core features:

  * **Conversations** → [CometChatConversations](/docs/ui-kit/react-native/conversations)
  * **Message List** → [CometChatMessageList](/docs/ui-kit/react-native/message-list)
  * **Message Composer** → [CometChatMessageComposer](/docs/ui-kit/react-native/message-composer)
  * **Message Header** → [CometChatMessageHeader](/docs/ui-kit/react-native/message-header)
  * **Users** → [CometChatUsers](/docs/ui-kit/react-native/users)
  * **Groups** → [CometChatGroups](/docs/ui-kit/react-native/groups)
  * **Group Members** → [CometChatGroupMembers](/docs/ui-kit/react-native/group-members)
</Info>

## Overview

The UI Kit comprises a variety of components, each designed to work seamlessly with one another to deliver a comprehensive and intuitive chat experience.

Here's how different UI Kit components work together to achieve CometChat's core features:

## Instant Messaging

At the heart of CometChat's functionality is the ability to support real-time text messaging. Users can send and receive instant messages, fostering quick and efficient communication.

<Frame>
  <img />
</Frame>

| Component                                                | Role                                                                                                                                                                                          |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [MessageComposer](/docs/ui-kit/react-native/message-composer) | [MessageComposer](/docs/ui-kit/react-native/message-composer) component allows users to compose and send different types of messages with ease.                                                    |
| [MessageList](/docs/ui-kit/react-native/message-list)         | [MessageList](/docs/ui-kit/react-native/message-list) component renders a list of messages sent and messages received using [TextBubble](/docs/ui-kit/react-native/message-bubble-styling#text-bubble). |

## Media Sharing

Share multiple images, videos, audio files, and documents in a single send. Tapping the attachment button opens a multi-select picker; the picks stage in a preview tray above the input box with per-file upload progress, and send together with an optional caption — all out of the box.

<Frame>
  <img alt="Multi-attachment message list showing an image grid, a file card, and an audio bubble with caption, plus the composer staging tray with mixed image, video, and file tiles" />
</Frame>

| Component                                                                              | Role                                                                                                          |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [MessageComposer](/docs/ui-kit/react-native/message-composer#multi-attachment-staging-tray) | Multi-select picker, an attachment tray that uploads before send, and the composer text as the batch caption. |
| [MessageList](/docs/ui-kit/react-native/message-list#multi-attachment-batch-grouping)       | Renders received attachments with per-type bubbles and groups a multi-type send as one visual batch.          |

A mixed pick is split into one message per attachment type (images → videos → audios → files) that render as grouped bubbles: an image/video **grid**, a stacked **audio player** list, and a connected **file card** stack. Per-message file count and per-file size limits come from your app's dashboard settings.

> A complete messaging interface can be built by combining three key components: [MessageHeader](/docs/ui-kit/react-native/message-header), [MessageList](/docs/ui-kit/react-native/message-list), and [MessageComposer](/docs/ui-kit/react-native/message-composer).

## Read Receipts

CometChat's Read Receipts feature provides visibility into message status, letting users know when a message has been delivered and read. This brings clarity to communication and ensures users are informed about the status of their messages.

<Frame>
  <img />
</Frame>

| Components                                                                       | Functionality                                                                                                                                                                                                                                   |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Conversations](/docs/ui-kit/react-native/conversations)                              | [Conversations](/docs/ui-kit/react-native/conversations) component renders a conversation item list. Each item also displays the delivery status of the last message, providing users with real-time updates on message status.                      |
| [MessageList](/docs/ui-kit/react-native/message-list)                                 | [MessageList](/docs/ui-kit/react-native/message-list) component renders different types of message bubbles. Read receipt status is an integral part of all message bubbles, regardless of type, and provides real-time updates about message status. |
| [MessageInformation](/docs/ui-kit/react-native/component-styling#message-information) | [MessageInformation](/docs/ui-kit/react-native/component-styling#message-information) component provides transparency into the status of each sent message, giving the sender insights into whether their message has been delivered and read.       |

## Mark as Unread

The Mark as Unread feature allows users to manually mark messages as unread, helping them keep track of important conversations they want to revisit later. When enabled, the message list can automatically start from the first unread message, making it easier to pick up where you left off.

<Frame>
  <img />
</Frame>

| Components                                          | Functionality                                                                                                                                                               |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Message List](/docs/ui-kit/react-native/message-list)   | [Message List](/docs/ui-kit/react-native/message-list) provides the "Mark as unread" option in message actions and supports starting from the first unread message when enabled. |
| [Conversations](/docs/ui-kit/react-native/conversations) | [Conversations](/docs/ui-kit/react-native/conversations) component listens to conversation updates and reflects the updated unread count in real-time.                           |

## Typing Indicator

The Typing Indicator feature shows when a user is typing a response in real-time, fostering a more interactive and engaging chat environment. This enhances the real-time communication experience, making conversations feel more natural and fluid.

<Frame>
  <img />
</Frame>

| Components                                            | Functionality                                                                                                                                                                                                                                                             |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Conversations](/docs/ui-kit/react-native/conversations)   | [Conversations](/docs/ui-kit/react-native/conversations) component renders a list of conversation items, each displaying real-time typing indicators. If a user in a one-on-one or group chat is currently typing, the status is reflected instantly in the conversation list. |
| [Message Header](/docs/ui-kit/react-native/message-header) | [Message Header](/docs/ui-kit/react-native/message-header) component displays user or group details in the toolbar. It also manages the typing indicator, dynamically updating to show a real-time "typing..." status when a user or group member is actively typing.          |

## User Presence

CometChat's User Presence feature lets users see the online or offline status of their contacts, helping them choose the right time to start a conversation and set expectations for response times.

<Frame>
  <img />
</Frame>

| Components                                           | Functionality                                                                                                                                                                                                   |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Conversations](/docs/ui-kit/react-native/conversations)  | [Conversations](/docs/ui-kit/react-native/conversations) component renders a list of conversation items, each displaying user presence information such as online or offline status.                                 |
| [MessageHeader](/docs/ui-kit/react-native/message-header) | [Message Header](/docs/ui-kit/react-native/message-header) component displays user or group details in the toolbar. It also handles user presence, showing real-time online or offline status for the selected user. |
| [Users](/docs/ui-kit/react-native/users)                  | [Users](/docs/ui-kit/react-native/users) component displays a list of users available in your app and is also responsible for showing their real-time presence status such as online or offline.                     |
| [GroupMembers](/docs/ui-kit/react-native/group-members)   | [Group Members](/docs/ui-kit/react-native/group-members) component displays a list of users within a group and also manages real-time presence information, showing whether each member is online or offline.        |

## Reactions

CometChat's Reactions feature adds a layer of expressiveness to your chat application by allowing users to react to messages. With Reactions, users can convey a range of emotions or express their thoughts on a particular message without typing out a full response, enhancing the user experience and fostering greater engagement.

<Frame>
  <img />
</Frame>

| Components                                       | Functionality                                                                                                                                                                                                                              |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [MessageList](/docs/ui-kit/react-native/message-list) | [MessageList](/docs/ui-kit/react-native/message-list) component renders various types of message bubbles. Regardless of the message type, reactions are seamlessly integrated, allowing users to respond in a more engaging and expressive way. |

## Mentions

Mentions is a feature that enhances the interactivity and clarity of group or 1-on-1 chats by allowing users to directly address or refer to specific individuals in a conversation.

<Frame>
  <img />
</Frame>

| Components                                               | Functionality                                                                                                                                                                                                                                       |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Conversations](/docs/ui-kit/react-native/conversations)      | [Conversations](/docs/ui-kit/react-native/conversations) component integrates the Mentions feature, allowing users to see directly from the conversation list when they or others have been specifically mentioned in a chat.                            |
| [MessageComposer](/docs/ui-kit/react-native/message-composer) | [MessageComposer](/docs/ui-kit/react-native/message-composer) component allows users to compose and send various types of messages, including support for the Mentions feature to directly address participants within the conversation.                 |
| [MessageList](/docs/ui-kit/react-native/message-list)         | [MessageList](/docs/ui-kit/react-native/message-list) component displays a list of sent and received messages. It also supports rendering Mentions, enhancing the clarity and interactivity of conversations by highlighting direct references to users. |

## Rich Text Formatting

Rich Text Formatting allows users to style their messages with bold, italic, underline, strikethrough, code, links, lists, blockquotes, and code blocks. This brings richer expression to conversations and helps users emphasize key points.

<Frame>
  <img />
</Frame>

| Components                                                                                   | Functionality                                                                                                                                                                                                                                                                                                                                       |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [CompactMessageComposer](/docs/ui-kit/react-native/compact-message-composer#rich-text-formatting) | [CompactMessageComposer](/docs/ui-kit/react-native/compact-message-composer#rich-text-formatting) provides a built-in rich text editor. Its formatting toolbar covers bold, italic, underline, strikethrough, links, lists, blockquotes, inline code, and code blocks; the native text selection menu offers bold, italic, underline, and strikethrough. |
| [MessageList](/docs/ui-kit/react-native/message-list)                                             | [MessageList](/docs/ui-kit/react-native/message-list) renders formatted messages with the appropriate styling automatically applied, ensuring that rich text formatting is displayed exactly as intended by the sender.                                                                                                                                  |

## Quoted Reply

The Quoted Reply feature enables users to quickly reply to specific messages by selecting the "Reply" option from a message's action menu. This enhances context, keeps conversations organized, and improves the overall chat experience in both 1-on-1 and group chats.

<Frame>
  <img />
</Frame>

| Components                                                | Functionality                                                                                                                                                                                                             |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Message List](/docs/ui-kit/react-native/message-list)         | [Message List](/docs/ui-kit/react-native/message-list) supports replying to messages via the "Reply" option. Users can select "Reply" on a message to open the composer with the quoted reply pre-filled, maintaining context. |
| [Message Composer](/docs/ui-kit/react-native/message-composer) | [Message Composer](/docs/ui-kit/react-native/message-composer) works seamlessly with Quoted Reply by showing the quoted message above the input field, letting users compose their response in proper context.                 |

## Conversation and Advanced Search

Conversation and Advanced Search enables users to quickly find conversations, messages, and media across chats in real time. It supports filters, scopes, and custom actions, allowing users to locate content efficiently while keeping the chat experience smooth and intuitive.

<Frame>
  <img />
</Frame>

| Components                                            | Functionality                                                                                                                                                              |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Search                                                | Search allows users to search across conversations and messages in real time. Users can click on a result to open the conversation or jump directly to a specific message. |
| [Message Header](/docs/ui-kit/react-native/message-header) | [Message Header](/docs/ui-kit/react-native/message-header) shows the search button in the chat header, allowing users to search within a conversation.                          |
| [Message List](/docs/ui-kit/react-native/message-list)     | [Message List](/docs/ui-kit/react-native/message-list) shows the selected message when clicked from search results and highlights it in the message list.                       |
| [Conversations](/docs/ui-kit/react-native/conversations)   | [Conversations](/docs/ui-kit/react-native/conversations) displays the search input.                                                                                             |

## Moderation

CometChat's Message Moderation feature helps maintain a safe and respectful chat environment by automatically filtering and managing inappropriate content. Messages can be automatically blocked or flagged based on predefined rules, ensuring harmful content is handled before it reaches users.

<Frame>
  <img />
</Frame>

<Note>
  Learn more about setting up moderation rules and managing content in the [Moderation](/docs/moderation/overview) documentation.
</Note>

| Components                                        | Functionality                                                                                                                                                           |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Message List](/docs/ui-kit/react-native/message-list) | [Message List](/docs/ui-kit/react-native/message-list) automatically handles moderated messages, displaying blocked content appropriately based on your moderation settings. |

After implementing moderation rules, users can report messages they find inappropriate or harmful. As a next step, you can enable the **[Report Message](#report-message)** feature to allow users to flag messages for review by moderators.

## Report Message

The Report Message feature allows users to report inappropriate or harmful messages within the chat. Users can choose from predefined reasons and provide additional remarks for detailed context. This feature helps maintain a safe and respectful chat environment.

<Note>
  Learn more about how flagged messages are handled, reviewed, and moderated in the [Flagged Messages](/docs/moderation/flagged-messages) documentation.
</Note>

<Frame>
  <img />
</Frame>

| Components                                        | Functionality                                                                                                                                                                                    |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Message List](/docs/ui-kit/react-native/message-list) | [Message List](/docs/ui-kit/react-native/message-list) provides the "Report Message" option in the message actions menu, allowing users to initiate the reporting process for inappropriate messages. |

## Threaded Conversations

The Threaded Conversations feature enables users to respond directly to a specific message in a chat. This keeps conversations organized and enhances the user experience by maintaining context, especially in group chats.

<Frame>
  <img />
</Frame>

| Components                                                       | Functionality                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Threaded Header](/docs/ui-kit/react-native/threaded-messages-header) | [Threaded Header](/docs/ui-kit/react-native/threaded-messages-header) component displays the original message along with all its replies, helping users follow the context of a threaded conversation.                                                         |
| [MessageComposer](/docs/ui-kit/react-native/message-composer)         | [MessageComposer](/docs/ui-kit/react-native/message-composer) component enables users to compose and send various types of messages.                                                                                                                           |
| [MessageList](/docs/ui-kit/react-native/message-list)                 | [MessageList](/docs/ui-kit/react-native/message-list) component displays a chronological list of sent and received messages. It also supports Mentions, making conversations more interactive and easier to follow by highlighting direct references to users. |

## Group Chat

CometChat facilitates Group Chats, allowing users to have conversations with multiple participants simultaneously. This feature is crucial for team collaborations, group discussions, social communities, and more.

<Frame>
  <img />
</Frame>

For a comprehensive understanding and guide on implementing and using the Groups feature in CometChat, refer to the detailed guide on [Groups](/docs/ui-kit/react-native/groups).

***

## Next Steps

<CardGroup>
  <Card title="Call Features" icon="phone" href="/ui-kit/react-native/call-features">
    Explore voice and video calling capabilities
  </Card>

  <Card title="Extensions" icon="puzzle-piece" href="/ui-kit/react-native/extensions">
    Add stickers, polls, link previews, and more
  </Card>

  <Card title="Components Overview" icon="layer-group" href="/ui-kit/react-native/components-overview">
    Browse all available UI Kit components
  </Card>

  <Card title="Theming" icon="palette" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and appearance
  </Card>
</CardGroup>


# Custom Text Formatter
Source: https://www.cometchat.com/docs/ui-kit/react-native/custom-text-formatter-guide

Extend the CometChatTextFormatter base class to implement custom inline text patterns with regex and callbacks in React Native.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                                                         |
  | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package        | `@cometchat/chat-uikit-react-native`                                                                                                                                                          |
  | Key class      | `CometChatTextFormatter` (abstract base class for custom formatters)                                                                                                                          |
  | Required setup | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")`                                                                                                                       |
  | Purpose        | Extend to create custom inline text patterns with regex, styling, and callbacks                                                                                                               |
  | Features       | Text formatting, customizable styles, dynamic text replacement, suggestion list integration                                                                                                   |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/sample)                                                                                                            |
  | Related        | [ShortCut Formatter](/docs/ui-kit/react-native/shortcut-formatter-guide) · [Mentions Formatter](/docs/ui-kit/react-native/mentions-formatter-guide) · [All Guides](/docs/ui-kit/react-native/guide-overview) |
</Accordion>

`CometChatTextFormatter` is an abstract class for formatting text in the message composer and message bubbles. Extend it to build custom formatters — hashtags, keywords, or any regex-based pattern.

| Capability       | Description                                                 |
| ---------------- | ----------------------------------------------------------- |
| Text formatting  | Auto-format text based on regex patterns and styles         |
| Custom styles    | Set colors, fonts, and backgrounds for matched text         |
| Suggestion list  | Display suggestions when tracking character is typed        |
| Message handling | Process messages before sending with `handlePreMessageSend` |

***

## Base Class Overview

The `CometChatTextFormatter` class provides the foundation for all text formatters in React Native:

```tsx theme={null}
import { CometChatTextFormatter } from "@cometchat/chat-uikit-react-native";

abstract class CometChatTextFormatter {
  protected regexPattern: RegExp;
  protected trackCharacter: string;
  protected loggedInUser?: CometChat.User;
  protected messageObject: CometChat.BaseMessage;
  protected SuggestionItems: Array<SuggestionItem>;
  
  // Core methods
  setTrackingCharacter(char: string): void;
  setRegexPatterns(pattern: RegExp): void;
  getFormattedText(inputText: string | null | JSX.Element): string | null | JSX.Element;
  handlePreMessageSend(message: CometChat.TextMessage): CometChat.TextMessage;
  search(searchKey: string): void;
  fetchNext(): void;
  setSearchData(data: Array<SuggestionItem>): void;
}
```

***

## Steps

### 1. Import the base class

```tsx theme={null}
import { CometChatTextFormatter, SuggestionItem } from "@cometchat/chat-uikit-react-native";
```

### 2. Extend it

```tsx theme={null}
class HashTagTextFormatter extends CometChatTextFormatter {
  constructor() {
    super();
    this.setTrackingCharacter("#");
    this.setRegexPatterns(/\B#(\w+)\b/g);
  }
}
```

### 3. Implement formatting methods

Override `getFormattedText` to apply custom styling to matched patterns:

```tsx theme={null}
import React from "react";
import { Text } from "react-native";

class HashTagTextFormatter extends CometChatTextFormatter {
  constructor() {
    super();
    this.setTrackingCharacter("#");
    this.setRegexPatterns(/\B#(\w+)\b/g);
  }

  getFormattedText(inputText: string | null | JSX.Element): string | null | JSX.Element {
    if (!inputText || typeof inputText !== "string") {
      return inputText;
    }

    const regex = this.getRegexPattern();
    const parts: (string | JSX.Element)[] = [];
    let lastIndex = 0;
    let match;

    while ((match = regex.exec(inputText)) !== null) {
      // Add text before the match
      if (match.index > lastIndex) {
        parts.push(inputText.slice(lastIndex, match.index));
      }

      // Add styled hashtag
      parts.push(
        <Text key={match.index} style={{ color: "#5dff05", fontWeight: "bold" }}>
          #{match[1]}
        </Text>
      );

      lastIndex = match.index + match[0].length;
    }

    // Add remaining text
    if (lastIndex < inputText.length) {
      parts.push(inputText.slice(lastIndex));
    }

    return <Text>{parts}</Text>;
  }
}

export default HashTagTextFormatter;
```

***

## Example

A hashtag formatter used with [CometChatMessageList](/docs/ui-kit/react-native/message-list) and [CometChatMessageComposer](/docs/ui-kit/react-native/message-composer).

<Tabs>
  <Tab title="HashTagTextFormatter.tsx">
    ```tsx theme={null}
    import React, { JSX } from "react";
    import { Text, TextStyle } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatTextFormatter } from "@cometchat/chat-uikit-react-native";

    class HashTagTextFormatter extends CometChatTextFormatter {
      private hashtagStyle: TextStyle = {
        color: "#5dff05",
        fontWeight: "bold",
      };

      constructor() {
        super();
        this.setTrackingCharacter("#");
        this.setRegexPatterns(/\B#(\w+)\b/g);
      }

      setHashtagStyle(style: TextStyle) {
        this.hashtagStyle = style;
      }

      getFormattedText(inputText: string | null | JSX.Element): string | null | JSX.Element {
        if (!inputText || typeof inputText !== "string") {
          return inputText;
        }

        const regex = this.getRegexPattern();
        const parts: (string | JSX.Element)[] = [];
        let lastIndex = 0;
        let match;

        // Reset regex lastIndex for global patterns
        regex.lastIndex = 0;

        while ((match = regex.exec(inputText)) !== null) {
          if (match.index > lastIndex) {
            parts.push(inputText.slice(lastIndex, match.index));
          }

          parts.push(
            <Text key={match.index} style={this.hashtagStyle}>
              #{match[1]}
            </Text>
          );

          lastIndex = match.index + match[0].length;
        }

        if (lastIndex < inputText.length) {
          parts.push(inputText.slice(lastIndex));
        }

        if (parts.length === 0) {
          return inputText;
        }

        return <Text>{parts}</Text>;
      }
    }

    export default HashTagTextFormatter;
    ```
  </Tab>

  <Tab title="ChatScreen.tsx">
    ```tsx theme={null}
    import React, { useState, useEffect, useMemo } from "react";
    import { View, SafeAreaView } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
    } from "@cometchat/chat-uikit-react-native";
    import HashTagTextFormatter from "./HashTagTextFormatter";

    function ChatScreen(): React.JSX.Element {
      const [chatUser, setChatUser] = useState<CometChat.User | undefined>();

      useEffect(() => {
        CometChat.getUser("uid").then((user) => {
          setChatUser(user);
        });
      }, []);

      const hashtagFormatter = useMemo(() => new HashTagTextFormatter(), []);

      return (
        <SafeAreaView style={{ flex: 1 }}>
          {chatUser && (
            <View style={{ flex: 1 }}>
              <CometChatMessageHeader user={chatUser} />
              <CometChatMessageList
                user={chatUser}
                textFormatters={[hashtagFormatter]}
              />
              <CometChatMessageComposer
                user={chatUser}
                textFormatters={[hashtagFormatter]}
              />
            </View>
          )}
        </SafeAreaView>
      );
    }

    export default ChatScreen;
    ```
  </Tab>
</Tabs>

***

## Methods Reference

| Method                          | Description                                             |
| ------------------------------- | ------------------------------------------------------- |
| `setTrackingCharacter(char)`    | Character that starts tracking (e.g. `#` for hashtags)  |
| `setRegexPatterns(pattern)`     | Regex pattern to match text for formatting              |
| `getFormattedText(inputText)`   | Returns formatted JSX from input text                   |
| `handlePreMessageSend(message)` | Process message before sending                          |
| `search(searchKey)`             | Search function called when tracking character is typed |
| `fetchNext()`                   | Fetch next page of suggestions                          |
| `setSearchData(data)`           | Set suggestion list data                                |
| `setSuggestionItems(items)`     | Set the suggestion items array                          |
| `getSuggestionItems()`          | Get current suggestion items                            |
| `setMessage(message)`           | Set the message object in context                       |
| `getMessage()`                  | Get the current message object                          |
| `setUser(user)`                 | Set the user in context                                 |
| `setGroup(group)`               | Set the group in context                                |
| `setLoggedInUser(user)`         | Set the logged-in user                                  |
| `setComposerId(id)`             | Set the composer ID for event handling                  |
| `setId(id)`                     | Set unique identifier for the formatter                 |

***

## Advanced: Suggestion List Integration

For formatters that need to show suggestions (like mentions), implement the `search` method:

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatTextFormatter, SuggestionItem } from "@cometchat/chat-uikit-react-native";

class CustomSuggestionFormatter extends CometChatTextFormatter {
  constructor() {
    super();
    this.setTrackingCharacter(":");
  }

  search(searchKey: string): void {
    // Fetch data based on searchKey
    const suggestions = this.filterSuggestions(searchKey);
    
    const suggestionItems = suggestions.map((item) => 
      new SuggestionItem({
        id: item.id,
        name: item.name,
        promptText: `:${item.name}:`,
        trackingCharacter: ":",
        underlyingText: `:${item.code}:`,
      })
    );

    this.setSearchData(suggestionItems);
  }

  private filterSuggestions(searchKey: string): any[] {
    // Your filtering logic here
    return [];
  }
}
```

***

## Next Steps

<CardGroup>
  <Card title="Mentions Formatter" href="/ui-kit/react-native/mentions-formatter-guide">
    Add @mentions with styled tokens.
  </Card>

  <Card title="URL Formatter" href="/ui-kit/react-native/url-formatter-guide">
    Auto-detect and style URLs as clickable links.
  </Card>

  <Card title="All Guides" href="/ui-kit/react-native/guide-overview">
    Browse all feature and formatter guides.
  </Card>

  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/sample">
    Full working sample application on GitHub.
  </Card>
</CardGroup>


# Events
Source: https://www.cometchat.com/docs/ui-kit/react-native/events

Listen to UI Kit events for conversations, users, groups, messages, and calls in React Native UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field               | Value                                                                                                                                                                                                                    |
  | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Package             | `@cometchat/chat-uikit-react-native`                                                                                                                                                                                     |
  | Import              | `import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";`                                                                                                                                          |
  | Conversation events | `ccConversationDeleted`, `ccUpdateConversation`                                                                                                                                                                          |
  | User events         | `ccUserBlocked`, `ccUserUnblocked`                                                                                                                                                                                       |
  | Group events        | `ccGroupCreated`, `ccGroupDeleted`, `ccGroupLeft`, `ccGroupMemberScopeChanged`, `ccGroupMemberKicked`, `ccGroupMemberBanned`, `ccGroupMemberUnbanned`, `ccGroupMemberJoined`, `ccGroupMemberAdded`, `ccOwnershipChanged` |
  | Message events      | `ccMessageSent`, `ccMessageEdited`, `ccMessageDeleted`, `ccMessageRead`, `ccLiveReaction`, plus SDK listener events                                                                                                      |
  | Call events         | `onIncomingCallAccepted`, `onIncomingCallRejected`, `onCallEnded`, `onCallInitiated`, `onOutgoingCallAccepted`, `onOutgoingCallRejected`                                                                                 |
  | UI events           | `ccActiveChatChanged`, `ccCardActionClicked`                                                                                                                                                                             |
  | Purpose             | Decoupled communication between UI Kit components — subscribe to events to react to changes without direct component references                                                                                          |
</Accordion>

Events provide decoupled communication between UI Kit components. Components emit events in response to user interactions or state changes, allowing other parts of the application to react without direct component references.

Both Components and Composite Components have the ability to emit events. By emitting events, these components allow other parts of the application to react to changes or interactions, enabling dynamic and interactive behavior within the application.

### CometChatConversationEventListener

`CometChatConversationEventListener` emits events when the logged-in user executes some action on a conversation object.

| Name                  | Description                                                                                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------------- |
| ccConversationDeleted | This event is triggered when the user successfully deletes a conversation.                                        |
| ccUpdateConversation  | This event is triggered to update a conversation in the conversation list. Takes a Conversation object to update. |

### CometChatUserEventListener

`CometChatUserEventListener` emits events when the logged-in user executes some action on an user object.

It consists of the following events:

| Name            | Description                                                               |
| --------------- | ------------------------------------------------------------------------- |
| ccUserBlocked   | This event is triggered when the user successfully blocks another user.   |
| ccUserUnblocked | This event is triggered when the user successfully unblocks another user. |

### CometChatGroupEventListener

`CometChatGroupEventListener` emits events when the logged-in user executes some action on a group object.

It consists of the following events:

| Name                      | Description                                                                          |
| ------------------------- | ------------------------------------------------------------------------------------ |
| ccGroupCreated            | This event is triggered when the user creates a group successfully                   |
| ccGroupDeleted            | This event is triggered when the group member deletes the group successfully         |
| ccGroupLeft               | This event is triggered when the group member leaves the group successfully          |
| ccGroupMemberScopeChanged | This event is triggered when the group member's scope is updated successfully        |
| ccGroupMemberKicked       | This event is triggered when the group member is kicked                              |
| ccGroupMemberBanned       | This event is triggered when the group member is banned                              |
| ccGroupMemberUnbanned     | This event is triggered when the group member is un-banned                           |
| ccGroupMemberJoined       | This event is triggered when a user joins the group                                  |
| ccGroupMemberAdded        | This event is triggered when a user is added to the group                            |
| ccOwnershipChanged        | This event is triggered when the group ownership is assigned to another group member |

### CometChatMessageEvents

`CometChatMessageEvents` emits events when the logged-in user executes some action on a message object.

It consists of the following events:

| Name                               | Description                                                                                                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ccMessageSent                      | This event is triggered when the sent message is in transit and also when it is received by the receiver.                                                                      |
| ccMessageEdited                    | This event is triggered when the user successfully edits the message.                                                                                                          |
| ccMessageDeleted                   | This event is triggered when the user successfully deletes the message.                                                                                                        |
| ccMessageRead                      | This event is triggered when the sent message is read by the receiver.                                                                                                         |
| ccLiveReaction                     | This event is triggered when the user sends a live reaction.                                                                                                                   |
| onTextMessageReceived              | This event is emitted when the CometChat SDK listener emits a text message.                                                                                                    |
| onMediaMessageReceived             | This event is emitted when the CometChat SDK listener emits a media message.                                                                                                   |
| onCustomMessageReceived            | This event is emitted when the CometChat SDK listener emits a custom message.                                                                                                  |
| onTypingStarted                    | This event is emitted when the CometChat SDK listener indicates that a user has started typing.                                                                                |
| onTypingEnded                      | This event is emitted when the CometChat SDK listener indicates that a user has stopped typing.                                                                                |
| onMessagesDelivered                | This event is emitted when the CometChat SDK listener indicates that messages have been delivered.                                                                             |
| onMessagesRead                     | This event is emitted when the CometChat SDK listener indicates that messages have been read.                                                                                  |
| onMessageEdited                    | This event is emitted when the CometChat SDK listener indicates that a message has been edited.                                                                                |
| onMessageDeleted                   | This event is emitted when the CometChat SDK listener indicates that a message has been deleted.                                                                               |
| onTransientMessageReceived         | This event is emitted when the CometChat SDK listener emits a transient message.                                                                                               |
| onInteractionGoalCompleted         | This event is emitted when the CometChat SDK listener indicates that an interaction goal has been completed.                                                                   |
| onFormMessageReceived              | This event is emitted when an interactive message of 'form' type is received from the CometChat SDK listener.                                                                  |
| onCardMessageReceived              | This event is emitted when a card message (`category: "card"`) is received from the CometChat SDK listener. Used by the Card message bubble to render developer-defined cards. |
| onSchedulerMessageReceived         | This event is emitted when an interactive message of 'scheduler' type is received from the CometChat SDK listener.                                                             |
| onCustomInteractiveMessageReceived | This event is emitted when an interactive message of 'customInteractive' type is received from the CometChat SDK listener.                                                     |

### CometChatCallEvents

`CometChatCallEvents` emits events when the logged-in user executes some action on a call object.

It consists of the following events:

| Name                                        | Description                                             |
| ------------------------------------------- | ------------------------------------------------------- |
| **func** onIncomingCallAccepted(call: Call) | Triggers whenever incoming call is accepted by the user |
| **func** onIncomingCallRejected(call: Call) | Triggers whenever incoming call is rejected by the user |
| **func** onCallEnded(call: Call)            | Triggers whenever the call is ended                     |
| **func** onCallInitiated(call: Call)        | Triggers whenever the call is getting initiated         |
| **func** onOutgoingCallAccepted(call: Call) | Triggers whenever outgoing call is accepted by the user |
| **func** onOutgoingCallRejected(call: Call) | Triggers whenever outgoing call is rejected by the user |

### CometChatUIEventListener

UI events refer to actions or interactions performed by a user within the CometChat UI Kit. These events are triggered when a user interacts with various UI elements, such as buttons, menus, checkboxes, input fields, or any other interactive components.

It consists of the following events:

| Name                | Description                                                                                                                                         |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| ccActiveChatChanged | This event is triggered when the user navigates to a particular chat window.                                                                        |
| ccCardActionClicked | This event is triggered when the user clicks an action on a card message bubble. The event payload contains the `message` and the clicked `action`. |

***

## Next Steps

<CardGroup>
  <Card title="Methods" icon="code" href="/ui-kit/react-native/methods">
    Initialize and authenticate with CometChatUIKit
  </Card>

  <Card title="Components Overview" icon="puzzle-piece" href="/ui-kit/react-native/components-overview">
    Explore all available UI components
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/react-native/conversations">
    Display and manage conversation lists
  </Card>

  <Card title="Message List" icon="message" href="/ui-kit/react-native/message-list">
    Display messages in a conversation
  </Card>
</CardGroup>


# Conversation List + Message View
Source: https://www.cometchat.com/docs/ui-kit/react-native/expo-conversation

Build CometChat React Native UI Kit conversation list and message view layouts in Expo with headers, lists, composers, and navigation.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                  |
  | ------------ | ------------------------------------------------------------------------------------------------------ |
  | Package      | `@cometchat/chat-uikit-react-native`                                                                   |
  | Framework    | Expo                                                                                                   |
  | Components   | `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Conversation list → tap → message view                                                                 |
  | Prerequisite | Complete [Expo Integration](/docs/ui-kit/react-native/expo-integration) Steps 1–4 first                     |
  | Pattern      | WhatsApp, Telegram, Signal                                                                             |
</Accordion>

This guide builds a standard mobile chat layout — conversation list on one screen, tap to open messages. Users tap a conversation to view and send messages.

This assumes you've already completed [Expo Integration](/docs/ui-kit/react-native/expo-integration) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Two screens working together:

1. **Conversation list** — shows all active conversations (users and groups)
2. **Message view** — displays chat messages for the selected conversation with header, message list, and composer

***

## Step 1 — Create the Messages Component

Create a `Messages.tsx` file that combines the message header, list, and composer:

<Tabs>
  <Tab title="TypeScript">
    ```tsx title="Messages.tsx" theme={null}
    import React from "react";
    import { View, StyleSheet } from "react-native";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    interface MessagesProps {
      user?: CometChat.User;
      group?: CometChat.Group;
      onBack: () => void;
    }

    const Messages = ({ user, group, onBack }: MessagesProps) => {
      return (
        <View style={styles.container}>
          <CometChatMessageHeader
            user={user}
            group={group}
            onBack={onBack}
            showBackButton
          />
          <CometChatMessageList user={user} group={group} />
          <CometChatMessageComposer user={user} group={group} />
        </View>
      );
    };

    const styles = StyleSheet.create({
      container: {
        flex: 1,
      },
    });

    export default Messages;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="Messages.js" theme={null}
    import React from "react";
    import { View, StyleSheet } from "react-native";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
    } from "@cometchat/chat-uikit-react-native";

    const Messages = ({ user, group, onBack }) => {
      return (
        <View style={styles.container}>
          <CometChatMessageHeader
            user={user}
            group={group}
            onBack={onBack}
            showBackButton
          />
          <CometChatMessageList user={user} group={group} />
          <CometChatMessageComposer user={user} group={group} />
        </View>
      );
    };

    const styles = StyleSheet.create({
      container: {
        flex: 1,
      },
    });

    export default Messages;
    ```
  </Tab>
</Tabs>

***

## Step 2 — Update App.tsx

Wire the conversation list and message components together:

<Tabs>
  <Tab title="TypeScript">
    ```tsx title="App.tsx" theme={null}
    import React, { useEffect, useState } from "react";
    import { ViewStyle } from "react-native";
    import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
    import { GestureHandlerRootView } from "react-native-gesture-handler";
    import {
      CometChatConversations,
      CometChatUIKit,
      CometChatUiKitConstants,
      UIKitSettings,
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import Messages from "./Messages";

    const APP_ID = "APP_ID";
    const AUTH_KEY = "AUTH_KEY";
    const REGION = "REGION";
    const UID = "cometchat-uid-1";

    const App = (): React.ReactElement => {
      const [loggedIn, setLoggedIn] = useState(false);
      const [messageUser, setMessageUser] = useState<CometChat.User>();
      const [messageGroup, setMessageGroup] = useState<CometChat.Group>();

      useEffect(() => {
        const init = async () => {
          const uiKitSettings: UIKitSettings = {
            appId: APP_ID,
            authKey: AUTH_KEY,
            region: REGION,
            subscriptionType: CometChat.AppSettings
              .SUBSCRIPTION_TYPE_ALL_USERS as UIKitSettings["subscriptionType"],
          };

          try {
            await CometChatUIKit.init(uiKitSettings);
            await CometChatUIKit.login({ uid: UID });
            setLoggedIn(true);
          } catch (err) {
            console.error("Init/login error:", err);
          }
        };

        init();
      }, []);

      const handleConversationPress = (conversation: CometChat.Conversation) => {
        const conversationType = conversation.getConversationType();
        
        if (conversationType === CometChatUiKitConstants.ConversationTypeConstants.user) {
          setMessageUser(conversation.getConversationWith() as CometChat.User);
          setMessageGroup(undefined);
        } else {
          setMessageUser(undefined);
          setMessageGroup(conversation.getConversationWith() as CometChat.Group);
        }
      };

      const handleBack = () => {
        setMessageUser(undefined);
        setMessageGroup(undefined);
      };

      return (
        <GestureHandlerRootView style={{ flex: 1 }}>
          <SafeAreaProvider>
            <CometChatI18nProvider>
              <SafeAreaView style={styles.fullScreen}>
                <CometChatThemeProvider>
                  {loggedIn && (
                    <>
                      <CometChatConversations
                        style={{
                          containerStyle: {
                            display: messageUser || messageGroup ? "none" : "flex",
                          },
                        }}
                        onItemPress={handleConversationPress}
                      />

                      {(messageUser || messageGroup) && (
                        <Messages
                          user={messageUser}
                          group={messageGroup}
                          onBack={handleBack}
                        />
                      )}
                    </>
                  )}
                </CometChatThemeProvider>
              </SafeAreaView>
            </CometChatI18nProvider>
          </SafeAreaProvider>
        </GestureHandlerRootView>
      );
    };

    const styles: { fullScreen: ViewStyle } = {
      fullScreen: { flex: 1 },
    };

    export default App;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="App.js" theme={null}
    import React, { useEffect, useState } from "react";
    import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
    import { GestureHandlerRootView } from "react-native-gesture-handler";
    import {
      CometChatConversations,
      CometChatUIKit,
      CometChatUiKitConstants,
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import Messages from "./Messages";

    const APP_ID = "APP_ID";
    const AUTH_KEY = "AUTH_KEY";
    const REGION = "REGION";
    const UID = "cometchat-uid-1";

    const App = () => {
      const [loggedIn, setLoggedIn] = useState(false);
      const [messageUser, setMessageUser] = useState();
      const [messageGroup, setMessageGroup] = useState();

      useEffect(() => {
        const init = async () => {
          const uiKitSettings = {
            appId: APP_ID,
            authKey: AUTH_KEY,
            region: REGION,
            subscriptionType: CometChat.AppSettings.SUBSCRIPTION_TYPE_ALL_USERS,
          };

          try {
            await CometChatUIKit.init(uiKitSettings);
            await CometChatUIKit.login({ uid: UID });
            setLoggedIn(true);
          } catch (err) {
            console.error("Init/login error:", err);
          }
        };

        init();
      }, []);

      const handleConversationPress = (conversation) => {
        const conversationType = conversation.getConversationType();
        
        if (conversationType === CometChatUiKitConstants.ConversationTypeConstants.user) {
          setMessageUser(conversation.getConversationWith());
          setMessageGroup(undefined);
        } else {
          setMessageUser(undefined);
          setMessageGroup(conversation.getConversationWith());
        }
      };

      const handleBack = () => {
        setMessageUser(undefined);
        setMessageGroup(undefined);
      };

      return (
        <GestureHandlerRootView style={{ flex: 1 }}>
          <SafeAreaProvider>
            <CometChatI18nProvider>
              <SafeAreaView style={{ flex: 1 }}>
                <CometChatThemeProvider>
                  {loggedIn && (
                    <>
                      <CometChatConversations
                        style={{
                          containerStyle: {
                            display: messageUser || messageGroup ? "none" : "flex",
                          },
                        }}
                        onItemPress={handleConversationPress}
                      />

                      {(messageUser || messageGroup) && (
                        <Messages
                          user={messageUser}
                          group={messageGroup}
                          onBack={handleBack}
                        />
                      )}
                    </>
                  )}
                </CometChatThemeProvider>
              </SafeAreaView>
            </CometChatI18nProvider>
          </SafeAreaProvider>
        </GestureHandlerRootView>
      );
    };

    export default App;
    ```
  </Tab>
</Tabs>

***

## Step 3 — Run the Project

<Tabs>
  <Tab title="iOS">
    ```bash theme={null}
    npx expo run:ios
    ```
  </Tab>

  <Tab title="Android">
    ```bash theme={null}
    npx expo run:android
    ```
  </Tab>
</Tabs>

You should see the conversation list. Tap any conversation to open the message view. Use the back button to return to the list.

***

## Next Steps

<CardGroup>
  <Card title="Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and styles to match your brand
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Expo Integration" icon="mobile" href="/ui-kit/react-native/expo-integration">
    Back to the main setup guide
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/react-native/core-features">
    Chat features included out of the box
  </Card>
</CardGroup>


# Expo Integration
Source: https://www.cometchat.com/docs/ui-kit/react-native/expo-integration

Add CometChat to an Expo app using development builds in 5 steps: create project, install, init, login, render.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                 |
  | ---------------- | ------------------------------------------------------------------------------------- |
  | Package          | `@cometchat/chat-uikit-react-native`                                                  |
  | Peer deps        | `expo` SDK 50+, `@cometchat/chat-sdk-react-native`                                    |
  | Init             | `CometChatUIKit.init(UIKitSettings)` — must resolve before `login()`                  |
  | Login            | `CometChatUIKit.login({ uid })` — must resolve before rendering components            |
  | Order            | `init()` → `login()` → render. Breaking this order = blank screen                     |
  | Auth Key         | Dev/testing only. Use Auth Token in production                                        |
  | Expo Go          | Not supported — use development builds                                                |
  | Other frameworks | [React Native CLI](/docs/ui-kit/react-native/react-native-cli-integration)                 |
  | AI Skills        | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills) |
</Accordion>

This guide walks you through adding CometChat to an Expo app using development builds. By the end you'll have a working chat UI.

<Warning>
  Expo Go is not supported. The CometChat UI Kit requires custom native modules, so you must use [development builds](https://docs.expo.dev/develop/development-builds/introduction/).
</Warning>

***

## Integrate with AI Coding Agents

Skip the manual steps — use [CometChat Skills](https://github.com/cometchat/cometchat-skills) to integrate via your AI coding agent. Your agent has a short conversation with you to understand your project and chat requirements, then writes production-grade integration code tailored to the files you already have.

```bash theme={null}
npx @cometchat/skills add
```

Use `--ide <name>` to target a specific IDE (e.g. `--ide cursor`), or `--ide all` for all supported IDEs.

Then in your IDE:

```
/cometchat add chat to my app
```

The skill detects your Expo setup (managed workflow + Expo Router), env prefix (`EXPO_PUBLIC_`), and existing auth system. It onboards you to CometChat directly in the terminal — signup, login, and app creation all via the CLI. It reads your screens, nav, and components before proposing a placement, shows the plan, and waits for your approval before writing code.

After the first integration, re-run `/cometchat` to access the iteration menu: theme presets, 40+ features, component customization, push notifications, production auth, user management, and diagnostics.

Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [30+ more agents](https://github.com/cometchat/cometchat-skills).

***

## Prerequisites

You need three things from the [CometChat Dashboard](https://app.cometchat.com/):

| Credential | Where to find it                                           |
| ---------- | ---------------------------------------------------------- |
| App ID     | Dashboard → Your App → Credentials                         |
| Auth Key   | Dashboard → Your App → Credentials                         |
| Region     | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) |

You also need:

* Node.js (v16+) and npm/yarn installed
* Expo CLI installed (`npm install -g expo-cli`)
* Xcode (for iOS) and Android Studio (for Android) for development builds

<Warning>
  Auth Key is for development only. In production, generate Auth Tokens server-side via the [REST API](/docs/rest-api/chat-apis) and use [`loginWithAuthToken()`](/docs/ui-kit/react-native/methods#how-to-login-a-user-with-auth-token). Never ship Auth Keys in client code.
</Warning>

***

## Step 1 — Create an Expo Project

```bash theme={null}
npx create-expo-app@latest MyApp --template blank-typescript
cd MyApp
```

***

## Step 2 — Install the UI Kit

```bash theme={null}
npm install @cometchat/chat-uikit-react-native
```

Install the SDK and peer dependencies:

```bash theme={null}
npm install @cometchat/chat-sdk-react-native
npm install @react-native-community/datetimepicker
npm install @react-native-clipboard/clipboard
npm install react-native-svg
npm install react-native-video
npm install dayjs
npm install @react-native-async-storage/async-storage
npm install react-native-gesture-handler
npm install react-native-localize
npm install react-native-safe-area-context
npm install punycode
```

### Configure app.json

Add required permissions for camera and microphone:

```json title="app.json" theme={null}
{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSCameraUsageDescription": "Camera access for video calls",
        "NSMicrophoneUsageDescription": "Microphone access for voice/video calls"
      }
    },
    "android": {
      "permissions": [
        "android.permission.INTERNET",
        "android.permission.CAMERA",
        "android.permission.MODIFY_AUDIO_SETTINGS",
        "android.permission.RECORD_AUDIO",
        "android.permission.ACCESS_NETWORK_STATE",
        "android.permission.WRITE_EXTERNAL_STORAGE",
        "android.permission.READ_EXTERNAL_STORAGE",
        "android.permission.VIBRATE"
      ]
    }
  }
}
```

### Optional: Install Calling SDK

To enable voice/video calling:

```bash theme={null}
npm install @cometchat/calls-sdk-react-native
npm install @react-native-community/netinfo
npm install react-native-background-timer
npm install react-native-callstats
npm install react-native-webrtc
```

***

## Step 3 — Initialize CometChat

<Warning>
  `init()` must resolve before you call `login()`. If you call `login()` before init completes, it will fail silently.
</Warning>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChatUIKit, UIKitSettings } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    const COMETCHAT_CONSTANTS = {
      APP_ID: "APP_ID",       // Replace with your App ID
      REGION: "REGION",       // Replace with your Region
      AUTH_KEY: "AUTH_KEY",   // Replace with your Auth Key (dev only)
    };

    const uiKitSettings: UIKitSettings = {
      appId: COMETCHAT_CONSTANTS.APP_ID,
      authKey: COMETCHAT_CONSTANTS.AUTH_KEY,
      region: COMETCHAT_CONSTANTS.REGION,
      subscriptionType: CometChat.AppSettings.SUBSCRIPTION_TYPE_ALL_USERS as UIKitSettings["subscriptionType"],
    };

    CometChatUIKit.init(uiKitSettings)
      .then(() => {
        console.log("CometChat UI Kit initialized successfully.");
      })
      .catch((error) => {
        console.error("CometChat UI Kit initialization failed:", error);
      });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    const COMETCHAT_CONSTANTS = {
      APP_ID: "APP_ID",       // Replace with your App ID
      REGION: "REGION",       // Replace with your Region
      AUTH_KEY: "AUTH_KEY",   // Replace with your Auth Key (dev only)
    };

    const uiKitSettings = {
      appId: COMETCHAT_CONSTANTS.APP_ID,
      authKey: COMETCHAT_CONSTANTS.AUTH_KEY,
      region: COMETCHAT_CONSTANTS.REGION,
      subscriptionType: CometChat.AppSettings.SUBSCRIPTION_TYPE_ALL_USERS,
    };

    CometChatUIKit.init(uiKitSettings)
      .then(() => {
        console.log("CometChat UI Kit initialized successfully.");
      })
      .catch((error) => {
        console.error("CometChat UI Kit initialization failed:", error);
      });
    ```
  </Tab>
</Tabs>

***

## Step 4 — Login

After init resolves, log the user in. For development, use one of the pre-created test UIDs:

`cometchat-uid-1` · `cometchat-uid-2` · `cometchat-uid-3` · `cometchat-uid-4` · `cometchat-uid-5`

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    const UID = "cometchat-uid-1"; // Replace with your actual UID

    CometChatUIKit.login({ uid: UID })
      .then((user: CometChat.User) => {
        console.log("Login Successful:", user.getName());
      })
      .catch((error) => {
        console.error("Login failed:", error);
      });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    const UID = "cometchat-uid-1"; // Replace with your actual UID

    CometChatUIKit.login({ uid: UID })
      .then((user) => {
        console.log("Login Successful:", user.getName());
      })
      .catch((error) => {
        console.error("Login failed:", error);
      });
    ```
  </Tab>
</Tabs>

<Note>
  For production, use [`loginWithAuthToken()`](/docs/ui-kit/react-native/methods#how-to-login-a-user-with-auth-token) instead of Auth Key. Generate tokens server-side via the REST API.
</Note>

***

## Step 5 — Choose a Chat Experience

Integrate a conversation view that suits your app's UX. Each option below includes a step-by-step guide.

### Conversation List + Message View

List of conversations on one screen, tap to open messages. Standard mobile chat pattern.

<Frame>
  <img />
</Frame>

<Card title="Build Conversation List + Message View" href="/ui-kit/react-native/expo-conversation" icon="comments">
  Step-by-step guide to build this layout
</Card>

***

### One-to-One / Group Chat

Single chat window — no conversation list. Good for support chat or focused messaging.

<Frame>
  <img />
</Frame>

<Card title="Build One-to-One / Group Chat" href="/ui-kit/react-native/expo-one-to-one-chat" icon="message">
  Step-by-step guide to build this layout
</Card>

***

### Tab-Based Chat

Tabbed navigation — Chats, Users, Groups, Calls in separate tabs. Good for full-featured apps.

<Frame>
  <img />
</Frame>

<Card title="Build Tab-Based Chat" href="/ui-kit/react-native/expo-tab-based-chat" icon="table-columns">
  Step-by-step guide to build this layout
</Card>

***

## Running Development Builds

Since Expo Go is not supported, you need to create development builds:

<Tabs>
  <Tab title="iOS">
    ```bash theme={null}
    npx expo run:ios
    ```
  </Tab>

  <Tab title="Android">
    ```bash theme={null}
    npx expo run:android
    ```
  </Tab>
</Tabs>

For more details, see the [Expo local app development guide](https://docs.expo.dev/guides/local-app-development/).

***

## Reference Implementation

For a complete working example, check out the [SampleAppExpo](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleAppExpo/) repository.

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and styles
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/react-native/core-features">
    Chat features included out of the box
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/react-native/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# One-to-One / Group Chat
Source: https://www.cometchat.com/docs/ui-kit/react-native/expo-one-to-one-chat

Build focused CometChat React Native UI Kit one-to-one or group chat screens in Expo with headers, message lists, and composers.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                              |
  | ------------ | ---------------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react-native`                                               |
  | Framework    | Expo                                                                               |
  | Components   | `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`       |
  | Layout       | Single chat window — no conversation list                                          |
  | Prerequisite | Complete [Expo Integration](/docs/ui-kit/react-native/expo-integration) Steps 1–4 first |
  | Pattern      | Support chat, embedded widgets, focused messaging                                  |
</Accordion>

This guide builds a single chat window — no conversation list. Users go directly into a one-to-one or group chat. Good for support chat, embedded widgets, or any focused messaging experience.

This assumes you've already completed [Expo Integration](/docs/ui-kit/react-native/expo-integration) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three components stacked vertically:

1. **Chat header** — displays recipient name, avatar, online status, and optional call buttons
2. **Message list** — real-time chat history with scrolling
3. **Message composer** — text input with media, emojis, and send button

***

## Step 1 — Update App.tsx

<Tabs>
  <Tab title="TypeScript">
    ```tsx title="App.tsx" theme={null}
    import React, { useEffect, useState } from "react";
    import { View, Text, StyleSheet } from "react-native";
    import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
    import { GestureHandlerRootView } from "react-native-gesture-handler";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
      CometChatUIKit,
      UIKitSettings,
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    const APP_ID = "APP_ID";
    const AUTH_KEY = "AUTH_KEY";
    const REGION = "REGION";
    const LOGIN_UID = "cometchat-uid-1";

    // The user or group to chat with
    const CHAT_WITH_UID = "cometchat-uid-2"; // Replace with actual UID
    // const CHAT_WITH_GUID = "GUID"; // Uncomment for group chat

    const App = (): React.ReactElement => {
      const [loggedIn, setLoggedIn] = useState(false);
      const [selectedUser, setSelectedUser] = useState<CometChat.User>();
      const [selectedGroup, setSelectedGroup] = useState<CometChat.Group>();

      useEffect(() => {
        const init = async () => {
          const uiKitSettings: UIKitSettings = {
            appId: APP_ID,
            authKey: AUTH_KEY,
            region: REGION,
            subscriptionType: CometChat.AppSettings
              .SUBSCRIPTION_TYPE_ALL_USERS as UIKitSettings["subscriptionType"],
          };

          try {
            await CometChatUIKit.init(uiKitSettings);
            await CometChatUIKit.login({ uid: LOGIN_UID });
            setLoggedIn(true);

            // Fetch the user to chat with
            const user = await CometChat.getUser(CHAT_WITH_UID);
            setSelectedUser(user);

            // For group chat, uncomment below:
            // const group = await CometChat.getGroup(CHAT_WITH_GUID);
            // setSelectedGroup(group);
          } catch (err) {
            console.error("Init/login/fetch error:", err);
          }
        };

        init();
      }, []);

      return (
        <GestureHandlerRootView style={{ flex: 1 }}>
          <SafeAreaProvider>
            <CometChatI18nProvider>
              <SafeAreaView style={styles.fullScreen}>
                <CometChatThemeProvider>
                  {loggedIn && (selectedUser || selectedGroup) ? (
                    <View style={styles.messagesWrapper}>
                      <CometChatMessageHeader
                        user={selectedUser}
                        group={selectedGroup}
                      />
                      <CometChatMessageList
                        user={selectedUser}
                        group={selectedGroup}
                      />
                      <CometChatMessageComposer
                        user={selectedUser}
                        group={selectedGroup}
                      />
                    </View>
                  ) : (
                    <View style={styles.emptyState}>
                      <Text style={styles.emptyText}>
                        Set a user or group UID in App.tsx to start chatting
                      </Text>
                    </View>
                  )}
                </CometChatThemeProvider>
              </SafeAreaView>
            </CometChatI18nProvider>
          </SafeAreaProvider>
        </GestureHandlerRootView>
      );
    };

    const styles = StyleSheet.create({
      fullScreen: {
        flex: 1,
      },
      messagesWrapper: {
        flex: 1,
      },
      emptyState: {
        flex: 1,
        justifyContent: "center",
        alignItems: "center",
        backgroundColor: "#F5F5F5",
      },
      emptyText: {
        color: "#727272",
        fontSize: 14,
      },
    });

    export default App;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="App.js" theme={null}
    import React, { useEffect, useState } from "react";
    import { View, Text, StyleSheet } from "react-native";
    import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
    import { GestureHandlerRootView } from "react-native-gesture-handler";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
      CometChatUIKit,
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    const APP_ID = "APP_ID";
    const AUTH_KEY = "AUTH_KEY";
    const REGION = "REGION";
    const LOGIN_UID = "cometchat-uid-1";

    // The user or group to chat with
    const CHAT_WITH_UID = "cometchat-uid-2"; // Replace with actual UID
    // const CHAT_WITH_GUID = "GUID"; // Uncomment for group chat

    const App = () => {
      const [loggedIn, setLoggedIn] = useState(false);
      const [selectedUser, setSelectedUser] = useState();
      const [selectedGroup, setSelectedGroup] = useState();

      useEffect(() => {
        const init = async () => {
          const uiKitSettings = {
            appId: APP_ID,
            authKey: AUTH_KEY,
            region: REGION,
            subscriptionType: CometChat.AppSettings.SUBSCRIPTION_TYPE_ALL_USERS,
          };

          try {
            await CometChatUIKit.init(uiKitSettings);
            await CometChatUIKit.login({ uid: LOGIN_UID });
            setLoggedIn(true);

            // Fetch the user to chat with
            const user = await CometChat.getUser(CHAT_WITH_UID);
            setSelectedUser(user);

            // For group chat, uncomment below:
            // const group = await CometChat.getGroup(CHAT_WITH_GUID);
            // setSelectedGroup(group);
          } catch (err) {
            console.error("Init/login/fetch error:", err);
          }
        };

        init();
      }, []);

      return (
        <GestureHandlerRootView style={{ flex: 1 }}>
          <SafeAreaProvider>
            <CometChatI18nProvider>
              <SafeAreaView style={styles.fullScreen}>
                <CometChatThemeProvider>
                  {loggedIn && (selectedUser || selectedGroup) ? (
                    <View style={styles.messagesWrapper}>
                      <CometChatMessageHeader
                        user={selectedUser}
                        group={selectedGroup}
                      />
                      <CometChatMessageList
                        user={selectedUser}
                        group={selectedGroup}
                      />
                      <CometChatMessageComposer
                        user={selectedUser}
                        group={selectedGroup}
                      />
                    </View>
                  ) : (
                    <View style={styles.emptyState}>
                      <Text style={styles.emptyText}>
                        Set a user or group UID in App.tsx to start chatting
                      </Text>
                    </View>
                  )}
                </CometChatThemeProvider>
              </SafeAreaView>
            </CometChatI18nProvider>
          </SafeAreaProvider>
        </GestureHandlerRootView>
      );
    };

    const styles = StyleSheet.create({
      fullScreen: {
        flex: 1,
      },
      messagesWrapper: {
        flex: 1,
      },
      emptyState: {
        flex: 1,
        justifyContent: "center",
        alignItems: "center",
        backgroundColor: "#F5F5F5",
      },
      emptyText: {
        color: "#727272",
        fontSize: 14,
      },
    });

    export default App;
    ```
  </Tab>
</Tabs>

***

## Switching Between User and Group Chat

To load a group chat instead of one-to-one, replace the `getUser` call with `getGroup`:

```tsx theme={null}
const CHAT_WITH_GUID = "GUID"; // Replace with your actual Group ID

const group = await CometChat.getGroup(CHAT_WITH_GUID);
setSelectedGroup(group);
```

***

## Step 2 — Run the Project

<Tabs>
  <Tab title="iOS">
    ```bash theme={null}
    npx expo run:ios
    ```
  </Tab>

  <Tab title="Android">
    ```bash theme={null}
    npx expo run:android
    ```
  </Tab>
</Tabs>

You should see the chat window load with the conversation for the UID you set.

***

## Next Steps

<CardGroup>
  <Card title="Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and styles to match your brand
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Expo Integration" icon="mobile" href="/ui-kit/react-native/expo-integration">
    Back to the main setup guide
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/react-native/core-features">
    Chat features included out of the box
  </Card>
</CardGroup>


# Tab-Based Chat
Source: https://www.cometchat.com/docs/ui-kit/react-native/expo-tab-based-chat

Build CometChat React Native UI Kit tab-based chat in Expo with conversations, users, groups, message views, and navigation.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                                                                            |
  | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react-native`                                                                                                                             |
  | Framework    | Expo                                                                                                                                                             |
  | Components   | `CometChatConversations`, `CometChatUsers`, `CometChatGroups`, `CometChatCallLogs`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Tabbed navigation (Chats, Users, Groups, Calls) + message view                                                                                                   |
  | Prerequisite | Complete [Expo Integration](/docs/ui-kit/react-native/expo-integration) Steps 1–4 first                                                                               |
  | Pattern      | Full-featured messaging app with multiple sections                                                                                                               |
</Accordion>

This guide builds a tabbed messaging UI — Chats, Users, Groups, and Calls tabs with bottom navigation, plus a message view when an item is selected. Good for full-featured apps that need more than just conversations.

This assumes you've already completed [Expo Integration](/docs/ui-kit/react-native/expo-integration) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three sections working together:

1. **Tab bar** — switches between Chats, Users, Groups, and Calls
2. **List screens** — renders the list for the active tab
3. **Message view** — header + messages + composer for the selected item

***

## Prerequisites

Install React Navigation dependencies:

```bash theme={null}
npx expo install @react-navigation/native @react-navigation/bottom-tabs @react-navigation/native-stack react-native-screens
```

***

## Step 1 — Create the Tab Screens

Create individual screen components for each tab:

<Tabs>
  <Tab title="TypeScript">
    ```tsx title="screens/ConversationsScreen.tsx" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import {
      CometChatConversations,
      CometChatUiKitConstants,
    } from "@cometchat/chat-uikit-react-native";
    import { NativeStackNavigationProp } from "@react-navigation/native-stack";

    type Props = {
      navigation: NativeStackNavigationProp<any>;
    };

    export function ConversationsScreen({ navigation }: Props) {
      const handleItemPress = (conversation: CometChat.Conversation) => {
        const conversationType = conversation.getConversationType();

        if (conversationType === CometChatUiKitConstants.ConversationTypeConstants.user) {
          const user = conversation.getConversationWith() as CometChat.User;
          navigation.navigate("Messages", { user });
        } else {
          const group = conversation.getConversationWith() as CometChat.Group;
          navigation.navigate("Messages", { group });
        }
      };

      return (
        <View style={{ flex: 1 }}>
          <CometChatConversations onItemPress={handleItemPress} />
        </View>
      );
    }
    ```

    ```tsx title="screens/UsersScreen.tsx" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
    import { NativeStackNavigationProp } from "@react-navigation/native-stack";

    type Props = {
      navigation: NativeStackNavigationProp<any>;
    };

    export function UsersScreen({ navigation }: Props) {
      const handleItemPress = (user: CometChat.User) => {
        navigation.navigate("Messages", { user });
      };

      return (
        <View style={{ flex: 1 }}>
          <CometChatUsers onItemPress={handleItemPress} />
        </View>
      );
    }
    ```

    ```tsx title="screens/GroupsScreen.tsx" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
    import { NativeStackNavigationProp } from "@react-navigation/native-stack";

    type Props = {
      navigation: NativeStackNavigationProp<any>;
    };

    export function GroupsScreen({ navigation }: Props) {
      const handleItemPress = (group: CometChat.Group) => {
        navigation.navigate("Messages", { group });
      };

      return (
        <View style={{ flex: 1 }}>
          <CometChatGroups onItemPress={handleItemPress} />
        </View>
      );
    }
    ```

    ```tsx title="screens/CallLogsScreen.tsx" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

    export function CallLogsScreen() {
      return (
        <View style={{ flex: 1 }}>
          <CometChatCallLogs />
        </View>
      );
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="screens/ConversationsScreen.js" theme={null}
    import React from "react";
    import { View } from "react-native";
    import {
      CometChatConversations,
      CometChatUiKitConstants,
    } from "@cometchat/chat-uikit-react-native";

    export function ConversationsScreen({ navigation }) {
      const handleItemPress = (conversation) => {
        const conversationType = conversation.getConversationType();

        if (conversationType === CometChatUiKitConstants.ConversationTypeConstants.user) {
          const user = conversation.getConversationWith();
          navigation.navigate("Messages", { user });
        } else {
          const group = conversation.getConversationWith();
          navigation.navigate("Messages", { group });
        }
      };

      return (
        <View style={{ flex: 1 }}>
          <CometChatConversations onItemPress={handleItemPress} />
        </View>
      );
    }
    ```

    ```jsx title="screens/UsersScreen.js" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChatUsers } from "@cometchat/chat-uikit-react-native";

    export function UsersScreen({ navigation }) {
      const handleItemPress = (user) => {
        navigation.navigate("Messages", { user });
      };

      return (
        <View style={{ flex: 1 }}>
          <CometChatUsers onItemPress={handleItemPress} />
        </View>
      );
    }
    ```

    ```jsx title="screens/GroupsScreen.js" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChatGroups } from "@cometchat/chat-uikit-react-native";

    export function GroupsScreen({ navigation }) {
      const handleItemPress = (group) => {
        navigation.navigate("Messages", { group });
      };

      return (
        <View style={{ flex: 1 }}>
          <CometChatGroups onItemPress={handleItemPress} />
        </View>
      );
    }
    ```

    ```jsx title="screens/CallLogsScreen.js" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

    export function CallLogsScreen() {
      return (
        <View style={{ flex: 1 }}>
          <CometChatCallLogs />
        </View>
      );
    }
    ```
  </Tab>
</Tabs>

***

## Step 2 — Create the Messages Screen

<Tabs>
  <Tab title="TypeScript">
    ```tsx title="screens/MessagesScreen.tsx" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
    } from "@cometchat/chat-uikit-react-native";
    import { RouteProp } from "@react-navigation/native";
    import { NativeStackNavigationProp } from "@react-navigation/native-stack";

    type MessagesRouteParams = {
      Messages: {
        user?: CometChat.User;
        group?: CometChat.Group;
      };
    };

    type Props = {
      route: RouteProp<MessagesRouteParams, "Messages">;
      navigation: NativeStackNavigationProp<any>;
    };

    export function MessagesScreen({ route, navigation }: Props) {
      const { user, group } = route.params;

      return (
        <View style={{ flex: 1 }}>
          <CometChatMessageHeader
            user={user}
            group={group}
            onBack={() => navigation.goBack()}
            showBackButton
          />
          <CometChatMessageList user={user} group={group} />
          <CometChatMessageComposer user={user} group={group} />
        </View>
      );
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="screens/MessagesScreen.js" theme={null}
    import React from "react";
    import { View } from "react-native";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
    } from "@cometchat/chat-uikit-react-native";

    export function MessagesScreen({ route, navigation }) {
      const { user, group } = route.params;

      return (
        <View style={{ flex: 1 }}>
          <CometChatMessageHeader
            user={user}
            group={group}
            onBack={() => navigation.goBack()}
            showBackButton
          />
          <CometChatMessageList user={user} group={group} />
          <CometChatMessageComposer user={user} group={group} />
        </View>
      );
    }
    ```
  </Tab>
</Tabs>

***

## Step 3 — Set Up Navigation

<Tabs>
  <Tab title="TypeScript">
    ```tsx title="App.tsx" theme={null}
    import React, { useEffect, useState } from "react";
    import { Image, StyleSheet } from "react-native";
    import { NavigationContainer } from "@react-navigation/native";
    import { createNativeStackNavigator } from "@react-navigation/native-stack";
    import { createBottomTabNavigator } from "@react-navigation/bottom-tabs";
    import { SafeAreaProvider } from "react-native-safe-area-context";
    import { GestureHandlerRootView } from "react-native-gesture-handler";
    import {
      CometChatUIKit,
      UIKitSettings,
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    import { ConversationsScreen } from "./screens/ConversationsScreen";
    import { UsersScreen } from "./screens/UsersScreen";
    import { GroupsScreen } from "./screens/GroupsScreen";
    import { CallLogsScreen } from "./screens/CallLogsScreen";
    import { MessagesScreen } from "./screens/MessagesScreen";

    const APP_ID = "APP_ID";
    const AUTH_KEY = "AUTH_KEY";
    const REGION = "REGION";
    const UID = "cometchat-uid-1";

    const Tab = createBottomTabNavigator();
    const Stack = createNativeStackNavigator();

    function TabNavigator() {
      return (
        <Tab.Navigator
          screenOptions={{
            tabBarActiveTintColor: "#6851D6",
            tabBarInactiveTintColor: "#808080",
            headerShown: false,
            tabBarStyle: styles.tabBar,
          }}
        >
          <Tab.Screen
            name="Chats"
            component={ConversationsScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/chats.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
          <Tab.Screen
            name="Users"
            component={UsersScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/users.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
          <Tab.Screen
            name="Groups"
            component={GroupsScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/groups.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
          <Tab.Screen
            name="Calls"
            component={CallLogsScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/calls.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
        </Tab.Navigator>
      );
    }

    export default function App() {
      const [loggedIn, setLoggedIn] = useState(false);

      useEffect(() => {
        const init = async () => {
          const uiKitSettings: UIKitSettings = {
            appId: APP_ID,
            authKey: AUTH_KEY,
            region: REGION,
            subscriptionType: CometChat.AppSettings
              .SUBSCRIPTION_TYPE_ALL_USERS as UIKitSettings["subscriptionType"],
          };

          try {
            await CometChatUIKit.init(uiKitSettings);
            await CometChatUIKit.login({ uid: UID });
            setLoggedIn(true);
          } catch (err) {
            console.error("Init/login error:", err);
          }
        };

        init();
      }, []);

      if (!loggedIn) return null;

      return (
        <GestureHandlerRootView style={{ flex: 1 }}>
          <SafeAreaProvider>
            <CometChatI18nProvider>
              <CometChatThemeProvider>
                <NavigationContainer>
                  <Stack.Navigator screenOptions={{ headerShown: false }}>
                    <Stack.Screen name="Home" component={TabNavigator} />
                    <Stack.Screen name="Messages" component={MessagesScreen} />
                  </Stack.Navigator>
                </NavigationContainer>
              </CometChatThemeProvider>
            </CometChatI18nProvider>
          </SafeAreaProvider>
        </GestureHandlerRootView>
      );
    }

    const styles = StyleSheet.create({
      tabBar: {
        backgroundColor: "#FFFFFF",
        borderTopWidth: 1,
        borderTopColor: "#E8E8E8",
        paddingBottom: 5,
        paddingTop: 5,
        height: 60,
      },
      tabIcon: {
        width: 24,
        height: 24,
      },
    });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="App.js" theme={null}
    import React, { useEffect, useState } from "react";
    import { Image, StyleSheet } from "react-native";
    import { NavigationContainer } from "@react-navigation/native";
    import { createNativeStackNavigator } from "@react-navigation/native-stack";
    import { createBottomTabNavigator } from "@react-navigation/bottom-tabs";
    import { SafeAreaProvider } from "react-native-safe-area-context";
    import { GestureHandlerRootView } from "react-native-gesture-handler";
    import {
      CometChatUIKit,
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    import { ConversationsScreen } from "./screens/ConversationsScreen";
    import { UsersScreen } from "./screens/UsersScreen";
    import { GroupsScreen } from "./screens/GroupsScreen";
    import { CallLogsScreen } from "./screens/CallLogsScreen";
    import { MessagesScreen } from "./screens/MessagesScreen";

    const APP_ID = "APP_ID";
    const AUTH_KEY = "AUTH_KEY";
    const REGION = "REGION";
    const UID = "cometchat-uid-1";

    const Tab = createBottomTabNavigator();
    const Stack = createNativeStackNavigator();

    function TabNavigator() {
      return (
        <Tab.Navigator
          screenOptions={{
            tabBarActiveTintColor: "#6851D6",
            tabBarInactiveTintColor: "#808080",
            headerShown: false,
            tabBarStyle: styles.tabBar,
          }}
        >
          <Tab.Screen
            name="Chats"
            component={ConversationsScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/chats.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
          <Tab.Screen
            name="Users"
            component={UsersScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/users.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
          <Tab.Screen
            name="Groups"
            component={GroupsScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/groups.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
          <Tab.Screen
            name="Calls"
            component={CallLogsScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/calls.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
        </Tab.Navigator>
      );
    }

    export default function App() {
      const [loggedIn, setLoggedIn] = useState(false);

      useEffect(() => {
        const init = async () => {
          const uiKitSettings = {
            appId: APP_ID,
            authKey: AUTH_KEY,
            region: REGION,
            subscriptionType: CometChat.AppSettings.SUBSCRIPTION_TYPE_ALL_USERS,
          };

          try {
            await CometChatUIKit.init(uiKitSettings);
            await CometChatUIKit.login({ uid: UID });
            setLoggedIn(true);
          } catch (err) {
            console.error("Init/login error:", err);
          }
        };

        init();
      }, []);

      if (!loggedIn) return null;

      return (
        <GestureHandlerRootView style={{ flex: 1 }}>
          <SafeAreaProvider>
            <CometChatI18nProvider>
              <CometChatThemeProvider>
                <NavigationContainer>
                  <Stack.Navigator screenOptions={{ headerShown: false }}>
                    <Stack.Screen name="Home" component={TabNavigator} />
                    <Stack.Screen name="Messages" component={MessagesScreen} />
                  </Stack.Navigator>
                </NavigationContainer>
              </CometChatThemeProvider>
            </CometChatI18nProvider>
          </SafeAreaProvider>
        </GestureHandlerRootView>
      );
    }

    const styles = StyleSheet.create({
      tabBar: {
        backgroundColor: "#FFFFFF",
        borderTopWidth: 1,
        borderTopColor: "#E8E8E8",
        paddingBottom: 5,
        paddingTop: 5,
        height: 60,
      },
      tabIcon: {
        width: 24,
        height: 24,
      },
    });
    ```
  </Tab>
</Tabs>

<Note>
  Download tab icons from the [CometChat UI Kit assets folder on GitHub](https://github.com/cometchat/cometchat-uikit-react-native) and place them in your `assets/` folder.
</Note>

***

## Step 4 — Run the Project

<Tabs>
  <Tab title="iOS">
    ```bash theme={null}
    npx expo run:ios
    ```
  </Tab>

  <Tab title="Android">
    ```bash theme={null}
    npx expo run:android
    ```
  </Tab>
</Tabs>

You should see the tab bar at the bottom. Switch between Chats, Users, Groups, and Calls — tapping any item navigates to the message view.

***

## Next Steps

<CardGroup>
  <Card title="Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and styles to match your brand
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Expo Integration" icon="mobile" href="/ui-kit/react-native/expo-integration">
    Back to the main setup guide
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/react-native/core-features">
    Chat features included out of the box
  </Card>
</CardGroup>


# Extensions
Source: https://www.cometchat.com/docs/ui-kit/react-native/extensions

Enable built-in extensions like stickers, polls, collaborative documents, message translation, and link previews in CometChat's React Native UI Kit.

<Info>
  **Quick Reference for AI Agents & Developers**

  Key components used by extensions:

  * **Message Composer** → [CometChatMessageComposer](/docs/ui-kit/react-native/message-composer) (stickers, polls, whiteboard, document)
  * **Message List** → [CometChatMessageList](/docs/ui-kit/react-native/message-list) (translation, link preview, thumbnails)

  Extensions are enabled from the [CometChat Dashboard](https://app.cometchat.com) — no additional code required.
</Info>

## Overview

CometChat's UI Kit comes with built-in support for a wide variety of extensions that provide additional functionality. These extensions enhance the chatting experience, making it more interactive, secure, and efficient.

Activating any extension in CometChat is a simple process done through your application's dashboard. For detailed information, refer to the [Extensions](/docs/fundamentals/extensions-overview) guide.

Once you have successfully enabled the desired extension in your dashboard, it will be reflected in your CometChat application upon initialization and successful login. The extension features will only be available if they are supported by the CometChat UI Kit.

CometChat's UI Kit offers built-in support for 12 powerful extensions. This seamless integration makes it easy to enhance your chat application with engaging features without any extra coding effort. Just enable the desired extensions from the CometChat Dashboard, and they will be automatically reflected in the relevant components of your application, providing a richer and more engaging experience for your users.

## Built-in Extensions

Here's a guide on how you can enable and integrate these extensions:

### Stickers

The Stickers extension allows users to express their emotions more creatively. It adds a fun element to the chat by allowing users to send various pre-designed stickers. For a comprehensive guide on implementing the Sticker Extension, refer to the [Sticker Extension](/docs/fundamentals/stickers) documentation.

Once you have activated the [Sticker Extension](/docs/fundamentals/stickers) from your CometChat Dashboard, the feature will automatically be incorporated into the [Message Composer](/docs/ui-kit/react-native/message-composer) component.

<Frame>
  <img />
</Frame>

### Polls

The Polls extension enhances group discussions by allowing users to create polls. Users can ask questions with a predefined list of answers, enabling a quick, organized way to gather group opinions. For a comprehensive guide, refer to the [Polls Extension](/docs/fundamentals/polls) documentation.

Once you have activated the [Polls Extension](/docs/fundamentals/polls) from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/docs/ui-kit/react-native/message-composer) component.

<Frame>
  <img />
</Frame>

### Collaborative Whiteboard

The Collaborative Whiteboard extension facilitates real-time collaboration. Users can draw, brainstorm, and share ideas on a shared digital whiteboard. For a comprehensive guide, refer to the [Collaborative Whiteboard Extension](/docs/fundamentals/collaborative-whiteboard) documentation.

Once you have activated the [Collaborative Whiteboard Extension](/docs/fundamentals/collaborative-whiteboard) from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/docs/ui-kit/react-native/message-composer) component.

<Frame>
  <img />
</Frame>

### Collaborative Document

With the Collaborative Document extension, users can work together on a shared document. This feature is essential for remote teams where document collaboration is a recurring requirement. For a comprehensive guide, refer to the [Collaborative Document Extension](/docs/fundamentals/collaborative-document) documentation.

Once you have activated the [Collaborative Document Extension](/docs/fundamentals/collaborative-document) from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/docs/ui-kit/react-native/message-composer) component.

<Frame>
  <img />
</Frame>

### Message Translation

The Message Translation extension translates any message into your local locale. It eliminates language barriers, making the chat more inclusive. For a comprehensive guide, refer to the [Message Translation Extension](/docs/fundamentals/message-translation) documentation.

Once you have activated the [Message Translation Extension](/docs/fundamentals/message-translation) from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [MessageList](/docs/ui-kit/react-native/message-list) component.

<Frame>
  <img />
</Frame>

### Link Preview

The Link Preview extension provides a summary of any URL shared in the chat. It includes the title, a description, and a thumbnail image from the web page. For a comprehensive guide, refer to the [Link Preview Extension](/docs/fundamentals/link-preview) documentation.

Once you have activated the [Link Preview Extension](/docs/fundamentals/link-preview) from your CometChat Dashboard, the feature will automatically be incorporated into the message bubble of the [MessageList](/docs/ui-kit/react-native/message-list) component.

<Frame>
  <img />
</Frame>

### Thumbnail Generation

The Thumbnail Generation extension automatically creates a smaller preview image whenever a larger image is shared, helping reduce upload/download time and bandwidth usage. For a comprehensive guide, refer to the [Thumbnail Generation Extension](/docs/fundamentals/thumbnail-generation) documentation.

Once you have activated the [Thumbnail Generation Extension](/docs/fundamentals/thumbnail-generation) from your CometChat Dashboard, the feature will automatically be incorporated into the message bubble of the [MessageList](/docs/ui-kit/react-native/message-list) component.

<Frame>
  <img />
</Frame>

***

## Next Steps

<CardGroup>
  <Card title="Core Features" icon="comments" href="/ui-kit/react-native/core-features">
    Explore messaging, receipts, typing indicators, and more
  </Card>

  <Card title="Call Features" icon="phone" href="/ui-kit/react-native/call-features">
    Add voice and video calling to your app
  </Card>

  <Card title="Message Composer" icon="pen" href="/ui-kit/react-native/message-composer">
    Customize the message input component
  </Card>

  <Card title="Message List" icon="list" href="/ui-kit/react-native/message-list">
    Customize how messages are displayed
  </Card>
</CardGroup>


# Group Members
Source: https://www.cometchat.com/docs/ui-kit/react-native/group-members

Display and manage group members with CometChatGroupMembers component in React Native UI Kit, including member roles, permissions, and moderation actions.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatGroupMembers",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatGroupMembers } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Scrollable, searchable list of members in a specific group with roles, scopes, online status, and member management actions.",
    "primaryOutput": {
      "prop": "onItemPress",
      "type": "(groupMember: CometChat.GroupMember) => void"
    },
    "props": {
      "data": {
        "group": {
          "type": "CometChat.Group",
          "required": true,
          "note": "The group whose members are displayed"
        },
        "groupMemberRequestBuilder": {
          "type": "CometChat.GroupMembersRequestBuilder",
          "default": "SDK default (30 per page)",
          "note": "Pass the builder, not the result of .build()"
        },
        "searchRequestBuilder": {
          "type": "CometChat.GroupMembersRequestBuilder",
          "default": "undefined"
        },
        "searchKeyword": {
          "type": "string",
          "default": "\"\""
        }
      },
      "callbacks": {
        "onItemPress": "(groupMember: CometChat.GroupMember) => void",
        "onItemLongPress": "(groupMember: CometChat.GroupMember) => void",
        "onBack": "() => void",
        "onSelection": "(list: CometChat.GroupMember[]) => void",
        "onSubmit": "(list: Array<CometChat.Conversation>) => void",
        "onError": "() => void",
        "onEmpty": "() => void",
        "onLoad": "(list: CometChat.GroupMember[]) => void"
      },
      "visibility": {
        "hideHeader": { "type": "boolean", "default": false },
        "showBackButton": { "type": "boolean", "default": false },
        "hideSearch": { "type": "boolean", "default": false },
        "hideError": { "type": "boolean", "default": false },
        "hideLoadingState": { "type": "boolean", "default": false },
        "usersStatusVisibility": { "type": "boolean", "default": true },
        "hideKickMemberOption": { "type": "boolean", "default": false },
        "hideBanMemberOption": { "type": "boolean", "default": false },
        "hideScopeChangeOption": { "type": "boolean", "default": false },
        "excludeOwner": { "type": "boolean", "default": false },
        "hideSubmitButton": { "type": "boolean", "default": false }
      },
      "selection": {
        "selectionMode": {
          "type": "SelectionMode",
          "values": ["single", "multiple", "none"],
          "default": "none"
        }
      },
      "viewSlots": {
        "ItemView": "(groupMember: CometChat.GroupMember) => JSX.Element",
        "LeadingView": "(groupMember: CometChat.GroupMember) => JSX.Element",
        "TitleView": "(groupMember: CometChat.GroupMember) => JSX.Element",
        "SubtitleView": "(groupMember: CometChat.GroupMember) => JSX.Element",
        "TrailingView": "(groupMember: CometChat.GroupMember) => JSX.Element",
        "LoadingView": "() => JSX.Element",
        "EmptyView": "() => JSX.Element",
        "ErrorView": "() => JSX.Element",
        "AppBarOptions": "() => JSX.Element"
      }
    },
    "events": [
      {
        "name": "ccGroupMemberKicked",
        "payload": "IGroupMemberKickedBanned",
        "description": "Triggered when a group member is kicked"
      },
      {
        "name": "ccGroupMemberBanned",
        "payload": "IGroupMemberKickedBanned",
        "description": "Triggered when a group member is banned"
      },
      {
        "name": "ccGroupMemberScopeChanged",
        "payload": "IGroupMemberScopeChanged",
        "description": "Triggered when a group member's scope is changed"
      }
    ],
    "sdkListeners": [
      "onGroupMemberScopeChanged",
      "onGroupMemberKicked",
      "onGroupMemberBanned",
      "onMemberAddedToGroup",
      "onGroupMemberLeft",
      "onGroupMemberJoined"
    ],
    "compositionExample": {
      "description": "Group members panel wired to group chat view",
      "components": [
        "CometChatGroupMembers",
        "CometChatMessageHeader",
        "CometChatMessageList",
        "CometChatMessageComposer"
      ],
      "flow": "Fetch group -> pass to GroupMembers, MessageHeader, MessageList, MessageComposer"
    },
    "types": {
      "SelectionMode": {
        "single": "Select one member at a time",
        "multiple": "Select multiple members",
        "none": "No selection mode"
      }
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatGroupMembers` is a panel component that renders the member list for a specific group. It requires a `group` prop and provides built-in member management actions (kick, ban, scope change) based on the logged-in user's role. Typically rendered alongside the message view in a group chat layout.

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";

function GroupMembersDemo() {
  const [group, setGroup] = useState<CometChat.Group | undefined>(undefined);

  useEffect(() => {
    CometChat.getGroup("GROUP_GUID").then(setGroup);
  }, []);

  return group ? <CometChatGroupMembers group={group} /> : null;
}

export default GroupMembersDemo;
```

***

## Filtering Group Members

Pass a `CometChat.GroupMembersRequestBuilder` to `groupMemberRequestBuilder`. Pass the builder instance — not the result of `.build()`.

The [GroupMembersRequestBuilder](/docs/sdk/react-native/retrieve-group-members) enables you to filter and customize the group members list based on available parameters. The following are the parameters available in [GroupMembersRequestBuilder](/docs/sdk/react-native/retrieve-group-members):

| Methods              | Type           | Description                                                                                       |
| -------------------- | -------------- | ------------------------------------------------------------------------------------------------- |
| **setLimit**         | number         | sets the number of group members that can be fetched in a single request, suitable for pagination |
| **setSearchKeyword** | string         | used for fetching group members matching the passed string                                        |
| **setScopes**        | Array\<string> | used for fetching group members based on multiple scopes                                          |

```tsx lines theme={null}
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";

function FilteredGroupMembers() {
  const [group, setGroup] = useState<CometChat.Group | undefined>(undefined);

  useEffect(() => {
    CometChat.getGroup("GROUP_GUID").then(setGroup);
  }, []);

  if (!group) return null;

  return (
    <CometChatGroupMembers
      group={group}
      groupMemberRequestBuilder={
        new CometChat.GroupMembersRequestBuilder(group.getGuid())
          .setScopes(["admin", "moderator"])
          .setLimit(10)
      }
    />
  );
}
```

### Filter Recipes

| Recipe                     | Code                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------ |
| Limit to 10 per page       | `new CometChat.GroupMembersRequestBuilder("GUID").setLimit(10)`                      |
| Search by keyword          | `new CometChat.GroupMembersRequestBuilder("GUID").setSearchKeyword("john")`          |
| Admins and moderators only | `new CometChat.GroupMembersRequestBuilder("GUID").setScopes(["admin", "moderator"])` |

Default page size is 30. The component uses infinite scroll — the next page loads as the user scrolls to the bottom.

### SearchRequestBuilder

The `searchRequestBuilder` prop accepts a separate `GroupMembersRequestBuilder` for filtering when the search bar is active. This allows you to keep uniformity between the displayed Group Members List and searched Group Members List.

```tsx lines theme={null}
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";

function SearchGroupMembers() {
  const [group, setGroup] = useState<CometChat.Group | undefined>(undefined);

  useEffect(() => {
    CometChat.getGroup("GROUP_GUID").then(setGroup);
  }, []);

  if (!group) return null;

  const searchRequestBuilder = new CometChat.GroupMembersRequestBuilder(
    group.getGuid()
  )
    .setScopes(["admin"])
    .setSearchKeyword("custom-keyword");

  return (
    <CometChatGroupMembers
      group={group}
      searchRequestBuilder={searchRequestBuilder}
    />
  );
}
```

Refer to [GroupMembersRequestBuilder](/docs/sdk/react-native/retrieve-group-members) for the full builder API.

***

## Actions and Events

### Callback Props

#### onItemPress

Fires when a member row is tapped.

```tsx lines theme={null}
onItemPress?: (groupMember: CometChat.GroupMember) => void
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function GroupMembersWithPress({ group }: { group: CometChat.Group }) {
  return (
    <CometChatGroupMembers
      group={group}
      onItemPress={(member: CometChat.GroupMember) => {
        console.log("Selected member:", member.getName());
      }}
    />
  );
}
```

#### onItemLongPress

Fires when a member item is long-pressed, allowing additional actions like delete or block.

```tsx lines theme={null}
onItemLongPress?: (groupMember: CometChat.GroupMember) => void
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function GroupMembersWithLongPress({ group }: { group: CometChat.Group }) {
  return (
    <CometChatGroupMembers
      group={group}
      onItemLongPress={(member: CometChat.GroupMember) => {
        console.log("Long pressed:", member.getName());
      }}
    />
  );
}
```

#### onBack

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

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";

function GroupMembersWithBack({ group }: { group: CometChat.Group }) {
  return (
    <CometChatGroupMembers
      group={group}
      showBackButton={true}
      onBack={() => {
        console.log("Back pressed");
      }}
    />
  );
}
```

#### onSelection

Fires when members are selected/deselected in selection mode. Requires `selectionMode` to be set.

```tsx lines theme={null}
onSelection?: (list: CometChat.GroupMember[]) => void
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function GroupMembersWithSelection({ group }: { group: CometChat.Group }) {
  const handleSelection = (list: CometChat.GroupMember[]) => {
    console.log("Selected:", list.length);
  };

  return (
    <CometChatGroupMembers
      group={group}
      selectionMode={"single"}
      onSelection={handleSelection}
    />
  );
}
```

#### onSubmit

Fires when the submit selection button is pressed. Requires `selectionMode` to be set.

```tsx lines theme={null}
onSubmit?: (list: Array<CometChat.Conversation>) => void
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function GroupMembersWithSubmit({ group }: { group: CometChat.Group }) {
  const handleSubmit = (list: Array<CometChat.Conversation>) => {
    console.log("Submit", list);
  };

  return <CometChatGroupMembers group={group} onSubmit={handleSubmit} />;
}
```

#### onError

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

```tsx lines theme={null}
onError?: () => void
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function GroupMembersWithError({ group }: { group: CometChat.Group }) {
  return (
    <CometChatGroupMembers
      group={group}
      onError={() => {
        console.error("CometChatGroupMembers error occurred");
      }}
    />
  );
}
```

#### onLoad

Fires when the list is successfully fetched and loaded.

```tsx lines theme={null}
onLoad?: (list: CometChat.GroupMember[]) => void
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function GroupMembersWithLoad({ group }: { group: CometChat.Group }) {
  const handleLoad = (list: CometChat.GroupMember[]) => {
    console.log("Loaded members:", list.length);
  };

  return <CometChatGroupMembers group={group} onLoad={handleLoad} />;
}
```

#### onEmpty

Fires when the member list is empty.

```tsx lines theme={null}
onEmpty?: () => void
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";

function GroupMembersWithEmpty({ group }: { group: CometChat.Group }) {
  return (
    <CometChatGroupMembers
      group={group}
      onEmpty={() => {
        console.log("No group members found");
      }}
    />
  );
}
```

### Global UI Events

`CometChatUIEventHandler` emits events subscribable from anywhere in the application. Add listeners and remove them on cleanup.

| Event                       | Fires when                        | Payload                    |
| --------------------------- | --------------------------------- | -------------------------- |
| `ccGroupMemberKicked`       | A member is kicked from the group | `IGroupMemberKickedBanned` |
| `ccGroupMemberBanned`       | A member is banned from the group | `IGroupMemberKickedBanned` |
| `ccGroupMemberScopeChanged` | A member's scope is changed       | `IGroupMemberScopeChanged` |

When to use: sync external UI with group member state changes. For example, update a member list when a member is kicked, or refresh the UI when a member's scope changes.

```tsx lines theme={null}
import { useEffect } from "react";
import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function useGroupMemberEvents() {
  useEffect(() => {
    const listenerId = "GROUP_MEMBER_EVENTS_" + Date.now();

    CometChatUIEventHandler.addGroupListener(listenerId, {
      ccGroupMemberKicked: ({
        message,
        kickedFrom,
      }: {
        message: CometChat.BaseMessage;
        kickedFrom: CometChat.Group;
      }) => {
        console.log("Member kicked from:", kickedFrom.getName());
      },
      ccGroupMemberBanned: ({
        message,
        kickedUser,
        kickedBy,
        kickedFrom,
      }: {
        message: CometChat.BaseMessage;
        kickedUser: CometChat.User;
        kickedBy: CometChat.User;
        kickedFrom: CometChat.Group;
      }) => {
        console.log("Member banned:", kickedUser.getName());
      },
      ccGroupMemberScopeChanged: ({
        action,
        updatedUser,
        scopeChangedTo,
        scopeChangedFrom,
        group,
      }) => {
        console.log("Scope changed:", updatedUser.getName(), "to", scopeChangedTo);
      },
    });

    return () => {
      CometChatUIEventHandler.removeGroupListener(listenerId);
    };
  }, []);
}
```

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual attachment needed unless additional side effects are required.

| SDK Listener                | Internal behavior                         |
| --------------------------- | ----------------------------------------- |
| `onGroupMemberScopeChanged` | Updates the member's scope in the list    |
| `onGroupMemberKicked`       | Removes the kicked member from the list   |
| `onGroupMemberBanned`       | Removes the banned member from the list   |
| `onMemberAddedToGroup`      | Appends the new member to the list        |
| `onGroupMemberLeft`         | Removes the member who left from the list |
| `onGroupMemberJoined`       | Appends the joined member to the list     |

<Note>
  In React 18 StrictMode, `useEffect` runs twice on mount in development. The component handles listener cleanup internally, but any additional listeners added alongside the component need cleanup in the `useEffect` return function to avoid duplicate event handling.
</Note>

***

## Custom View Slots

Each slot replaces a section of the default UI. Slots that accept a member parameter receive the `CometChat.GroupMember` object for that row.

| Slot            | Signature                                             | Replaces                              |
| --------------- | ----------------------------------------------------- | ------------------------------------- |
| `ItemView`      | `(groupMember: CometChat.GroupMember) => JSX.Element` | Entire list item row                  |
| `LeadingView`   | `(groupMember: CometChat.GroupMember) => JSX.Element` | Avatar / left section                 |
| `TitleView`     | `(groupMember: CometChat.GroupMember) => JSX.Element` | Name / title text                     |
| `SubtitleView`  | `(groupMember: CometChat.GroupMember) => JSX.Element` | Subtitle text                         |
| `TrailingView`  | `(groupMember: CometChat.GroupMember) => JSX.Element` | Right section (scope badge / actions) |
| `LoadingView`   | `() => JSX.Element`                                   | Loading spinner                       |
| `EmptyView`     | `() => JSX.Element`                                   | Empty state                           |
| `ErrorView`     | `() => JSX.Element`                                   | Error state                           |
| `AppBarOptions` | `() => JSX.Element`                                   | Header bar options                    |

### LoadingView

Custom view displayed when data is being fetched.

```tsx lines theme={null}
LoadingView?: () => JSX.Element
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";

const getLoadingView = (): JSX.Element => {
  return <Text>Loading group members...</Text>;
};

return <CometChatGroupMembers group={group} LoadingView={getLoadingView} />;
```

### EmptyView

Custom view displayed when there are no group members.

```tsx lines theme={null}
EmptyView?: () => JSX.Element
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";

const getEmptyView = (): JSX.Element => {
  return <Text>No members in this group yet.</Text>;
};

return <CometChatGroupMembers group={group} EmptyView={getEmptyView} />;
```

### ErrorView

Custom view displayed when an error occurs.

```tsx lines theme={null}
ErrorView?: () => JSX.Element
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";

const getErrorView = (): JSX.Element => {
  return <Text>Failed to load members. Please try again.</Text>;
};

return <CometChatGroupMembers group={group} ErrorView={getErrorView} />;
```

### LeadingView

Custom view for the avatar / left section of each member item.

```tsx lines theme={null}
LeadingView?: (groupMember: CometChat.GroupMember) => JSX.Element
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const getLeadingView = (groupMember: CometChat.GroupMember): JSX.Element => {
  return (
    <View style={{ width: 40, height: 40, borderRadius: 20, backgroundColor: '#6852D6' }}>
      <Text style={{ color: 'white', textAlign: 'center', lineHeight: 40 }}>
        {groupMember.getName().charAt(0)}
      </Text>
    </View>
  );
};

return <CometChatGroupMembers group={group} LeadingView={getLeadingView} />;
```

### TitleView

Custom view for the name / title text.

```tsx lines theme={null}
TitleView?: (groupMember: CometChat.GroupMember) => JSX.Element
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const getTitleView = (groupMember: CometChat.GroupMember): JSX.Element => {
  return (
    <Text style={{ fontWeight: 'bold', fontSize: 16 }}>
      {groupMember.getName()}
    </Text>
  );
};

return <CometChatGroupMembers group={group} TitleView={getTitleView} />;
```

### SubtitleView

Custom view for the subtitle text.

```tsx lines theme={null}
SubtitleView?: (groupMember: CometChat.GroupMember) => JSX.Element
```

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const getSubtitleView = (groupMember: CometChat.GroupMember): JSX.Element => {
  return (
    <Text style={{ fontSize: 12, color: '#727272' }}>
      {groupMember.getScope()}
    </Text>
  );
};

return <CometChatGroupMembers group={group} SubtitleView={getSubtitleView} />;
```

### TrailingView

Custom view for the right section (scope badge / actions).

```tsx lines theme={null}
TrailingView?: (groupMember: CometChat.GroupMember) => JSX.Element
```

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const getTrailingView = (groupMember: CometChat.GroupMember): JSX.Element => {
  return (
    <TouchableOpacity onPress={() => { /* action */ }}>
      <Text style={{ color: '#6852D6' }}>{groupMember.getScope()}</Text>
    </TouchableOpacity>
  );
};

return <CometChatGroupMembers group={group} TrailingView={getTrailingView} />;
```

### ItemView

Custom view for the entire list item row.

```tsx lines theme={null}
ItemView?: (groupMember: CometChat.GroupMember) => JSX.Element
```

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import {
  CometChatGroupMembers,
  CometChatAvatar,
  useTheme,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const theme = useTheme();

const getItemView = (groupMember: CometChat.GroupMember): JSX.Element => {
  return (
    <View
      style={{
        flexDirection: 'row',
        flex: 1,
        paddingHorizontal: 16,
        paddingVertical: 12,
        alignItems: 'center',
        borderWidth: 1,
        borderColor: theme.color.borderLight,
      }}>
      <CometChatAvatar
        name={groupMember.getName()}
        image={{ uri: groupMember.getAvatar() }}
        style={{
          containerStyle: { borderRadius: 8 },
          imageStyle: { borderRadius: 8 },
        }}
      />
      <View style={{ flex: 1, marginLeft: 12 }}>
        <Text
          style={{
            color: theme.color.textPrimary,
            fontSize: 16,
            fontWeight: '500',
          }}
          numberOfLines={1}
          ellipsizeMode="tail">
          {groupMember.getName()}
        </Text>
        <Text style={{ color: theme.color.textSecondary, fontSize: 12 }}>
          {groupMember.getScope()}
        </Text>
      </View>
    </View>
  );
};

return <CometChatGroupMembers group={group} ItemView={getItemView} />;
```

### AppBarOptions

Custom view for the header bar options.

```tsx lines theme={null}
AppBarOptions?: () => JSX.Element
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";

return (
  <CometChatGroupMembers
    group={group}
    AppBarOptions={() => {
      return (
        <TouchableOpacity onPress={() => { /* handle click */ }}>
          <Text>Custom App Bar Options</Text>
        </TouchableOpacity>
      );
    }}
  />
);
```

### options

Custom context menu actions for each member item.

```tsx lines theme={null}
options?: (groupMember: CometChat.GroupMember, group: CometChat.Group) => MenuItemInterface[]
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const setMyOptions = (member: CometChat.GroupMember, group: CometChat.Group) => {
  return [
    {
      text: "View Profile",
      onPress: () => { /* view profile logic */ },
    },
    {
      text: "Remove",
      onPress: () => { /* remove logic */ },
    },
  ];
};

return <CometChatGroupMembers group={group} options={setMyOptions} />;
```

### addOptions

Extends the default context menu actions with additional options.

```tsx lines theme={null}
addOptions?: (groupMember: CometChat.GroupMember, group: CometChat.Group) => MenuItemInterface[]
```

```tsx lines theme={null}
import { CometChatGroupMembers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const addOptions = (member: CometChat.GroupMember, group: CometChat.Group) => {
  return [
    {
      text: "Report Member",
      onPress: () => { /* report logic */ },
    },
  ];
};

return <CometChatGroupMembers group={group} addOptions={addOptions} />;
```

***

## 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 `CometChatGroupMembers` component.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import {
  CometChatGroupMembers,
  useTheme,
} from "@cometchat/chat-uikit-react-native";

const theme = useTheme();

return (
  <CometChatGroupMembers
    group={group}
    style={{
      titleSeparatorStyle: {
        borderBottomColor: "#F76808",
      },
      titleStyle: {
        color: "#F76808",
      },
      backButtonIconStyle: {
        tintColor: "#F76808",
      },
      ownerBadgeStyle: {
        containerStyle: {
          backgroundColor: "#F76808",
          borderColor: "#F76808",
        },
        textStyle: {
          ...theme.typography.caption1.regular,
          color: theme.color.staticWhite,
        },
      },
      adminBadgeStyle: {
        containerStyle: {
          backgroundColor: "#FEEDE1",
          borderColor: "#F76808",
        },
        textStyle: {
          ...theme.typography.caption1.regular,
          color: "#F76808",
        },
      },
      moderatorBadgeStyle: {
        containerStyle: {
          backgroundColor: "#FEEDE1",
        },
        textStyle: {
          ...theme.typography.caption1.regular,
          color: "#F76808",
        },
      },
    }}
  />
);
```

### Visibility Props

| Property                | Description                                           | Code                              |
| ----------------------- | ----------------------------------------------------- | --------------------------------- |
| `hideHeader`            | Toggle visibility for the toolbar/header              | `hideHeader?: boolean`            |
| `showBackButton`        | Toggle visibility for back button                     | `showBackButton?: boolean`        |
| `hideSearch`            | Toggle visibility for search box                      | `hideSearch?: boolean`            |
| `hideError`             | Hide error on fetching group members                  | `hideError?: boolean`             |
| `hideLoadingState`      | Toggle visibility for Loading state                   | `hideLoadingState?: boolean`      |
| `usersStatusVisibility` | Toggle visibility for user status indicators          | `usersStatusVisibility?: boolean` |
| `hideKickMemberOption`  | Hide the "Remove" (Kick) option from the default menu | `hideKickMemberOption?: boolean`  |
| `hideBanMemberOption`   | Hide the "Ban" option from the default menu           | `hideBanMemberOption?: boolean`   |
| `hideScopeChangeOption` | Hide the "Change Scope" option from the default menu  | `hideScopeChangeOption?: boolean` |
| `excludeOwner`          | Exclude the group owner from the members list         | `excludeOwner?: boolean`          |

### Selection Mode

| Property                | Description                                     | Code                             |
| ----------------------- | ----------------------------------------------- | -------------------------------- |
| `selectionMode`         | Determines the selection mode for group members | `selectionMode?: SelectionMode`  |
| `searchKeyword`         | Keyword used to fetch initial member list       | `searchKeyword?: string`         |
| `searchPlaceholderText` | Placeholder text for search input               | `searchPlaceholderText?: string` |

***

## Next Steps

<CardGroup>
  <Card title="Groups" icon="user-group" href="/ui-kit/react-native/groups">
    Display and manage group conversations
  </Card>

  <Card title="Add Members" icon="user-plus" href="/ui-kit/react-native/group-members">
    Add new members to a group
  </Card>

  <Card title="Banned Members" icon="ban" href="/ui-kit/react-native/group-members">
    View and manage banned group members
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>


# Groups
Source: https://www.cometchat.com/docs/ui-kit/react-native/groups

Searchable, scrollable list of all available groups with icon, name, member count, and group type indicator.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatGroups",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatGroups } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Searchable, scrollable list of all available groups with icon, name, member count, and group type indicator.",
    "primaryOutput": {
      "prop": "onItemPress",
      "type": "(group: CometChat.Group) => void"
    },
    "props": {
      "data": {
        "groupsRequestBuilder": {
          "type": "CometChat.GroupsRequestBuilder",
          "default": "SDK default (30 per page)",
          "note": "Pass the builder, not the result of .build()"
        },
        "searchRequestBuilder": {
          "type": "CometChat.GroupsRequestBuilder",
          "default": "undefined"
        },
        "searchKeyword": {
          "type": "string",
          "default": "\"\""
        }
      },
      "callbacks": {
        "onItemPress": "(group: CometChat.Group) => void",
        "onItemLongPress": "(group: CometChat.Group) => void",
        "onBack": "() => void",
        "onSelection": "(list: Array<CometChat.Group>) => void",
        "onSubmit": "(list: Array<CometChat.Group>) => void",
        "onError": "(error: CometChat.CometChatException) => void",
        "onEmpty": "() => void",
        "onLoad": "(list: CometChat.GroupMember[]) => void"
      },
      "visibility": {
        "hideHeader": { "type": "boolean", "default": false },
        "showBackButton": { "type": "boolean", "default": false },
        "hideSearch": { "type": "boolean", "default": false },
        "hideError": { "type": "boolean", "default": false },
        "hideSubmitButton": { "type": "boolean", "default": true },
        "hideLoadingState": { "type": "boolean", "default": false },
        "groupTypeVisibility": { "type": "boolean", "default": true }
      },
      "icons": {
        "privateGroupIcon": { "type": "ImageSourcePropType", "default": "built-in" },
        "passwordGroupIcon": { "type": "ImageSourcePropType", "default": "built-in" }
      },
      "menu": {
        "options": "(group: CometChat.Group) => MenuItemInterface[]",
        "addOptions": "(group: CometChat.Group) => MenuItemInterface[]"
      },
      "search": {
        "searchPlaceholderText": { "type": "string", "default": "\"Search\"" }
      },
      "selection": {
        "selectionMode": {
          "type": "SelectionMode",
          "values": ["single", "multiple", "none"],
          "default": "none"
        }
      },
      "viewSlots": {
        "ItemView": "(group: CometChat.Group) => JSX.Element",
        "LeadingView": "(group: CometChat.Group) => JSX.Element",
        "TitleView": "(group: CometChat.Group) => JSX.Element",
        "SubtitleView": "(group: CometChat.Group) => JSX.Element",
        "TrailingView": "(group: CometChat.Group) => JSX.Element",
        "LoadingView": "() => JSX.Element",
        "EmptyView": "() => JSX.Element",
        "ErrorView": "() => JSX.Element",
        "AppBarOptions": "() => JSX.Element"
      }
    },
    "events": [
      { "name": "ccGroupCreated", "payload": "CometChat.Group", "description": "Triggered when logged-in user creates a group" },
      { "name": "ccGroupDeleted", "payload": "CometChat.Group", "description": "Triggered when logged-in user deletes a group" },
      { "name": "ccGroupLeft", "payload": "{ leftGroup: CometChat.Group }", "description": "Triggered when logged-in user leaves a group" },
      { "name": "ccGroupMemberScopeChanged", "payload": "IGroupMemberScopeChanged", "description": "Triggered when logged-in user changes scope of another member" },
      { "name": "ccGroupMemberBanned", "payload": "IGroupMemberKickedBanned", "description": "Triggered when logged-in user bans a group member" },
      { "name": "ccGroupMemberKicked", "payload": "IGroupMemberKickedBanned", "description": "Triggered when logged-in user kicks a group member" },
      { "name": "ccGroupMemberUnbanned", "payload": "IGroupMemberUnBanned", "description": "Triggered when logged-in user unbans a group member" },
      { "name": "ccGroupMemberJoined", "payload": "IGroupMemberJoined", "description": "Triggered when logged-in user joins a group" },
      { "name": "ccGroupMemberAdded", "payload": "IGroupMemberAdded", "description": "Triggered when logged-in user adds members to a group" },
      { "name": "ccOwnershipChanged", "payload": "IOwnershipChanged", "description": "Triggered when logged-in user transfers group ownership" }
    ],
    "sdkListeners": [
      "onGroupMemberJoined",
      "onGroupMemberLeft",
      "onMemberAddedToGroup",
      "onGroupMemberKicked",
      "onGroupMemberBanned",
      "onGroupMemberScopeChanged"
    ],
    "compositionExample": {
      "description": "Group directory wired to message view",
      "components": [
        "CometChatGroups",
        "CometChatMessageHeader",
        "CometChatMessageList",
        "CometChatMessageComposer"
      ],
      "flow": "onItemPress emits CometChat.Group -> pass to MessageHeader, MessageList, MessageComposer"
    },
    "types": {
      "SelectionMode": {
        "single": "Select one group at a time",
        "multiple": "Select multiple groups",
        "none": "No selection mode"
      }
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatGroups` is a directory list component. It renders all available groups and emits the selected `CometChat.Group` via `onItemPress`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a group chat layout.

```tsx lines theme={null}
import { useState } from "react";
import { View, Text, StyleSheet } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { SafeAreaProvider } from "react-native-safe-area-context";
import {
  CometChatGroups,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ChatApp() {
  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group>();

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <SafeAreaProvider>
        <CometChatThemeProvider>
          <View style={styles.container}>
            <View style={styles.sidebar}>
              <CometChatGroups onItemPress={(group) => setSelectedGroup(group)} />
            </View>
            {selectedGroup ? (
              <View style={styles.chatArea}>
                <CometChatMessageHeader group={selectedGroup} />
                <CometChatMessageList group={selectedGroup} />
                <CometChatMessageComposer group={selectedGroup} />
              </View>
            ) : (
              <View style={styles.placeholder}>
                <Text>Select a group</Text>
              </View>
            )}
          </View>
        </CometChatThemeProvider>
      </SafeAreaProvider>
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, flexDirection: "row" },
  sidebar: { width: 350 },
  chatArea: { flex: 1 },
  placeholder: { flex: 1, justifyContent: "center", alignItems: "center" },
});
```

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";

function GroupsDemo() {
  return <CometChatGroups />;
}

export default GroupsDemo;
```

***

## Filtering Groups

Pass a `CometChat.GroupsRequestBuilder` to `groupsRequestBuilder`. Pass the builder instance — not the result of `.build()`.

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function FilteredGroups() {
  return (
    <CometChatGroups
      groupsRequestBuilder={
        new CometChat.GroupsRequestBuilder().joinedOnly(true).setLimit(10)
      }
    />
  );
}
```

### Filter Recipes

| Recipe               | Code                                                              |
| -------------------- | ----------------------------------------------------------------- |
| Joined groups only   | `new CometChat.GroupsRequestBuilder().joinedOnly(true)`           |
| Limit to 10 per page | `new CometChat.GroupsRequestBuilder().setLimit(10)`               |
| Search by keyword    | `new CometChat.GroupsRequestBuilder().setSearchKeyword("design")` |
| Filter by tags       | `new CometChat.GroupsRequestBuilder().setTags(["vip"])`           |
| With tags data       | `new CometChat.GroupsRequestBuilder().withTags(true)`             |

Default page size is 30. The component uses infinite scroll — the next page loads as the user scrolls to the bottom.

A separate `searchRequestBuilder` can be passed to filter the search list independently from the main list.

Refer to [GroupsRequestBuilder](/docs/sdk/react-native/retrieve-groups) for the full builder API.

***

## Actions and Events

### Callback Props

#### onItemPress

Fires when a group row is tapped. Primary navigation hook — set the active group and render the message view.

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function GroupsWithPress() {
  const handleItemPress = (group: CometChat.Group) => {
    console.log("Selected:", group.getName());
  };

  return <CometChatGroups onItemPress={handleItemPress} />;
}
```

#### onItemLongPress

Fires when a group item is long-pressed, allowing additional actions like leave or delete.

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function GroupsWithLongPress() {
  const handleLongPress = (group: CometChat.Group) => {
    console.log("Long pressed:", group.getName());
  };

  return <CometChatGroups onItemLongPress={handleLongPress} />;
}
```

#### onSelection

Fires when groups are selected/deselected in selection mode. Requires `selectionMode` to be set.

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function GroupsWithSelection() {
  const handleSelection = (list: Array<CometChat.Group>) => {
    console.log("Selected:", list.length);
  };

  return (
    <CometChatGroups
      selectionMode="multiple"
      onSelection={handleSelection}
    />
  );
}
```

#### onEmpty

Fires when the group list fetch returns zero results.

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";

function GroupsWithEmptyHandler() {
  return (
    <CometChatGroups onEmpty={() => console.log("No groups available")} />
  );
}
```

#### onError

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

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function GroupsWithErrorHandler() {
  return (
    <CometChatGroups
      onError={(error: CometChat.CometChatException) => {
        console.error("CometChatGroups error:", error);
      }}
    />
  );
}
```

#### onLoad

Fires when groups are successfully fetched and loaded.

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function GroupsWithLoadHandler() {
  const handleLoad = (list: CometChat.GroupMember[]) => {
    console.log("Groups loaded:", list.length);
  };

  return <CometChatGroups onLoad={handleLoad} />;
}
```

### Global UI Events

`CometChatUIEventHandler` emits events subscribable from anywhere in the application. Subscribe in a `useEffect` and unsubscribe on cleanup.

| Event                       | Fires when                                         | Payload                          |
| --------------------------- | -------------------------------------------------- | -------------------------------- |
| `ccGroupCreated`            | The logged-in user creates a group                 | `CometChat.Group`                |
| `ccGroupDeleted`            | The logged-in user deletes a group                 | `CometChat.Group`                |
| `ccGroupLeft`               | The logged-in user leaves a group                  | `{ leftGroup: CometChat.Group }` |
| `ccGroupMemberScopeChanged` | The logged-in user changes scope of another member | `IGroupMemberScopeChanged`       |
| `ccGroupMemberBanned`       | The logged-in user bans a group member             | `IGroupMemberKickedBanned`       |
| `ccGroupMemberKicked`       | The logged-in user kicks a group member            | `IGroupMemberKickedBanned`       |
| `ccGroupMemberUnbanned`     | The logged-in user unbans a group member           | `IGroupMemberUnBanned`           |
| `ccGroupMemberJoined`       | The logged-in user joins a group                   | `IGroupMemberJoined`             |
| `ccGroupMemberAdded`        | The logged-in user adds members to a group         | `IGroupMemberAdded`              |
| `ccOwnershipChanged`        | The logged-in user transfers group ownership       | `IOwnershipChanged`              |

```tsx lines theme={null}
import { useEffect } from "react";
import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function useGroupEvents() {
  useEffect(() => {
    const listenerId = "GROUP_EVENTS_" + Date.now();
    
    CometChatUIEventHandler.addGroupListener(listenerId, {
      ccGroupCreated: (group: CometChat.Group) => {
        console.log("Group created:", group.getName());
      },
      ccGroupDeleted: (group: CometChat.Group) => {
        console.log("Group deleted:", group.getName());
      },
      ccGroupLeft: ({ leftGroup }: { leftGroup: CometChat.Group }) => {
        console.log("Left group:", leftGroup.getName());
      },
    });

    return () => {
      CometChatUIEventHandler.removeGroupListener(listenerId);
    };
  }, []);
}
```

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual attachment needed unless additional side effects are required.

| SDK Listener                | Internal behavior                            |
| --------------------------- | -------------------------------------------- |
| `onGroupMemberJoined`       | Updates member count when a user joins       |
| `onGroupMemberLeft`         | Updates member count when a user leaves      |
| `onMemberAddedToGroup`      | Updates member count when members are added  |
| `onGroupMemberKicked`       | Updates member count when a member is kicked |
| `onGroupMemberBanned`       | Updates member count when a member is banned |
| `onGroupMemberScopeChanged` | Updates scope when a member's scope changes  |

***

## Custom View Slots

Each slot replaces a section of the default UI. Slots that accept a group parameter receive the `CometChat.Group` object for that row.

| Slot            | Signature                                 | Replaces              |
| --------------- | ----------------------------------------- | --------------------- |
| `ItemView`      | `(group: CometChat.Group) => JSX.Element` | Entire list item row  |
| `LeadingView`   | `(group: CometChat.Group) => JSX.Element` | Avatar / left section |
| `TitleView`     | `(group: CometChat.Group) => JSX.Element` | Name / title text     |
| `SubtitleView`  | `(group: CometChat.Group) => JSX.Element` | Member count subtitle |
| `TrailingView`  | `(group: CometChat.Group) => JSX.Element` | Right section         |
| `LoadingView`   | `() => JSX.Element`                       | Loading spinner       |
| `EmptyView`     | `() => JSX.Element`                       | Empty state           |
| `ErrorView`     | `() => JSX.Element`                       | Error state           |
| `AppBarOptions` | `() => JSX.Element`                       | Header bar options    |

### ItemView

Replace the entire list item row.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import {
  CometChatGroups,
  CometChatAvatar,
  useTheme,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function CustomItemViewGroups() {
  const theme = useTheme();

  const getItemView = (group: CometChat.Group) => {
    return (
      <View
        style={{
          flexDirection: "row",
          flex: 1,
          paddingHorizontal: 16,
          paddingVertical: 12,
          alignItems: "center",
          borderWidth: 1,
          borderColor: theme.color.borderLight,
        }}>
        <CometChatAvatar
          name={group.getName()}
          image={{ uri: group.getIcon() }}
          style={{
            containerStyle: { borderRadius: 8 },
            imageStyle: { borderRadius: 8 },
          }}
        />
        <View style={{ flex: 1, marginLeft: 12 }}>
          <Text
            style={{
              color: theme.color.textPrimary,
              fontSize: 16,
              fontWeight: "500",
            }}
            numberOfLines={1}
            ellipsizeMode="tail">
            {group.getName()}
          </Text>
          <Text style={{ color: theme.color.textSecondary, fontSize: 12 }}>
            {group.getMembersCount()} members
          </Text>
        </View>
      </View>
    );
  };

  return <CometChatGroups ItemView={getItemView} />;
}
```

### SubtitleView

Replace the member count subtitle.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { Text } from "react-native";

function SubtitleViewGroups() {
  const getSubtitleView = (group: CometChat.Group) => {
    return (
      <Text style={{ fontSize: 12, color: "#727272" }}>
        {group.getMembersCount()} members • {group.getType()}
      </Text>
    );
  };

  return <CometChatGroups SubtitleView={getSubtitleView} />;
}
```

### AppBarOptions

Custom view for the header bar options.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
import { TouchableOpacity, Text } from "react-native";

function AppBarOptionsGroups() {
  return (
    <CometChatGroups
      AppBarOptions={() => (
        <TouchableOpacity onPress={() => console.log("Create group")}>
          <Text style={{ color: "#6852D6", fontWeight: "500" }}>+ Create</Text>
        </TouchableOpacity>
      )}
    />
  );
}
```

### options

Custom context menu actions for each group item.

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function OptionsGroups() {
  const getOptions = (group: CometChat.Group) => [
    {
      text: "Leave",
      onPress: () => console.log("Leave:", group.getName()),
    },
    {
      text: "Mute",
      onPress: () => console.log("Mute:", group.getName()),
    },
  ];

  return <CometChatGroups options={getOptions} />;
}
```

***

## Common Patterns

### Custom empty state with CTA

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
import { View, Text, TouchableOpacity } from "react-native";

function EmptyStateGroups() {
  return (
    <CometChatGroups
      EmptyView={() => (
        <View style={{ flex: 1, justifyContent: "center", alignItems: "center", padding: 40 }}>
          <Text style={{ fontSize: 16, marginBottom: 16 }}>No groups found</Text>
          <TouchableOpacity
            style={{ backgroundColor: "#6852D6", paddingHorizontal: 20, paddingVertical: 10, borderRadius: 8 }}
            onPress={() => console.log("Create group")}>
            <Text style={{ color: "white" }}>Create a group</Text>
          </TouchableOpacity>
        </View>
      )}
    />
  );
}
```

### Joined groups only

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function JoinedGroupsOnly() {
  return (
    <CometChatGroups
      groupsRequestBuilder={
        new CometChat.GroupsRequestBuilder().joinedOnly(true).setLimit(15)
      }
    />
  );
}
```

### Multi-select with submit

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function MultiSelectGroups() {
  const handleSubmit = (groups: Array<CometChat.Group>) => {
    console.log("Selected groups:", groups.length);
  };

  return (
    <CometChatGroups
      selectionMode="multiple"
      hideSubmitButton={false}
      onSubmit={handleSubmit}
    />
  );
}
```

### Hide all chrome — minimal list

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";

function MinimalGroups() {
  return (
    <CometChatGroups
      hideSearch={true}
      groupTypeVisibility={false}
      hideHeader={true}
    />
  );
}
```

***

## Styling

The component uses the theme system from `CometChatThemeProvider`. Pass a `style` prop to customize the appearance.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatGroups } from "@cometchat/chat-uikit-react-native";

function StyledGroups() {
  return (
    <CometChatGroups
      style={{
        titleStyle: {
          color: "#FBAA75",
        },
        titleSeparatorStyle: {
          borderBottomColor: "#FBAA75",
        },
        itemStyle: {
          avatarStyle: {
            containerStyle: {
              borderRadius: 8,
              backgroundColor: "#FBAA75",
            },
            imageStyle: {
              borderRadius: 8,
            },
          },
        },
      }}
    />
  );
}
```

### Style Properties

| Property         | Type        | Description                                                                  |
| ---------------- | ----------- | ---------------------------------------------------------------------------- |
| `containerStyle` | `ViewStyle` | Style for the root container                                                 |
| `headerStyle`    | `ViewStyle` | Style for the header section                                                 |
| `titleStyle`     | `TextStyle` | Style for the header title                                                   |
| `itemStyle`      | `object`    | Style for list items (includes `avatarStyle`, `titleStyle`, `subtitleStyle`) |
| `searchStyle`    | `object`    | Style for the search bar                                                     |

***

## Props

All props are optional unless noted.

### EmptyView

Custom component displayed when there are no groups.

|         |                      |
| ------- | -------------------- |
| Type    | `() => JSX.Element`  |
| Default | Built-in empty state |

***

### ErrorView

Custom component displayed when an error occurs.

|         |                      |
| ------- | -------------------- |
| Type    | `() => JSX.Element`  |
| Default | Built-in error state |

***

### groupsRequestBuilder

Controls which groups load and in what order.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `CometChat.GroupsRequestBuilder` |
| Default | SDK default (30 per page)        |

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

***

### groupTypeVisibility

Shows/hides the group type icon (public/private/password).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### hideError

Hides the error state view.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideHeader

Hides the entire header bar.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideLoadingState

Hides the loading state while fetching groups.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideSearch

Hides the search bar.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideSubmitButton

Hides the submit button when selection mode is enabled.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### ItemView

Custom renderer for the entire list item row.

|         |                                           |
| ------- | ----------------------------------------- |
| Type    | `(group: CometChat.Group) => JSX.Element` |
| Default | Built-in list item                        |

***

### LeadingView

Custom renderer for the avatar / left section.

|         |                                           |
| ------- | ----------------------------------------- |
| Type    | `(group: CometChat.Group) => JSX.Element` |
| Default | Built-in avatar                           |

***

### LoadingView

Custom component displayed during the loading state.

|         |                            |
| ------- | -------------------------- |
| Type    | `() => JSX.Element`        |
| Default | Built-in loading indicator |

***

### onBack

Callback fired when the back button is pressed.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onEmpty

Callback fired when the group list is empty.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onError

Callback fired when the component encounters an error.

|         |                                                 |
| ------- | ----------------------------------------------- |
| Type    | `(error: CometChat.CometChatException) => void` |
| Default | `undefined`                                     |

***

### onItemLongPress

Callback fired when a group row is long-pressed.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `(group: CometChat.Group) => void` |
| Default | `undefined`                        |

***

### onItemPress

Callback fired when a group row is tapped.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `(group: CometChat.Group) => void` |
| Default | `undefined`                        |

***

### onLoad

Callback fired when groups are loaded.

|         |                                           |
| ------- | ----------------------------------------- |
| Type    | `(list: CometChat.GroupMember[]) => void` |
| Default | `undefined`                               |

***

### onSelection

Callback fired when groups are selected/deselected. Requires `selectionMode` to be set.

|         |                                          |
| ------- | ---------------------------------------- |
| Type    | `(list: Array<CometChat.Group>) => void` |
| Default | `undefined`                              |

***

### onSubmit

Callback fired when the submit button is pressed. Requires `selectionMode` to be set.

|         |                                          |
| ------- | ---------------------------------------- |
| Type    | `(list: Array<CometChat.Group>) => void` |
| Default | `undefined`                              |

***

### searchKeyword

Pre-fills the search and filters the group list.

|         |          |
| ------- | -------- |
| Type    | `string` |
| Default | `""`     |

***

### searchRequestBuilder

Request builder with search parameters to fetch groups.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `CometChat.GroupsRequestBuilder` |
| Default | `undefined`                      |

***

### selectionMode

Enables single or multi-select mode on list items.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `"single" \| "multiple" \| "none"` |
| Default | `"none"`                           |

***

### showBackButton

Shows the back button in the header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### searchPlaceholderText

Placeholder text for the search input.

|         |            |
| ------- | ---------- |
| Type    | `string`   |
| Default | `"Search"` |

***

### privateGroupIcon

Custom icon for private groups.

|         |                       |
| ------- | --------------------- |
| Type    | `ImageSourcePropType` |
| Default | Built-in icon         |

***

### passwordGroupIcon

Custom icon for password-protected groups.

|         |                       |
| ------- | --------------------- |
| Type    | `ImageSourcePropType` |
| Default | Built-in icon         |

***

### addOptions

Function to append additional menu items to the default context menu.

|         |                                                   |
| ------- | ------------------------------------------------- |
| Type    | `(group: CometChat.Group) => MenuItemInterface[]` |
| Default | `undefined`                                       |

***

### options

Function to replace the default context menu items entirely.

|         |                                                   |
| ------- | ------------------------------------------------- |
| Type    | `(group: CometChat.Group) => MenuItemInterface[]` |
| Default | `undefined`                                       |

***

### SubtitleView

Custom renderer for the member count subtitle.

|         |                                           |
| ------- | ----------------------------------------- |
| Type    | `(group: CometChat.Group) => JSX.Element` |
| Default | Built-in subtitle                         |

***

### TitleView

Custom renderer for the name / title text.

|         |                                           |
| ------- | ----------------------------------------- |
| Type    | `(group: CometChat.Group) => JSX.Element` |
| Default | Built-in title                            |

***

### TrailingView

Custom renderer for the right section.

|         |                                           |
| ------- | ----------------------------------------- |
| Type    | `(group: CometChat.Group) => JSX.Element` |
| Default | Built-in trailing view                    |

***

## Next Steps

<CardGroup>
  <Card title="Group Members" icon="users" href="/ui-kit/react-native/group-members">
    View and manage members of a group
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/react-native/conversations">
    Display and manage the list of recent chats
  </Card>

  <Card title="Message List" icon="message" href="/ui-kit/react-native/message-list">
    Display the full chat interface after selecting a group
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>


# AI Agent Integration
Source: https://www.cometchat.com/docs/ui-kit/react-native/guide-ai-agent

Enable intelligent conversational AI capabilities in your React Native app using CometChat UI Kit v5 with AI Agent integration.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                             |
  | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package        | `@cometchat/chat-uikit-react-native`                                                                                                                              |
  | Key components | `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatAIAssistantChatHistory`                                                   |
  | Required setup | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")`                                                                                           |
  | Purpose        | Enable intelligent conversational AI capabilities with AI Agent integration                                                                                       |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/sample)                                                                                |
  | Related        | [Message List](/docs/ui-kit/react-native/message-list) · [Message Composer](/docs/ui-kit/react-native/message-composer) · [All Guides](/docs/ui-kit/react-native/guide-overview) |
</Accordion>

Enable intelligent conversational AI capabilities in your React Native app using CometChat UIKit v5 with AI Agent integration:

* **AI Assistant Chat History**
* **Chat History Management**
* **Contextual Responses**
* **Agent Detection**
* **Seamless Handoffs**

Transform your chat experience with AI-powered assistance that provides intelligent responses and offers seamless integration with your existing chat infrastructure.

<Note>
  **1:1 and group conversations.** AI Agents work in both one-on-one and group conversations. In a 1:1 chat, the end user talks directly with the agent user. In a group, the agent participates as a member — its messages (including cards) are rendered and attributed like any other member's message.
</Note>

## Overview

Users can interact with AI agents through a dedicated chat interface that:

* Provides intelligent responses based on conversation context.
* Maintains chat history for continuity.
* Seamlessly integrates with your existing user chat system.

The AI Agent chat interface provides a familiar messaging experience enhanced with AI capabilities, accessible through your main chat flow or as a standalone feature.

<Frame>
  <img />
</Frame>

## Prerequisites

* React Native project with **@cometchat/chat-uikit-react-native** and **@cometchat/chat-sdk-react-native** installed.
* Valid CometChat **App ID**, **Region**, and **Auth Key** configured via `CometChatUIKit.init()`.
* User logged in with `CometChatUIKit.login()`.
* AI Agent configured in your CometChat dashboard.

## Components

| Component / Class                 | Role                                       |
| :-------------------------------- | :----------------------------------------- |
| `AIAssistantChatScreen`           | Main screen for AI agent chat.             |
| `CometChatAIAssistantChatHistory` | Displays previous AI conversation history. |
| `CometChatMessageList`            | Shows AI messages with threading support.  |
| `CometChatMessageComposer`        | Input interface for AI conversations.      |
| `CometChatMessageHeader`          | Header with AI agent info and controls.    |

## Integration Steps

### Step 1 - Screen Setup

Create the AI Assistant chat screen with proper navigation and component configuration.

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import React, { useState, useEffect } from 'react';
    import { SafeAreaView, View } from 'react-native';
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
      CometChatThemeProvider,
    } from '@cometchat/chat-uikit-react-native';
    import { CometChat } from '@cometchat/chat-sdk-react-native';

    interface AIAssistantChatScreenProps {
      route: {
        params: {
          user: CometChat.User;
          parentMessage?: CometChat.BaseMessage;
        };
      };
      navigation: any;
    }

    const AIAssistantChatScreen: React.FC<AIAssistantChatScreenProps> = ({
      route,
      navigation,
    }) => {
      const { user, parentMessage } = route.params;
      const [currentUser, setCurrentUser] = useState<CometChat.User>(user);

      useEffect(() => {
        initializeComponents();
      }, []);

      const initializeComponents = () => {
        // Set up AI-specific configurations
        console.log('Initializing AI Assistant Chat for user:', currentUser.getName());
      };

      const handleNewChatClick = () => {
        // Navigate to new AI chat
        navigation.replace('AIAssistantChat', { user: currentUser });
      };

      const handleChatHistoryClick = () => {
        // Navigate to chat history
        navigation.navigate('AIAssistantChatHistory', { user: currentUser });
      };

      return (
        <SafeAreaView style={{ flex: 1 }}>
          <CometChatThemeProvider
            theme={{
              light: {
                messageListStyles: {
                  containerStyle: {
                    backgroundColor: '#F8F9FA',
                  },
                  outgoingMessageBubbleStyles: {
                    containerStyle: {
                      backgroundColor: '#E3F2FD',
                    },
                  },
                },
                messageComposerStyles: {
                  containerStyle: {
                    backgroundColor: '#FFFFFF',
                  },
                },
              },
            }}
          >
            <CometChatMessageHeader
              user={currentUser}
              onNewChatButtonClick={handleNewChatClick}
              onChatHistoryButtonClick={handleChatHistoryClick}
            />
            
            <CometChatMessageList
              user={currentUser}
              parentMessageId={parentMessage?.getId()}
              // AI-specific configurations
              emptyChatGreetingView={<AIGreetingView />}
              streamingSpeed={50}
              aiAssistantSuggestedMessages={[
                'How can I help you today?',
                'What would you like to know?',
                'Ask me anything!',
              ]}
            />
            
            <CometChatMessageComposer
              user={currentUser}
              parentMessageId={parentMessage?.getId()}
            />
          </CometChatThemeProvider>
        </SafeAreaView>
      );
    };

    // Custom AI Greeting Component
    const AIGreetingView = () => (
      <View style={{ 
        flex: 1, 
        justifyContent: 'center', 
        alignItems: 'center',
        padding: 20 
      }}>
        <Text style={{ 
          fontSize: 18, 
          fontWeight: 'bold', 
          marginBottom: 10 
        }}>
          Welcome to AI Assistant
        </Text>
        <Text style={{ 
          fontSize: 14, 
          textAlign: 'center',
          color: '#666' 
        }}>
          I'm here to help! Ask me anything or choose from the suggested prompts below.
        </Text>
      </View>
    );

    export default AIAssistantChatScreen;
    ```
  </Tab>
</Tabs>

### Step 2 - Navigation Setup

Configure React Navigation to handle AI Assistant chat screens.

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    // App.tsx or your main navigation file
    import React from 'react';
    import { NavigationContainer } from '@react-navigation/native';
    import { createNativeStackNavigator } from '@react-navigation/native-stack';
    import AIAssistantChatScreen from './screens/AIAssistantChatScreen';
    import AIAssistantChatHistoryScreen from './screens/AIAssistantChatHistoryScreen';
    import MainChatScreen from './screens/MainChatScreen';

    const Stack = createNativeStackNavigator();

    const App = () => {
      return (
        <NavigationContainer>
          <Stack.Navigator
            initialRouteName="MainChat"
            screenOptions={{
              headerShown: false, // Hide default header since we use CometChatMessageHeader
            }}
          >
            <Stack.Screen 
              name="MainChat" 
              component={MainChatScreen} 
            />
            <Stack.Screen 
              name="AIAssistantChat" 
              component={AIAssistantChatScreen}
              options={{
                title: 'AI Assistant',
              }}
            />
            <Stack.Screen 
              name="AIAssistantChatHistory" 
              component={AIAssistantChatHistoryScreen}
              options={{
                title: 'Chat History',
              }}
            />
          </Stack.Navigator>
        </NavigationContainer>
      );
    };

    export default App;
    ```
  </Tab>
</Tabs>

### Step 3 - Theme Customization

Define custom themes for the message list and composer to differentiate AI agent chats.

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    // AITheme.ts
    import { CometChatTheme } from '@cometchat/chat-uikit-react-native';

    export const aiAssistantTheme: Partial<CometChatTheme> = {
      light: {
        messageComposerStyles: {
          containerStyle: {
            backgroundColor: '#F8F9FA',
            borderTopWidth: 1,
            borderTopColor: '#E0E0E0',
          },
          inputStyle: {
            backgroundColor: '#FFFFFF',
            borderRadius: 8,
            borderWidth: 1,
            borderColor: '#E0E0E0',
            paddingHorizontal: 12,
            paddingVertical: 8,
          },
          sendIconContainerStyle: {
            backgroundColor: '#007AFF',
            borderRadius: 20,
            width: 40,
            height: 40,
            justifyContent: 'center',
            alignItems: 'center',
          },
        },
        messageListStyles: {
          containerStyle: {
            backgroundColor: '#F8F9FA',
          },
          outgoingMessageBubbleStyles: {
            containerStyle: {
              backgroundColor: '#E3F2FD',
              borderRadius: 12,
              padding: 12,
              marginVertical: 4,
            },
            textBubbleStyles: {
              textStyle: {
                color: '#1976D2',
                fontSize: 16,
                lineHeight: 20,
              },
            },
          },
          incomingMessageBubbleStyles: {
            assistantBubbleStyles: {
              containerStyle: {
                backgroundColor: '#FFFFFF',
                borderRadius: 12,
                padding: 12,
                marginVertical: 4,
                borderWidth: 1,
                borderColor: '#E0E0E0',
              },
              textStyle: {
                color: '#333333',
                fontSize: 16,
                lineHeight: 20,
              },
              placeholderTextStyle: {
                color: '#666666',
                fontSize: 16,
                opacity: 0.7,
              },
              copyButtonStyle: {
                backgroundColor: '#007AFF',
                borderRadius: 6,
                paddingHorizontal: 8,
                paddingVertical: 4,
              },
              errorContainerStyle: {
                backgroundColor: '#FFEBEE',
                borderColor: '#F44336',
                borderWidth: 1,
                borderRadius: 8,
                padding: 8,
                marginTop: 4,
              },
              errorTextStyle: {
                color: '#F44336',
                fontSize: 14,
              },
            },
          },
        },
        messageHeaderStyles: {
          containerStyle: {
            backgroundColor: '#FFFFFF',
            borderBottomWidth: 1,
            borderBottomColor: '#E0E0E0',
            paddingHorizontal: 16,
            paddingVertical: 12,
          },
          titleTextStyle: {
            fontSize: 18,
            fontWeight: '600',
            color: '#333333',
          },
          avatarStyle: {
            containerStyle: {
              width: 40,
              height: 40,
              borderRadius: 20,
              backgroundColor: '#007AFF',
            },
          },
        },
      },
    };
    ```
  </Tab>
</Tabs>

### Step 4 - AI Assistant Tools Configuration

Configure AI Assistant tools and suggested messages for an enhanced user experience.

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    // AIAssistantConfig.ts
    import { CometChat } from '@cometchat/chat-sdk-react-native';

    export const aiTools = new CometChatAIAssistantTools({
      getCurrentWeather: (args: any) => {
        console.log('Weather tool called with:', args);
        // Handle weather tool action
      },
      getLocationInfo: (args: any) => {
        console.log('Location tool called with:', args);
        // Handle location tool action
      },
      sendEmail: (args: any) => {
        console.log('Email tool called with:', args);
        // Handle email tool action
      }
    });

    export const suggestedMessages = [
      'How can I help you today?',
      'What would you like to know?',
      'Tell me about your project',
      'Need help with something specific?',
      'Ask me anything!',
    ];

    // Enhanced AI Assistant Chat Screen with tools
    export const EnhancedAIAssistantChatScreen: React.FC<AIAssistantChatScreenProps> = ({
      route,
      navigation,
    }) => {
      const { user, parentMessage } = route.params;

      return (
        <SafeAreaView style={{ flex: 1 }}>
          <CometChatThemeProvider theme={aiAssistantTheme}>
            <CometChatMessageHeader
              user={user}
              onNewChatButtonClick={() => {
                navigation.replace('AIAssistantChat', { user });
              }}
              onChatHistoryButtonClick={() => {
                navigation.navigate('AIAssistantChatHistory', { user });
              }}
            />
            
            <CometChatMessageList
              user={user}
              parentMessageId={parentMessage?.getId()}
              emptyChatGreetingView={<AIGreetingView />}
              streamingSpeed={50}
              aiAssistantSuggestedMessages={suggestedMessages}
              aiAssistantTools={aiTools}
            />
            
            <CometChatMessageComposer
              user={user}
              parentMessageId={parentMessage?.getId()}
            />
          </CometChatThemeProvider>
        </SafeAreaView>
      );
    };
    ```
  </Tab>
</Tabs>

### Step 5 - Create AI Assistant Chat History Screen

Create a screen to host the `CometChatAIAssistantChatHistory` component and handle its interactions.

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    // AIAssistantChatHistoryScreen.tsx
    import React, { useState, useEffect } from 'react';
    import { SafeAreaView, Alert } from 'react-native';
    import {
      CometChatAIAssistantChatHistory,
      CometChatThemeProvider,
    } from '@cometchat/chat-uikit-react-native';
    import { CometChat } from '@cometchat/chat-sdk-react-native';

    interface AIAssistantChatHistoryScreenProps {
      route: {
        params: {
          user: CometChat.User;
        };
      };
      navigation: any;
    }

    const AIAssistantChatHistoryScreen: React.FC<AIAssistantChatHistoryScreenProps> = ({
      route,
      navigation,
    }) => {
      const { user } = route.params;
      const [currentUser, setCurrentUser] = useState<CometChat.User>(user);

      useEffect(() => {
        console.log('Loading AI Assistant Chat History for:', currentUser.getName());
      }, [currentUser]);

      const handleItemClick = (message: CometChat.BaseMessage) => {
        const receiver = message.getReceiver();
        if (receiver instanceof CometChat.User) {
          // Navigate to specific chat thread
          navigation.navigate('AIAssistantChat', {
            user: receiver,
            parentMessage: message,
          });
        }
      };

      const handleNewChatClick = () => {
        // Navigate to new AI chat
        navigation.navigate('AIAssistantChat', { user: currentUser });
      };

      const handleCloseClick = () => {
        // Navigate back or close
        navigation.goBack();
      };

      return (
        <SafeAreaView style={{ flex: 1 }}>
          <CometChatThemeProvider
            theme={{
              light: {
                chatHistoryStyles: {
                  containerStyle: {
                    backgroundColor: '#F8F9FA',
                  },
                  headerStyle: {
                    backgroundColor: '#FFFFFF',
                    borderBottomWidth: 1,
                    borderBottomColor: '#E0E0E0',
                  },
                  headerTitleStyle: {
                    fontSize: 18,
                    fontWeight: '600',
                    color: '#333333',
                  },
                  messageItemStyle: {
                    backgroundColor: '#FFFFFF',
                    marginVertical: 4,
                    marginHorizontal: 16,
                    borderRadius: 8,
                    padding: 12,
                    borderWidth: 1,
                    borderColor: '#E0E0E0',
                  },
                  messageTextStyle: {
                    fontSize: 14,
                    color: '#333333',
                    lineHeight: 18,
                  },
                  newChatButtonStyle: {
                    backgroundColor: '#007AFF',
                    borderRadius: 8,
                    padding: 12,
                    margin: 16,
                  },
                  newChatTextStyle: {
                    color: '#FFFFFF',
                    fontSize: 16,
                    fontWeight: '600',
                    textAlign: 'center',
                  },
                },
              },
            }}
          >
            <CometChatAIAssistantChatHistory
              user={currentUser}
              onItemClick={handleItemClick}
              onNewChatButtonClick={handleNewChatClick}
              onCloseButtonClick={handleCloseClick}
            />
          </CometChatThemeProvider>
        </SafeAreaView>
      );
    };

    export default AIAssistantChatHistoryScreen;
    ```
  </Tab>
</Tabs>

### Step 6 - Launching AI Chat

Create navigation functions to launch AI Assistant chat from your main application.

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    // MainChatScreen.tsx or your main component
    import React from 'react';
    import { View, TouchableOpacity, Text } from 'react-native';
    import { CometChat } from '@cometchat/chat-sdk-react-native';

    interface MainChatScreenProps {
      navigation: any;
    }

    const MainChatScreen: React.FC<MainChatScreenProps> = ({ navigation }) => {
      const launchAIAssistantChat = async (aiUser: CometChat.User, parentMessage?: CometChat.BaseMessage) => {
        try {
          // Verify the user has @agentic role for AI agent
          if (aiUser.getRole() === '@agentic') {
            navigation.navigate('AIAssistantChat', {
              user: aiUser,
              parentMessage: parentMessage,
            });
          } else {
            console.warn('User is not an AI agent');
          }
        } catch (error) {
          console.error('Error launching AI chat:', error);
        }
      };

      const createAIUser = () => {
        // Create or fetch AI user with @agentic role
        const aiUser = new CometChat.User('ai-assistant-001');
        aiUser.setName('AI Assistant');
        aiUser.setRole('@agentic'); // Important: Set role to @agentic for AI agents
        return aiUser;
      };

      return (
        <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
          <TouchableOpacity
            style={{
              backgroundColor: '#007AFF',
              paddingHorizontal: 20,
              paddingVertical: 12,
              borderRadius: 8,
              marginBottom: 16,
            }}
            onPress={() => {
              const aiUser = createAIUser();
              launchAIAssistantChat(aiUser);
            }}
          >
            <Text style={{ color: '#FFFFFF', fontSize: 16, fontWeight: '600' }}>
              Start AI Chat
            </Text>
          </TouchableOpacity>

          <TouchableOpacity
            style={{
              backgroundColor: '#34C759',
              paddingHorizontal: 20,
              paddingVertical: 12,
              borderRadius: 8,
            }}
            onPress={() => {
              const aiUser = createAIUser();
              navigation.navigate('AIAssistantChatHistory', { user: aiUser });
            }}
          >
            <Text style={{ color: '#FFFFFF', fontSize: 16, fontWeight: '600' }}>
              View Chat History
            </Text>
          </TouchableOpacity>
        </View>
      );
    };

    export default MainChatScreen;
    ```
  </Tab>
</Tabs>

## Implementation Flow Summary

| Step | Action                                                                     |
| :--- | :------------------------------------------------------------------------- |
| 1    | User selects AI agent from chat list                                       |
| 2    | `AIAssistantChatScreen` navigates and renders                              |
| 3    | Parse route params and detect agent chat (Role of user must be "@agentic") |
| 4    | Initialize UI with AI-specific theming                                     |
| 5    | Configure chat history and navigation handlers                             |
| 6    | Launch chat with AI agent                                                  |

## Customization Options

* **Custom AI Assistant Empty Chat View:** Customize the empty state view using `emptyChatGreetingView` prop.
* **Streaming Speed:** Adjust AI response streaming speed via `streamingSpeed` prop.
* **AI Assistant Suggested Messages:** Create custom list of suggested messages using `aiAssistantSuggestedMessages` prop.
* **AI Assistant Tools:** Set tools for the AI agent using `aiAssistantTools` prop.

## Feature Matrix

| Feature           | Implementation                    | UI Component        |
| :---------------- | :-------------------------------- | :------------------ |
| AI Chat Interface | `AIAssistantChatScreen`           | Full chat screen    |
| Chat History      | `CometChatAIAssistantChatHistory` | Chat history screen |

<CardGroup>
  <Card title="React Native AI Sample">
    Explore this feature in the CometChat React Native Sample:
    [GitHub → React Native Sample](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/sample)
  </Card>

  <Card title="React Native UI Kit">
    Learn more about React Native UI Kit components:
    [GitHub → React Native UIKit](https://github.com/cometchat/cometchat-uikit-react-native)
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="messages" href="/ui-kit/react-native/message-list">
    Display and manage messages in a conversation
  </Card>

  <Card title="Message Composer" icon="keyboard" href="/ui-kit/react-native/message-composer">
    Compose and send messages with rich input options
  </Card>

  <Card title="All Guides" icon="book" href="/ui-kit/react-native/guide-overview">
    Browse all feature and formatter guides
  </Card>

  <Card title="Components Overview" icon="grid" href="/ui-kit/react-native/components-overview">
    Explore all available components
  </Card>
</CardGroup>


# Block/Unblock Users
Source: https://www.cometchat.com/docs/ui-kit/react-native/guide-block-unblock-user

Implement block and unblock user functionality in CometChat React Native UI Kit with composer state management.

<Accordion title="AI Integration Quick Reference">
  | Field       | Value                                                                                                                                               |
  | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package     | `@cometchat/chat-uikit-react-native`                                                                                                                |
  | Key methods | `CometChat.blockUsers()`, `CometChat.unblockUsers()`                                                                                                |
  | Init        | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")`                                                                             |
  | Events      | `CometChatUIEvents.ccUserBlocked`, `CometChatUIEvents.ccUserUnBlocked`                                                                              |
  | Sample app  | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp)                                                      |
  | Related     | [Users](/docs/ui-kit/react-native/users) · [Message Composer](/docs/ui-kit/react-native/message-composer) · [All Guides](/docs/ui-kit/react-native/guide-overview) |
</Accordion>

Block/Unblock lets users prevent specific users from sending them messages. When blocked, the message composer is hidden and replaced with an unblock prompt.

Before starting, complete the [Getting Started](/docs/ui-kit/react-native/react-native-cli-integration) guide.

***

## Components

| Component / Class                   | Role                                           |
| :---------------------------------- | :--------------------------------------------- |
| `CometChat.blockUsers()`            | SDK method to block specific users             |
| `CometChat.unblockUsers()`          | SDK method to unblock previously blocked users |
| `CometChatUIEvents.ccUserBlocked`   | Event fired when a user is blocked             |
| `CometChatUIEvents.ccUserUnBlocked` | Event fired when a user is unblocked           |
| `CometChatConfirmDialog`            | Confirmation dialog for block/unblock actions  |

***

## Integration Steps

### 1. Block User

Call `CometChat.blockUsers()` with the target UID. On success, emit `ccUserBlocked` so all subscribed components react to the change.

```tsx theme={null}
import { CometChat } from '@cometchat/chat-sdk-react-native';
import {
  CometChatUIEventHandler,
  CometChatUIEvents,
} from '@cometchat/chat-uikit-react-native';

const blockUser = async (user: CometChat.User) => {
  try {
    const uid = user.getUid();
    await CometChat.blockUsers([uid]);
    
    // Fetch fresh user data
    const freshUser = await CometChat.getUser(uid);
    
    // Emit event so UI components update
    CometChatUIEventHandler.emitUserEvent(
      CometChatUIEvents.ccUserBlocked,
      { user: freshUser }
    );
    
    console.log('User blocked successfully');
  } catch (error) {
    console.error('Blocking user failed:', error);
  }
};
```

***

### 2. Unblock User

Call `CometChat.unblockUsers()` with the target UID. On success, emit `ccUserUnBlocked` to restore the composer.

```tsx theme={null}
import { CometChat } from '@cometchat/chat-sdk-react-native';
import {
  CometChatUIEventHandler,
  CometChatUIEvents,
} from '@cometchat/chat-uikit-react-native';

const unblockUser = async (user: CometChat.User) => {
  try {
    const uid = user.getUid();
    await CometChat.unblockUsers([uid]);
    
    // Fetch fresh user data
    const freshUser = await CometChat.getUser(uid);
    
    // Emit event so UI components update
    CometChatUIEventHandler.emitUserEvent(
      CometChatUIEvents.ccUserUnBlocked,
      { user: freshUser }
    );
    
    console.log('User unblocked successfully');
  } catch (error) {
    console.error('Unblocking user failed:', error);
  }
};
```

***

### 3. Composer Blocked State

When a user is blocked, replace the composer with an unblock prompt.

```tsx theme={null}
import React, { useState, useEffect } from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';
import {
  CometChatMessageComposer,
  CometChatUIEventHandler,
  CometChatUIEvents,
  useTheme,
  useCometChatTranslation,
} from '@cometchat/chat-uikit-react-native';

interface MessageComposerWithBlockProps {
  user: CometChat.User;
}

const MessageComposerWithBlock: React.FC<MessageComposerWithBlockProps> = ({ user }) => {
  const theme = useTheme();
  const { t } = useCometChatTranslation();
  const [localUser, setLocalUser] = useState(user);

  // Listen for block/unblock events
  useEffect(() => {
    const listenerId = 'composer_block_listener_' + Date.now();
    
    CometChatUIEventHandler.addUserListener(listenerId, {
      ccUserBlocked: (payload: { user: CometChat.User }) => {
        if (payload.user.getUid() === localUser.getUid()) {
          setLocalUser(payload.user);
        }
      },
      ccUserUnBlocked: (payload: { user: CometChat.User }) => {
        if (payload.user.getUid() === localUser.getUid()) {
          setLocalUser(payload.user);
        }
      },
    });

    return () => {
      CometChatUIEventHandler.removeUserListener(listenerId);
    };
  }, [localUser]);

  const handleUnblock = async () => {
    try {
      await CometChat.unblockUsers([localUser.getUid()]);
      const freshUser = await CometChat.getUser(localUser.getUid());
      setLocalUser(freshUser);
      
      CometChatUIEventHandler.emitUserEvent(
        CometChatUIEvents.ccUserUnBlocked,
        { user: freshUser }
      );
    } catch (error) {
      console.error('Error unblocking user:', error);
    }
  };

  if (localUser.getBlockedByMe()) {
    return (
      <View style={{
        alignItems: 'center',
        padding: 20,
        backgroundColor: theme.color.background3,
      }}>
        <Text style={{
          color: theme.color.textSecondary,
          textAlign: 'center',
          marginBottom: 10,
        }}>
          {t('BLOCKED_USER_DESC')}
        </Text>
        <TouchableOpacity
          onPress={handleUnblock}
          style={{
            borderWidth: 1,
            borderColor: theme.color.borderDefault,
            borderRadius: 8,
            paddingHorizontal: 20,
            paddingVertical: 10,
          }}
        >
          <Text style={{ color: theme.color.textPrimary }}>
            {t('UNBLOCK')}
          </Text>
        </TouchableOpacity>
      </View>
    );
  }

  return <CometChatMessageComposer user={localUser} />;
};
```

***

### 4. Block Option in User Info

Add a block/unblock option in the user info or details screen.

```tsx theme={null}
import React, { useState } from 'react';
import { View, TouchableOpacity, Text, Alert } from 'react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';
import {
  CometChatUIEventHandler,
  CometChatUIEvents,
  useTheme,
  useCometChatTranslation,
} from '@cometchat/chat-uikit-react-native';

interface UserInfoActionsProps {
  user: CometChat.User;
}

const UserInfoActions: React.FC<UserInfoActionsProps> = ({ user }) => {
  const theme = useTheme();
  const { t } = useCometChatTranslation();
  const [localUser, setLocalUser] = useState(user);

  const handleBlockToggle = () => {
    if (localUser.getBlockedByMe()) {
      // Unblock directly
      unblockUser();
    } else {
      // Show confirmation before blocking
      Alert.alert(
        t('BLOCK_USER'),
        t('BLOCK_USER_CONFIRMATION'),
        [
          { text: t('CANCEL'), style: 'cancel' },
          { text: t('BLOCK'), style: 'destructive', onPress: blockUser },
        ]
      );
    }
  };

  const blockUser = async () => {
    try {
      await CometChat.blockUsers([localUser.getUid()]);
      const freshUser = await CometChat.getUser(localUser.getUid());
      setLocalUser(freshUser);
      
      CometChatUIEventHandler.emitUserEvent(
        CometChatUIEvents.ccUserBlocked,
        { user: freshUser }
      );
    } catch (error) {
      console.error('Error blocking user:', error);
    }
  };

  const unblockUser = async () => {
    try {
      await CometChat.unblockUsers([localUser.getUid()]);
      const freshUser = await CometChat.getUser(localUser.getUid());
      setLocalUser(freshUser);
      
      CometChatUIEventHandler.emitUserEvent(
        CometChatUIEvents.ccUserUnBlocked,
        { user: freshUser }
      );
    } catch (error) {
      console.error('Error unblocking user:', error);
    }
  };

  return (
    <TouchableOpacity
      onPress={handleBlockToggle}
      style={{
        padding: 15,
        borderBottomWidth: 1,
        borderBottomColor: theme.color.borderLight,
      }}
    >
      <Text style={{
        color: localUser.getBlockedByMe() ? theme.color.textPrimary : theme.color.error,
      }}>
        {localUser.getBlockedByMe() ? t('UNBLOCK_USER') : t('BLOCK_USER')}
      </Text>
    </TouchableOpacity>
  );
};
```

***

## Feature Matrix

| Feature              | Component / Method                          |
| :------------------- | :------------------------------------------ |
| Block user           | `CometChat.blockUsers([UID])`               |
| Unblock user         | `CometChat.unblockUsers([UID])`             |
| Check blocked status | `user.getBlockedByMe()`                     |
| Block event          | `CometChatUIEvents.ccUserBlocked`           |
| Unblock event        | `CometChatUIEvents.ccUserUnBlocked`         |
| Event listener       | `CometChatUIEventHandler.addUserListener()` |

***

## Next Steps

<CardGroup>
  <Card title="Users" href="/ui-kit/react-native/users">
    Display and manage user lists.
  </Card>

  <Card title="Message Composer" href="/ui-kit/react-native/message-composer">
    Customize the message input component.
  </Card>

  <Card title="All Guides" href="/ui-kit/react-native/guide-overview">
    Browse all feature and formatter guides.
  </Card>

  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp">
    Full working sample application on GitHub.
  </Card>
</CardGroup>


# Group Chat
Source: https://www.cometchat.com/docs/ui-kit/react-native/guide-group-chat

Implement group management including create, join, members, roles, and ownership transfer in CometChat React Native UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                           |
  | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package        | `@cometchat/chat-uikit-react-native`                                                                                                            |
  | Key components | `CometChatGroups`, `CometChatGroupMembers`, `CometChatUsers`, `CometChatConfirmDialog`                                                          |
  | Init           | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")`                                                                         |
  | Features       | Create public/private/password-protected groups, manage members, roles, ownership transfer                                                      |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp)                                                  |
  | Related        | [Groups](/docs/ui-kit/react-native/groups) · [Group Members](/docs/ui-kit/react-native/group-members) · [All Guides](/docs/ui-kit/react-native/guide-overview) |
</Accordion>

This guide covers the full group lifecycle: creating groups, joining them, managing members, changing roles, and transferring ownership.

Before starting, complete the [Getting Started](/docs/ui-kit/react-native/react-native-cli-integration) guide.

***

## Components

| Component / Class        | Role                                             |
| :----------------------- | :----------------------------------------------- |
| `CometChatGroups`        | Displays list of groups with join/create options |
| `CometChatGroupMembers`  | Displays and manages group member lists          |
| `CometChatUsers`         | User selection for adding members                |
| `CometChatConfirmDialog` | Confirmation dialogs for destructive actions     |
| `CometChatGroupsEvents`  | Events for group-related actions                 |

***

## Integration Steps

### 1. Display Groups List

Render `CometChatGroups` with custom app bar options for creating new groups. Handle item press to either open chat (if joined) or trigger join flow.

```tsx theme={null}
import React, { useState } from 'react';
import { View, TouchableOpacity } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import {
  CometChatGroups,
  CometChatUIEventHandler,
  CometChatUIEvents,
  CometChatUIKit,
} from '@cometchat/chat-uikit-react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';

const GroupsScreen = () => {
  const navigation = useNavigation();
  const [isCreateGroupVisible, setCreateGroupVisible] = useState(false);

  const handleGroupItemPress = (group: CometChat.Group) => {
    if (group.getHasJoined()) {
      // Navigate to messages
      navigation.navigate('Messages', { group });
      return;
    }

    if (group.getType() === CometChat.GROUP_TYPE.PUBLIC) {
      joinPublicGroup(group);
    } else if (group.getType() === CometChat.GROUP_TYPE.PASSWORD) {
      // Show password input modal
      setGroupToJoin(group);
      setJoinGroupVisible(true);
    }
  };

  const joinPublicGroup = async (group: CometChat.Group) => {
    try {
      const joinedGroup = await CometChat.joinGroup(
        group.getGuid(),
        group.getType() as CometChat.GroupType,
        ''
      );
      
      navigation.navigate('Messages', { group: joinedGroup });
      
      CometChatUIEventHandler.emitGroupEvent(
        CometChatUIEvents.ccGroupMemberJoined,
        {
          joinedUser: CometChatUIKit.loggedInUser,
          joinedGroup: joinedGroup,
        }
      );
    } catch (error) {
      console.log('Error joining public group:', error);
    }
  };

  return (
    <View style={{ flex: 1 }}>
      <CometChatGroups
        onItemPress={handleGroupItemPress}
        AppBarOptions={() => (
          <TouchableOpacity onPress={() => setCreateGroupVisible(true)}>
            {/* Add icon */}
          </TouchableOpacity>
        )}
      />
    </View>
  );
};
```

***

### 2. Create Group

Build a form that collects group name, type, and optional password. Call `CometChat.createGroup()` and emit `ccGroupCreated`.

```tsx theme={null}
import React, { useState } from 'react';
import { View, TextInput, TouchableOpacity, Text } from 'react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';
import {
  CometChatUIEventHandler,
  CometChatGroupsEvents,
} from '@cometchat/chat-uikit-react-native';

interface CreateGroupProps {
  onGroupCreated: (group: CometChat.Group) => void;
  onClose: () => void;
}

const CreateGroupForm: React.FC<CreateGroupProps> = ({ onGroupCreated, onClose }) => {
  const [groupName, setGroupName] = useState('');
  const [groupType, setGroupType] = useState<string>(CometChat.GROUP_TYPE.PUBLIC);
  const [password, setPassword] = useState('');

  const handleCreateGroup = async () => {
    const GUID = `group_${new Date().getTime()}`;
    const group = new CometChat.Group(GUID, groupName, groupType, password);

    try {
      const createdGroup = await CometChat.createGroup(group);
      
      CometChatUIEventHandler.emitGroupEvent(
        CometChatGroupsEvents.ccGroupCreated,
        { group: createdGroup }
      );
      
      onGroupCreated(createdGroup);
      onClose();
    } catch (error) {
      console.error('Group creation failed:', error);
    }
  };

  return (
    <View style={{ padding: 20 }}>
      <TextInput
        placeholder="Group Name"
        value={groupName}
        onChangeText={setGroupName}
      />
      
      {/* Group type selector */}
      <View style={{ flexDirection: 'row', marginVertical: 10 }}>
        <TouchableOpacity onPress={() => setGroupType(CometChat.GROUP_TYPE.PUBLIC)}>
          <Text>Public</Text>
        </TouchableOpacity>
        <TouchableOpacity onPress={() => setGroupType(CometChat.GROUP_TYPE.PRIVATE)}>
          <Text>Private</Text>
        </TouchableOpacity>
        <TouchableOpacity onPress={() => setGroupType(CometChat.GROUP_TYPE.PASSWORD)}>
          <Text>Password</Text>
        </TouchableOpacity>
      </View>
      
      {groupType === CometChat.GROUP_TYPE.PASSWORD && (
        <TextInput
          placeholder="Password"
          secureTextEntry
          value={password}
          onChangeText={setPassword}
        />
      )}
      
      <TouchableOpacity onPress={handleCreateGroup}>
        <Text>Create Group</Text>
      </TouchableOpacity>
    </View>
  );
};
```

***

### 3. Add Members to Group

Use `CometChatUsers` with `selectionMode="multiple"` to select users, then call `CometChat.addMembersToGroup()`.

```tsx theme={null}
import React, { useState, useCallback } from 'react';
import { View, TouchableOpacity, Text } from 'react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';
import {
  CometChatUsers,
  CometChatUIEventHandler,
  CometChatGroupsEvents,
  CometChatUIKit,
  CometChatUiKitConstants,
} from '@cometchat/chat-uikit-react-native';

interface AddMemberProps {
  group: CometChat.Group;
  onBack: () => void;
}

const AddMemberScreen: React.FC<AddMemberProps> = ({ group, onBack }) => {
  const [selectedUsers, setSelectedUsers] = useState<CometChat.User[]>([]);

  const addMembersToGroup = useCallback(async () => {
    try {
      const membersList = selectedUsers.map((user) => {
        const groupMember = new CometChat.GroupMember(
          user.getUid(),
          CometChat.GROUP_MEMBER_SCOPE.PARTICIPANT
        );
        groupMember.setName(user.getName());
        return groupMember;
      });

      const guid = group.getGuid();
      const response = await CometChat.addMembersToGroup(guid, membersList, []);

      const addedUIDs = Object.entries(response)
        .filter(([_, status]) => status === 'success')
        .map(([uid]) => uid);

      if (addedUIDs.length > 0) {
        // Emit event for each added member
        membersList
          .filter((member) => addedUIDs.includes(member.getUid()))
          .forEach((member) => {
            CometChatUIEventHandler.emitGroupEvent(
              CometChatGroupsEvents.ccGroupMemberAdded,
              {
                addedBy: CometChatUIKit.loggedInUser,
                usersAdded: [member],
                userAddedIn: group,
              }
            );
          });
        
        onBack();
      }
    } catch (error) {
      console.error('Failed to add members:', error);
    }
  }, [group, selectedUsers, onBack]);

  return (
    <View style={{ flex: 1 }}>
      <CometChatUsers
        hideHeader={true}
        selectionMode="multiple"
        onSelection={setSelectedUsers}
      />
      
      <TouchableOpacity onPress={addMembersToGroup}>
        <Text>Add Members</Text>
      </TouchableOpacity>
    </View>
  );
};
```

***

### 4. View and Manage Group Members

Use `CometChatGroupMembers` to display members with options for scope changes and removal.

```tsx theme={null}
import React from 'react';
import { View } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import { CometChatGroupMembers } from '@cometchat/chat-uikit-react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';

interface ViewMembersProps {
  group: CometChat.Group;
}

const ViewMembersScreen: React.FC<ViewMembersProps> = ({ group }) => {
  const navigation = useNavigation();

  const handleMemberPress = (member: CometChat.GroupMember) => {
    // Navigate to member profile or show options
    console.log('Member pressed:', member.getName());
  };

  return (
    <View style={{ flex: 1 }}>
      <CometChatGroupMembers
        group={group}
        onItemPress={handleMemberPress}
        onBack={() => navigation.goBack()}
      />
    </View>
  );
};
```

***

### 5. Transfer Ownership

Let the current owner select a member and transfer ownership via `CometChat.transferGroupOwnership()`.

```tsx theme={null}
import React, { useState } from 'react';
import { View, TouchableOpacity, Text } from 'react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';
import {
  CometChatGroupMembers,
  CometChatUIEventHandler,
  CometChatGroupsEvents,
} from '@cometchat/chat-uikit-react-native';

interface TransferOwnershipProps {
  group: CometChat.Group;
  onClose: () => void;
}

const TransferOwnershipScreen: React.FC<TransferOwnershipProps> = ({ group, onClose }) => {
  const [selectedMember, setSelectedMember] = useState<CometChat.GroupMember | null>(null);

  const transferOwnership = async () => {
    if (!selectedMember) return;

    try {
      await CometChat.transferGroupOwnership(group.getGuid(), selectedMember.getUid());
      
      CometChatUIEventHandler.emitGroupEvent(
        CometChatGroupsEvents.ccOwnershipChanged,
        {
          group: group,
          newOwner: selectedMember,
        }
      );
      
      onClose();
    } catch (error) {
      console.error('Ownership transfer failed:', error);
    }
  };

  return (
    <View style={{ flex: 1 }}>
      <CometChatGroupMembers
        group={group}
        selectionMode="single"
        onSelection={(members) => setSelectedMember(members[0] || null)}
      />
      
      <TouchableOpacity onPress={transferOwnership} disabled={!selectedMember}>
        <Text>Transfer Ownership</Text>
      </TouchableOpacity>
    </View>
  );
};
```

***

## Feature Matrix

| Feature            | Component / Method                   |
| :----------------- | :----------------------------------- |
| Display groups     | `CometChatGroups`                    |
| Create group       | `CometChat.createGroup()`            |
| Join group         | `CometChat.joinGroup()`              |
| View members       | `CometChatGroupMembers`              |
| Add members        | `CometChat.addMembersToGroup()`      |
| Remove member      | `CometChat.kickGroupMember()`        |
| Ban member         | `CometChat.banGroupMember()`         |
| Change scope       | `CometChat.updateGroupMemberScope()` |
| Transfer ownership | `CometChat.transferGroupOwnership()` |
| Group events       | `CometChatGroupsEvents`              |

***

## Next Steps

<CardGroup>
  <Card title="Groups" href="/ui-kit/react-native/groups">
    Display and manage group lists.
  </Card>

  <Card title="Group Members" href="/ui-kit/react-native/group-members">
    Display and manage group member lists.
  </Card>

  <Card title="All Guides" href="/ui-kit/react-native/guide-overview">
    Browse all feature and formatter guides.
  </Card>

  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp">
    Full working sample application on GitHub.
  </Card>
</CardGroup>


# Message Privately
Source: https://www.cometchat.com/docs/ui-kit/react-native/guide-message-privately

Start private one-to-one chats from CometChat React Native UI Kit group conversations using the built-in message option and openChat event.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                 |
  | -------------- | ----------------------------------------------------------------------------------------------------- |
  | Package        | `@cometchat/chat-uikit-react-native`                                                                  |
  | Key components | `CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageHeader`                          |
  | Trigger        | Long-press another member's message in a group chat → "Message Privately"                             |
  | Event          | `openChat` via `CometChatUIEventHandler.addUIListener`                                                |
  | Prop           | `hideMessagePrivatelyOption` on `CometChatMessageList`                                                |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp)        |
  | Related        | [Message List](/docs/ui-kit/react-native/message-list) · [All Guides](/docs/ui-kit/react-native/guide-overview) |
</Accordion>

Message Privately lets users start a direct 1:1 conversation with a group member from within a group chat. The user long-presses a message, selects "Message Privately", and the UIKit opens a private conversation with the message sender.

Before starting, complete the [Getting Started](/docs/ui-kit/react-native/react-native-cli-integration) guide.

***

## How It Works

The feature is built into `CometChatMessageList`. When a user selects "Message Privately" from the message long-press menu:

1. The UIKit fetches the message sender via `CometChat.getUser()`
2. It emits an `openChat` UI event with `{ user }` via `CometChatUIEventHandler`
3. Your app listens with `addUIListener` and navigates to a private chat screen

***

## Components

| Component / Class          | Role                                                         |
| :------------------------- | :----------------------------------------------------------- |
| `CometChatMessageList`     | Group chat — shows the "Message Privately" long-press option |
| `CometChatMessageHeader`   | Header for the private 1:1 chat screen                       |
| `CometChatMessageList`     | Message list for the private 1:1 chat screen                 |
| `CometChatMessageComposer` | Composer for the private 1:1 chat screen                     |

***

## Integration Steps

### 1. Group Chat Screen

Render the full group chat and register an `openChat` listener. The "Message Privately" option appears automatically in the long-press menu for messages sent by *other* members of a group conversation — no extra setup needed. When selected, the UIKit fetches the sender and fires `openChat`, which your listener catches to navigate to the private chat.

```tsx theme={null}
import React, { useEffect } from 'react';
import { View, StyleSheet } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import {
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatUIEventHandler,
} from '@cometchat/chat-uikit-react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';

const LISTENER_ID = 'group_chat_private_listener';

export default function GroupChatScreen({ group }: { group: CometChat.Group }) {
  const navigation = useNavigation<any>();

  useEffect(() => {
    CometChatUIEventHandler.addUIListener(LISTENER_ID, {
      openChat: ({ user }: { user: CometChat.User }) => {
        navigation.navigate('PrivateChat', { user, fromGroup: group });
      },
    });

    return () => {
      CometChatUIEventHandler.removeUIListener(LISTENER_ID);
    };
  }, [navigation, group]);

  return (
    <View style={styles.container}>
      <CometChatMessageHeader group={group} />
      <CometChatMessageList group={group} />
      <CometChatMessageComposer group={group} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
});
```

***

### 2. Private Chat Screen

Create a dedicated screen for the private conversation. Include a back button in the header so the user can return to the group.

```tsx theme={null}
import React from 'react';
import { View, StyleSheet } from 'react-native';
import { useRoute, useNavigation } from '@react-navigation/native';
import {
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from '@cometchat/chat-uikit-react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';

type RouteParams = {
  user: CometChat.User;
  fromGroup?: CometChat.Group;
};

export default function PrivateChatScreen() {
  const navigation = useNavigation();
  const { user, fromGroup } = useRoute<any>().params as RouteParams;

  return (
    <View style={styles.container}>
      <CometChatMessageHeader
        user={user}
        showBackButton={true}
        onBack={() => {
          if (fromGroup) {
            navigation.navigate('GroupChat', { group: fromGroup });
          } else {
            navigation.goBack();
          }
        }}
      />
      <CometChatMessageList user={user} />
      <CometChatMessageComposer user={user} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
});
```

***

### 3. Navigation Setup

Register both screens in your navigator.

```tsx theme={null}
import { createStackNavigator } from '@react-navigation/stack';
import GroupChatScreen from './GroupChatScreen';
import PrivateChatScreen from './PrivateChatScreen';

const Stack = createStackNavigator();

export default function AppNavigator() {
  return (
    <Stack.Navigator screenOptions={{ headerShown: false }}>
      <Stack.Screen name="GroupChat" component={GroupChatScreen} />
      <Stack.Screen name="PrivateChat" component={PrivateChatScreen} />
    </Stack.Navigator>
  );
}
```

***

## Hiding the Option

The option is already absent in 1:1 conversations, on your own messages, and in AI agent chats — you don't need to hide it in those cases.

Use `hideMessagePrivatelyOption` when you want to suppress it in a group screen that would otherwise show it — for example a broadcast or announcement group where members shouldn't DM each other, or a moderated support group where private contact is off-policy.

```tsx theme={null}
<CometChatMessageList
  group={group}
  hideMessagePrivatelyOption={true}
/>
```

***

## Feature Matrix

| Feature          | How                                                                               |
| :--------------- | :-------------------------------------------------------------------------------- |
| Trigger          | Long-press another member's message in a group → "Message Privately"              |
| Event emitted    | `openChat` with `{ user: CometChat.User }` — the message sender                   |
| Listen for event | `CometChatUIEventHandler.addUIListener`                                           |
| Hide the option  | `hideMessagePrivatelyOption` prop on `CometChatMessageList`                       |
| Return to group  | Pass `fromGroup` as nav param, call `navigation.navigate('GroupChat', { group })` |

***

## Next Steps

<CardGroup>
  <Card title="Message List" href="/ui-kit/react-native/message-list">
    Full prop reference for CometChatMessageList.
  </Card>

  <Card title="Group Members" href="/ui-kit/react-native/group-members">
    Display and manage group member lists.
  </Card>

  <Card title="Message Header" href="/ui-kit/react-native/message-header">
    Customize the chat header with back navigation.
  </Card>

  <Card title="All Guides" href="/ui-kit/react-native/guide-overview">
    Browse all feature and formatter guides.
  </Card>
</CardGroup>


# New Chat
Source: https://www.cometchat.com/docs/ui-kit/react-native/guide-new-chat

Build a unified new chat entry point for starting 1:1 or group conversations in CometChat React Native UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                           |
  | -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
  | Package        | `@cometchat/chat-uikit-react-native`                                                                                            |
  | Key components | `CometChatUsers`, `CometChatGroups`, `CometChatConversations`                                                                   |
  | Init           | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")`                                                         |
  | Purpose        | Unified new chat entry point for starting 1:1 or group conversations                                                            |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp)                                  |
  | Related        | [Users](/docs/ui-kit/react-native/users) · [Groups](/docs/ui-kit/react-native/groups) · [All Guides](/docs/ui-kit/react-native/guide-overview) |
</Accordion>

The New Chat feature lets users start conversations with other users or join group conversations from a single interface.

Before starting, complete the [Getting Started](/docs/ui-kit/react-native/react-native-cli-integration) guide.

***

## Components

| Component / Class        | Role                                               |
| :----------------------- | :------------------------------------------------- |
| `CometChatUsers`         | Displays list of available users for chat creation |
| `CometChatGroups`        | Shows available groups for joining                 |
| `CometChatConversations` | Main conversations list                            |

***

## Integration Steps

### 1. New Chat Screen with Tabs

Create a screen with tabs to switch between Users and Groups lists.

```tsx theme={null}
import React, { useState } from 'react';
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import {
  CometChatUsers,
  CometChatGroups,
  useTheme,
  useCometChatTranslation,
  Icon,
} from '@cometchat/chat-uikit-react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';

const NewChatScreen = () => {
  const navigation = useNavigation();
  const theme = useTheme();
  const { t } = useCometChatTranslation();
  const [selectedTab, setSelectedTab] = useState<'user' | 'group'>('user');

  const handleUserPress = (user: CometChat.User) => {
    navigation.navigate('Messages', { user });
  };

  const handleGroupPress = (group: CometChat.Group) => {
    if (group.getHasJoined()) {
      navigation.navigate('Messages', { group });
    } else {
      // Handle join flow for non-joined groups
      handleJoinGroup(group);
    }
  };

  const handleJoinGroup = async (group: CometChat.Group) => {
    if (group.getType() === CometChat.GROUP_TYPE.PUBLIC) {
      try {
        const joinedGroup = await CometChat.joinGroup(
          group.getGuid(),
          group.getType() as CometChat.GroupType,
          ''
        );
        navigation.navigate('Messages', { group: joinedGroup });
      } catch (error) {
        console.error('Error joining group:', error);
      }
    } else if (group.getType() === CometChat.GROUP_TYPE.PASSWORD) {
      // Show password input modal
      navigation.navigate('JoinGroup', { group });
    }
  };

  return (
    <View style={[styles.container, { backgroundColor: theme.color.background1 }]}>
      {/* Header */}
      <View style={[styles.header, { borderBottomColor: theme.color.borderLight }]}>
        <TouchableOpacity onPress={() => navigation.goBack()}>
          {/* Back icon */}
        </TouchableOpacity>
        <Text style={[theme.typography.heading1.bold, { color: theme.color.textPrimary }]}>
          {t('NEW_CHAT')}
        </Text>
      </View>

      {/* Tabs */}
      <View style={styles.tabs}>
        <TouchableOpacity
          style={[
            styles.tab,
            selectedTab === 'user' && { borderBottomColor: theme.color.primary, borderBottomWidth: 2 },
          ]}
          onPress={() => setSelectedTab('user')}
        >
          <Text style={{
            color: selectedTab === 'user' ? theme.color.primary : theme.color.textSecondary,
          }}>
            {t('USERS')}
          </Text>
        </TouchableOpacity>
        <TouchableOpacity
          style={[
            styles.tab,
            selectedTab === 'group' && { borderBottomColor: theme.color.primary, borderBottomWidth: 2 },
          ]}
          onPress={() => setSelectedTab('group')}
        >
          <Text style={{
            color: selectedTab === 'group' ? theme.color.primary : theme.color.textSecondary,
          }}>
            {t('GROUPS')}
          </Text>
        </TouchableOpacity>
      </View>

      {/* Content */}
      <View style={{ flex: 1 }}>
        {selectedTab === 'user' ? (
          <CometChatUsers
            hideHeader={true}
            onItemPress={handleUserPress}
          />
        ) : (
          <CometChatGroups
            hideHeader={true}
            onItemPress={handleGroupPress}
          />
        )}
      </View>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  header: {
    flexDirection: 'row',
    alignItems: 'center',
    padding: 15,
    borderBottomWidth: 1,
  },
  tabs: {
    flexDirection: 'row',
  },
  tab: {
    flex: 1,
    paddingVertical: 15,
    alignItems: 'center',
  },
});

export default NewChatScreen;
```

***

### 2. Add New Chat Button to Conversations

Add a floating action button or header option to launch the new chat screen.

```tsx theme={null}
import React from 'react';
import { View, TouchableOpacity, StyleSheet } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import {
  CometChatConversations,
  useTheme,
  Icon,
} from '@cometchat/chat-uikit-react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';

const ConversationsScreen = () => {
  const navigation = useNavigation();
  const theme = useTheme();

  const handleConversationPress = (conversation: CometChat.Conversation) => {
    const conversationWith = conversation.getConversationWith();
    
    if (conversationWith instanceof CometChat.User) {
      navigation.navigate('Messages', { user: conversationWith });
    } else if (conversationWith instanceof CometChat.Group) {
      navigation.navigate('Messages', { group: conversationWith });
    }
  };

  const handleNewChatPress = () => {
    navigation.navigate('NewChat');
  };

  return (
    <View style={{ flex: 1 }}>
      <CometChatConversations
        onItemPress={handleConversationPress}
        AppBarOptions={() => (
          <TouchableOpacity onPress={handleNewChatPress}>
            {/* New chat icon */}
          </TouchableOpacity>
        )}
      />
      
      {/* Floating Action Button */}
      <TouchableOpacity
        style={[styles.fab, { backgroundColor: theme.color.primary }]}
        onPress={handleNewChatPress}
      >
        {/* Plus icon */}
      </TouchableOpacity>
    </View>
  );
};

const styles = StyleSheet.create({
  fab: {
    position: 'absolute',
    bottom: 20,
    right: 20,
    width: 56,
    height: 56,
    borderRadius: 28,
    justifyContent: 'center',
    alignItems: 'center',
    elevation: 4,
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 2 },
    shadowOpacity: 0.25,
    shadowRadius: 4,
  },
});

export default ConversationsScreen;
```

***

### 3. Create Conversation Screen

A dedicated screen for creating new 1:1 conversations by selecting a user.

```tsx theme={null}
import React from 'react';
import { View } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import {
  CometChatUsers,
  useTheme,
} from '@cometchat/chat-uikit-react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';

const CreateConversationScreen = () => {
  const navigation = useNavigation();
  const theme = useTheme();

  const handleUserSelect = (user: CometChat.User) => {
    // Navigate directly to messages with selected user
    navigation.replace('Messages', { user });
  };

  return (
    <View style={{ flex: 1, backgroundColor: theme.color.background1 }}>
      <CometChatUsers
        onItemPress={handleUserSelect}
        onBack={() => navigation.goBack()}
      />
    </View>
  );
};

export default CreateConversationScreen;
```

***

### 4. Navigation Setup

Configure navigation to include all new chat related screens.

```tsx theme={null}
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import ConversationsScreen from './screens/ConversationsScreen';
import NewChatScreen from './screens/NewChatScreen';
import CreateConversationScreen from './screens/CreateConversationScreen';
import MessagesScreen from './screens/MessagesScreen';

const Stack = createNativeStackNavigator();

const AppNavigator = () => {
  return (
    <Stack.Navigator screenOptions={{ headerShown: false }}>
      <Stack.Screen name="Conversations" component={ConversationsScreen} />
      <Stack.Screen name="NewChat" component={NewChatScreen} />
      <Stack.Screen name="CreateConversation" component={CreateConversationScreen} />
      <Stack.Screen name="Messages" component={MessagesScreen} />
    </Stack.Navigator>
  );
};
```

***

## Feature Matrix

| Feature           | Component / Method                                |
| :---------------- | :------------------------------------------------ |
| User selection    | `CometChatUsers` with `onItemPress`               |
| Group selection   | `CometChatGroups` with `onItemPress`              |
| Join public group | `CometChat.joinGroup()`                           |
| Navigate to chat  | `navigation.navigate('Messages', { user/group })` |
| Tab navigation    | Custom tabs with state management                 |

***

## Next Steps

<CardGroup>
  <Card title="Conversations" href="/ui-kit/react-native/conversations">
    Display and manage conversation lists.
  </Card>

  <Card title="Users" href="/ui-kit/react-native/users">
    Display and manage user lists.
  </Card>

  <Card title="All Guides" href="/ui-kit/react-native/guide-overview">
    Browse all feature and formatter guides.
  </Card>

  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp">
    Full working sample application on GitHub.
  </Card>
</CardGroup>


# Overview
Source: https://www.cometchat.com/docs/ui-kit/react-native/guide-overview

Browse React Native UI Kit feature guides for chat layouts, Expo setup, users, conversations, methods, and tab-based messaging.

<Accordion title="AI Integration Quick Reference">
  | Field      | Value                                                                                                                                                                                                                                                                                                                                                        |
  | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Package    | `@cometchat/chat-uikit-react-native`                                                                                                                                                                                                                                                                                                                         |
  | Purpose    | Index of task-oriented feature guides for the React Native UI Kit                                                                                                                                                                                                                                                                                            |
  | Sample app | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp)                                                                                                                                                                                                                                                               |
  | Components | [Components Overview](/docs/ui-kit/react-native/components-overview)                                                                                                                                                                                                                                                                                              |
  | Guides     | [AI Agent](/docs/ui-kit/react-native/guide-ai-agent) · [New Chat](/docs/ui-kit/react-native/guide-new-chat) · [Group Chat](/docs/ui-kit/react-native/guide-group-chat) · [Threaded Messages](/docs/ui-kit/react-native/guide-threaded-messages) · [Search Messages](/docs/ui-kit/react-native/guide-search-messages) · [Block/Unblock](/docs/ui-kit/react-native/guide-block-unblock-user) |
</Accordion>

> This page indexes focused, task‑oriented feature guides for the React Native UI Kit. Each guide shows how to implement a specific capability end‑to‑end using UI components.

## When to Use These Guides

Use these guides after completing the base [Getting Started](/docs/ui-kit/react-native/react-native-cli-integration) (or [Expo Integration](/docs/ui-kit/react-native/expo-integration)). They help you layer additional UX without rewriting core chat flows.

## Guide Directory

| Guide                                                                       | Description                                                                                                          |
| :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| [AI Agent Integration](/docs/ui-kit/react-native/guide-ai-agent)                 | Enable intelligent conversational AI capabilities with AI Agent integration, chat history, and contextual responses. |
| [New Chat](/docs/ui-kit/react-native/guide-new-chat)                             | Unified entry for starting new 1:1 or group chats with user & group discovery.                                       |
| [Group Management](/docs/ui-kit/react-native/guide-group-chat)                   | Create/join groups, view members, add/ban users, change roles/scopes, transfer ownership.                            |
| [Threaded Messages](/docs/ui-kit/react-native/guide-threaded-messages)           | Threaded replies: open parent context, list replies, compose within focused thread.                                  |
| [Search Messages](/docs/ui-kit/react-native/guide-search-messages)               | Add full‑text message search across conversations with result routing into context.                                  |
| [Block/Unblock User](/docs/ui-kit/react-native/guide-block-unblock-user)         | Let users block or unblock others in 1:1 chats; hides composer and shows an unblock prompt.                          |
| [Custom Text Formatter](/docs/ui-kit/react-native/custom-text-formatter-guide)   | Extend the base formatter to implement custom inline patterns (hashtags, keywords) with regex + callbacks.           |
| [Mentions Formatter](/docs/ui-kit/react-native/mentions-formatter-guide)         | Add @mentions with styled tokens, suggestion list, and click handling for users & members.                           |
| [URL Formatter](/docs/ui-kit/react-native/url-formatter-guide)                   | Detect and style plain URLs, emails, and phone numbers as clickable links.                                           |
| [Shortcut Formatter](/docs/ui-kit/react-native/shortcut-formatter-guide)         | Provide !shortcut style expansions invoking extension APIs before inserting content.                                 |
| [Apple Privacy Manifest](/docs/ui-kit/react-native/apple-privacy-manifest-guide) | Configure required Apple Privacy Manifest for App Store compliance.                                                  |

Need another guide? Open a request via our [Support Portal](https://help.cometchat.com/hc/en-us/requests/new).

***

## Next Steps

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/ui-kit/react-native/react-native-cli-integration">
    Set up the React Native UI Kit
  </Card>

  <Card title="Components Overview" icon="puzzle-piece" href="/ui-kit/react-native/components-overview">
    Explore all UI components
  </Card>

  <Card title="Customization" icon="palette" href="/ui-kit/react-native/theme">
    Customize themes and styling
  </Card>

  <Card title="Events" icon="bolt" href="/ui-kit/react-native/events">
    Handle UI Kit events
  </Card>
</CardGroup>


# Search Messages
Source: https://www.cometchat.com/docs/ui-kit/react-native/guide-search-messages

Add full-text message search across conversations with result routing in CometChat React Native UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                 |
  | -------------- | ----------------------------------------------------------------------------------------------------- |
  | Package        | `@cometchat/chat-uikit-react-native`                                                                  |
  | Key components | `CometChatSearch`, `CometChatMessageList`                                                             |
  | Init           | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")`                               |
  | Purpose        | Full-text message search across conversations with result routing and navigation                      |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp)        |
  | Related        | [Message List](/docs/ui-kit/react-native/message-list) · [All Guides](/docs/ui-kit/react-native/guide-overview) |
</Accordion>

Search Messages lets users locate specific messages across conversations and groups using keyword search, then navigate directly to the result.

Before starting, complete the [Getting Started](/docs/ui-kit/react-native/react-native-cli-integration) guide.

***

## Components

| Component / Class      | Role                                                                |
| :--------------------- | :------------------------------------------------------------------ |
| `CometChatSearch`      | Main search interface with conversation and message results         |
| `CometChatMessageList` | Displays messages with search highlighting via `searchKeyword` prop |

***

## Integration Steps

### 1. Search Messages Screen

Create a dedicated search screen using `CometChatSearch` component.

```tsx theme={null}
import React, { useCallback } from 'react';
import { View, StyleSheet, BackHandler, Platform } from 'react-native';
import { useRoute, useNavigation } from '@react-navigation/native';
import {
  CometChatSearch,
  useTheme,
} from '@cometchat/chat-uikit-react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';

const SearchMessagesScreen = () => {
  const route = useRoute();
  const navigation = useNavigation();
  const theme = useTheme();
  const { user, group } = route.params || {};

  // Handle back button
  const handleBack = useCallback(() => {
    navigation.goBack();
  }, [navigation]);

  // Handle conversation click from search results
  const handleConversationClicked = useCallback(
    (conversation: CometChat.Conversation, searchKeyword?: string) => {
      const conversationWith = conversation.getConversationWith();

      if (conversationWith instanceof CometChat.User) {
        navigation.navigate('Messages', {
          user: conversationWith,
          searchKeyword,
        });
      } else if (conversationWith instanceof CometChat.Group) {
        navigation.navigate('Messages', {
          group: conversationWith,
          searchKeyword,
        });
      }
    },
    [navigation]
  );

  // Handle message click from search results
  const handleMessageClicked = useCallback(
    async (message: CometChat.BaseMessage, searchKeyword?: string) => {
      const messageReceiver = message.getReceiver();
      const parentMessageId = message.getParentMessageId();

      let targetUser: CometChat.User | undefined;
      let targetGroup: CometChat.Group | undefined;

      if (messageReceiver instanceof CometChat.User) {
        const sender = message.getSender();
        const loggedInUser = await CometChat.getLoggedinUser();

        if (sender.getUid() === loggedInUser?.getUid()) {
          targetUser = messageReceiver;
        } else {
          targetUser = sender;
        }
      } else if (messageReceiver instanceof CometChat.Group) {
        targetGroup = messageReceiver;
      }

      // If message is in a thread, navigate to thread view
      if (parentMessageId) {
        try {
          const parentMessage = await CometChat.getMessageDetails(parentMessageId);
          if (parentMessage) {
            navigation.navigate('ThreadView', {
              message: parentMessage,
              user: targetUser,
              group: targetGroup,
              highlightMessageId: String(message.getId()),
            });
            return;
          }
        } catch (e) {
          console.error('Failed to fetch parent message', e);
        }
      }

      // Navigate to messages screen with highlight
      if (targetUser) {
        navigation.navigate('Messages', {
          user: targetUser,
          messageId: String(message.getId()),
          searchKeyword,
        });
      } else if (targetGroup) {
        navigation.navigate('Messages', {
          group: targetGroup,
          messageId: String(message.getId()),
          searchKeyword,
        });
      }
    },
    [navigation]
  );

  // Determine placeholder text
  let searchPlaceholder = 'Search';
  if (user?.getName()) {
    searchPlaceholder = `Search in ${user.getName()}`;
  } else if (group?.getName()) {
    searchPlaceholder = `Search in ${group.getName()}`;
  }

  return (
    <View style={styles.container}>
      <CometChatSearch
        onBack={handleBack}
        hideBackButton={false}
        onConversationClicked={handleConversationClicked}
        onMessageClicked={handleMessageClicked}
        uid={user?.getUid()}
        guid={group?.getGuid()}
        searchPlaceholder={searchPlaceholder}
        messagesRequestBuilder={
          new CometChat.MessagesRequestBuilder().setLimit(30)
        }
        conversationsRequestBuilder={
          new CometChat.ConversationsRequestBuilder().setLimit(30)
        }
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

export default SearchMessagesScreen;
```

***

### 2. Trigger Search from Messages Screen

Add a search button to your messages header that navigates to the search screen.

```tsx theme={null}
import React from 'react';
import { View, TouchableOpacity } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import {
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  Icon,
} from '@cometchat/chat-uikit-react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';

interface MessagesScreenProps {
  user?: CometChat.User;
  group?: CometChat.Group;
  messageId?: string;
  searchKeyword?: string;
}

const MessagesScreen: React.FC<MessagesScreenProps> = ({
  user,
  group,
  messageId,
  searchKeyword,
}) => {
  const navigation = useNavigation();

  const handleSearchPress = () => {
    navigation.navigate('SearchMessages', { user, group });
  };

  return (
    <View style={{ flex: 1 }}>
      <CometChatMessageHeader
        user={user}
        group={group}
        AppBarOptions={() => (
          <TouchableOpacity onPress={handleSearchPress}>
            {/* Search icon */}
          </TouchableOpacity>
        )}
      />
      
      <CometChatMessageList
        user={user}
        group={group}
        goToMessageId={messageId}
        searchKeyword={searchKeyword}
      />
      
      <CometChatMessageComposer user={user} group={group} />
    </View>
  );
};
```

***

### 3. Highlight Search Results

When navigating from search results, pass `searchKeyword` to highlight matching text in messages.

```tsx theme={null}
<CometChatMessageList
  user={user}
  group={group}
  goToMessageId={messageId}      // Scroll to specific message
  searchKeyword={searchKeyword}  // Highlight matching text
/>
```

***

### 4. Navigation Setup

Add the search screen to your navigation stack.

```tsx theme={null}
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import MessagesScreen from './screens/MessagesScreen';
import SearchMessagesScreen from './screens/SearchMessagesScreen';
import ThreadView from './screens/ThreadView';

const Stack = createNativeStackNavigator();

const AppNavigator = () => {
  return (
    <Stack.Navigator screenOptions={{ headerShown: false }}>
      <Stack.Screen name="Messages" component={MessagesScreen} />
      <Stack.Screen name="SearchMessages" component={SearchMessagesScreen} />
      <Stack.Screen name="ThreadView" component={ThreadView} />
    </Stack.Navigator>
  );
};
```

***

## Feature Matrix

| Feature              | Component / Prop                               |
| :------------------- | :--------------------------------------------- |
| Search interface     | `CometChatSearch`                              |
| Conversation results | `onConversationClicked` callback               |
| Message results      | `onMessageClicked` callback                    |
| Scoped search        | `uid` or `guid` props to limit search scope    |
| Keyword highlighting | `searchKeyword` prop on `CometChatMessageList` |
| Navigate to message  | `goToMessageId` prop on `CometChatMessageList` |

***

## Next Steps

<CardGroup>
  <Card title="Message List" href="/ui-kit/react-native/message-list">
    Render real-time message threads.
  </Card>

  <Card title="Threaded Messages" href="/ui-kit/react-native/guide-threaded-messages">
    Implement threaded message replies.
  </Card>

  <Card title="All Guides" href="/ui-kit/react-native/guide-overview">
    Browse all feature and formatter guides.
  </Card>

  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp">
    Full working sample application on GitHub.
  </Card>
</CardGroup>


# Threaded Messages
Source: https://www.cometchat.com/docs/ui-kit/react-native/guide-threaded-messages

Implement threaded message replies with parent context, reply list, and focused thread composer in CometChat React Native UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                                  |
  | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package        | `@cometchat/chat-uikit-react-native`                                                                                                                                   |
  | Key components | `CometChatThreadHeader`, `CometChatMessageList`, `CometChatMessageComposer`                                                                                            |
  | Init           | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")`                                                                                                |
  | Entry point    | Pass `parentMessageId` prop to `CometChatMessageList` and `CometChatMessageComposer`                                                                                   |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp)                                                                         |
  | Related        | [Message List](/docs/ui-kit/react-native/message-list) · [Thread Header](/docs/ui-kit/react-native/threaded-messages-header) · [All Guides](/docs/ui-kit/react-native/guide-overview) |
</Accordion>

Threaded messages let users create sub-conversations by replying to specific messages in group chats. This reduces clutter and keeps discussions focused.

Before starting, complete the [Getting Started](/docs/ui-kit/react-native/react-native-cli-integration) guide.

***

## Components

| Component / Class          | Role                                         |
| :------------------------- | :------------------------------------------- |
| `CometChatThreadHeader`    | Displays parent message context              |
| `CometChatMessageList`     | Shows messages filtered by `parentMessageId` |
| `CometChatMessageComposer` | Input for composing threaded replies         |

***

## Integration Steps

### 1. Thread View Screen

Create a dedicated screen for threaded messages that receives the parent message via navigation params.

```tsx theme={null}
import React, { useCallback } from 'react';
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
import { useRoute, useNavigation } from '@react-navigation/native';
import {
  CometChatThreadHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  useTheme,
  useCometChatTranslation,
  Icon,
} from '@cometchat/chat-uikit-react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';

const ThreadView = () => {
  const route = useRoute();
  const navigation = useNavigation();
  const theme = useTheme();
  const { t } = useCometChatTranslation();
  
  const { message, user, group } = route.params || {};

  const handleBack = useCallback(() => {
    navigation.goBack();
  }, [navigation]);

  return (
    <View style={{ backgroundColor: theme.color.background1, flex: 1 }}>
      {/* Custom Header */}
      <View style={styles.headerStyle}>
        <TouchableOpacity onPress={handleBack}>
          {/* Back icon */}
        </TouchableOpacity>
        <View style={styles.textStyle}>
          <Text style={[theme.typography.heading1.bold, { color: theme.color.textPrimary }]}>
            {t('THREAD')}
          </Text>
          <Text
            style={[theme.typography.caption1.regular, { color: theme.color.textSecondary }]}
            numberOfLines={1}
          >
            {user ? user.getName() : group?.getName()}
          </Text>
        </View>
      </View>

      {/* Thread Header - shows parent message */}
      <CometChatThreadHeader parentMessage={message} />

      {/* Threaded Message List */}
      <View style={{ flex: 1 }}>
        <CometChatMessageList
          user={user}
          group={group}
          parentMessageId={message.getId().toString()}
        />
      </View>

      {/* Message Composer for Thread */}
      <CometChatMessageComposer
        user={user}
        group={group}
        parentMessageId={message.getId()}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  headerStyle: {
    paddingVertical: 10,
    paddingLeft: 10,
    flexDirection: 'row',
  },
  textStyle: {
    paddingLeft: 10,
    alignItems: 'flex-start',
  },
});

export default ThreadView;
```

***

### 2. Trigger Thread View from Messages

In your main messages screen, handle the `onThreadRepliesClick` callback to navigate to the thread view.

```tsx theme={null}
import React from 'react';
import { View } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import {
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from '@cometchat/chat-uikit-react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';

interface MessagesScreenProps {
  user?: CometChat.User;
  group?: CometChat.Group;
}

const MessagesScreen: React.FC<MessagesScreenProps> = ({ user, group }) => {
  const navigation = useNavigation();

  const handleThreadRepliesClick = (message: CometChat.BaseMessage) => {
    navigation.navigate('ThreadView', {
      message,
      user,
      group,
    });
  };

  return (
    <View style={{ flex: 1 }}>
      <CometChatMessageHeader user={user} group={group} />
      
      <CometChatMessageList
        user={user}
        group={group}
        onThreadRepliesClick={handleThreadRepliesClick}
      />
      
      <CometChatMessageComposer user={user} group={group} />
    </View>
  );
};
```

***

### 3. Navigation Setup

Configure React Navigation to include the ThreadView screen.

```tsx theme={null}
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import MessagesScreen from './screens/MessagesScreen';
import ThreadView from './screens/ThreadView';

const Stack = createNativeStackNavigator();

const AppNavigator = () => {
  return (
    <Stack.Navigator screenOptions={{ headerShown: false }}>
      <Stack.Screen name="Messages" component={MessagesScreen} />
      <Stack.Screen name="ThreadView" component={ThreadView} />
    </Stack.Navigator>
  );
};
```

***

### 4. Navigate to Specific Message in Thread

Support navigating to a specific message within a thread using `goToMessageId` prop.

```tsx theme={null}
<CometChatMessageList
  user={user}
  group={group}
  parentMessageId={message.getId().toString()}
  goToMessageId={highlightMessageId} // Optional: scroll to specific message
/>
```

***

### 5. Handle Blocked Users in Threads

Show an unblock prompt when the user is blocked instead of the composer.

```tsx theme={null}
import React, { useState } from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { CometChat } from '@cometchat/chat-sdk-react-native';
import {
  CometChatMessageComposer,
  CometChatUIEventHandler,
  CometChatUIEvents,
  useTheme,
  useCometChatTranslation,
} from '@cometchat/chat-uikit-react-native';

interface ThreadComposerProps {
  user?: CometChat.User;
  group?: CometChat.Group;
  parentMessageId: number;
}

const ThreadComposer: React.FC<ThreadComposerProps> = ({ user, group, parentMessageId }) => {
  const theme = useTheme();
  const { t } = useCometChatTranslation();
  const [localUser, setLocalUser] = useState(user);

  const unblock = async () => {
    if (!localUser) return;
    
    try {
      await CometChat.unblockUsers([localUser.getUid()]);
      const freshUser = await CometChat.getUser(localUser.getUid());
      setLocalUser(freshUser);
      
      CometChatUIEventHandler.emitUserEvent(
        CometChatUIEvents.ccUserUnBlocked,
        { user: freshUser }
      );
    } catch (error) {
      console.error('Error unblocking user:', error);
    }
  };

  if (localUser?.getBlockedByMe()) {
    return (
      <View style={{ alignItems: 'center', padding: 20, backgroundColor: theme.color.background3 }}>
        <Text style={{ color: theme.color.textSecondary, textAlign: 'center' }}>
          {t('BLOCKED_USER_DESC')}
        </Text>
        <TouchableOpacity onPress={unblock} style={{ marginTop: 10 }}>
          <Text style={{ color: theme.color.textPrimary }}>{t('UNBLOCK')}</Text>
        </TouchableOpacity>
      </View>
    );
  }

  return (
    <CometChatMessageComposer
      user={localUser}
      group={group}
      parentMessageId={parentMessageId}
    />
  );
};
```

***

## Feature Matrix

| Feature                | Component / Prop                                          |
| :--------------------- | :-------------------------------------------------------- |
| Display parent message | `CometChatThreadHeader` with `parentMessage` prop         |
| Show thread replies    | `CometChatMessageList` with `parentMessageId` prop        |
| Compose thread reply   | `CometChatMessageComposer` with `parentMessageId` prop    |
| Navigate to message    | `goToMessageId` prop on `CometChatMessageList`            |
| Thread trigger         | `onThreadRepliesClick` callback on `CometChatMessageList` |

***

## Next Steps

<CardGroup>
  <Card title="Message List" href="/ui-kit/react-native/message-list">
    Render real-time message threads.
  </Card>

  <Card title="Thread Header" href="/ui-kit/react-native/threaded-messages-header">
    Customize the thread header component.
  </Card>

  <Card title="All Guides" href="/ui-kit/react-native/guide-overview">
    Browse all feature and formatter guides.
  </Card>

  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp">
    Full working sample application on GitHub.
  </Card>
</CardGroup>


# Incoming Call
Source: https://www.cometchat.com/docs/ui-kit/react-native/incoming-call

Display and handle incoming voice and video calls with CometChatIncomingCall component in React Native UI Kit, providing options to accept or decline.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatIncomingCall",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatIncomingCall } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Visual representation for incoming voice and video calls with accept/decline options.",
    "props": {
      "data": {
        "call": {
          "type": "CometChat.Call | CometChat.CustomMessage",
          "note": "The incoming call object"
        }
      },
      "callbacks": {
        "onAccept": "(call: CometChat.BaseMessage) => void",
        "onDecline": "(call: CometChat.BaseMessage) => void",
        "onError": "(error: CometChat.CometChatException) => void"
      },
      "sound": {
        "disableSoundForCalls": { "type": "boolean", "default": false },
        "customSoundForCalls": { "type": "string", "default": "built-in" }
      },
      "viewSlots": {
        "ItemView": "(call) => JSX.Element",
        "LeadingView": "(call) => JSX.Element",
        "TitleView": "(call) => JSX.Element",
        "SubtitleView": "(call) => JSX.Element",
        "TrailingView": "(call) => JSX.Element"
      }
    },
    "events": [
      { "name": "ccCallRejected", "payload": "{ call }", "description": "Call rejected by receiver" },
      { "name": "ccCallAccepted", "payload": "{ call }", "description": "Call accepted by receiver" },
      { "name": "ccCallEnded", "payload": "{ call }", "description": "Call successfully ended" },
      { "name": "ccCallFailled", "payload": "{ call }", "description": "Error during call" }
    ]
  }
  ```
</Accordion>

## Where It Fits

`CometChatIncomingCall` is a [Component](/docs/ui-kit/react-native/components-overview#components) that serves as a visual representation when the user receives an incoming call, such as a voice call or video call, providing options to answer or decline the call.

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";
import { useState, useRef, useEffect } from "react";

function IncomingCallDemo() {
  const incomingCall = useRef<CometChat.Call | null>(null);
  const [callReceived, setCallReceived] = useState(false);
  const listenerId = "INCOMING_CALL_LISTENER";

  useEffect(() => {
    CometChat.addCallListener(
      listenerId,
      new CometChat.CallListener({
        onIncomingCallReceived: (call) => {
          incomingCall.current = call;
          setCallReceived(true);
        },
        onIncomingCallCancelled: (call) => {
          incomingCall.current = null;
          setCallReceived(false);
        },
      })
    );

    return () => {
      CometChat.removeCallListener(listenerId);
    };
  }, []);

  return (
    <>
      {callReceived && incomingCall.current && (
        <CometChatIncomingCall
          call={incomingCall.current}
          onDecline={() => setCallReceived(false)}
        />
      )}
    </>
  );
}
```

***

## Actions and Events

### Callback Props

#### onAccept

Fires when the accept button is pressed.

```tsx lines theme={null}
onAccept?: (call: CometChat.BaseMessage) => void
```

```tsx lines theme={null}
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function IncomingCallWithAccept() {
  const handleAccept = (call: CometChat.BaseMessage) => {
    console.log("Call accepted:", call);
  };

  return (
    <CometChatIncomingCall
      call={incomingCall}
      onAccept={handleAccept}
      onDecline={() => setCallReceived(false)}
    />
  );
}
```

#### onDecline

Fires when the decline button is pressed.

```tsx lines theme={null}
onDecline?: (call: CometChat.BaseMessage) => void
```

```tsx lines theme={null}
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";

function IncomingCallWithDecline() {
  const handleDecline = (call) => {
    console.log("Call declined");
    setCallReceived(false);
  };

  return (
    <CometChatIncomingCall
      call={incomingCall}
      onDecline={handleDecline}
    />
  );
}
```

#### onError

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

```tsx lines theme={null}
onError?: (error: CometChat.CometChatException) => void
```

```tsx lines theme={null}
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function IncomingCallWithError() {
  return (
    <CometChatIncomingCall
      call={incomingCall}
      onDecline={() => setCallReceived(false)}
      onError={(error: CometChat.CometChatException) => {
        console.error("IncomingCall error:", error);
      }}
    />
  );
}
```

### Global UI Events

`CometChatUIEventHandler` emits events subscribable from anywhere in the application. Add listeners and remove them on cleanup.

| Event            | Fires when                                 | Payload    |
| ---------------- | ------------------------------------------ | ---------- |
| `ccCallRejected` | Initiated call is rejected by the receiver | `{ call }` |
| `ccCallAccepted` | Initiated call is accepted by the receiver | `{ call }` |
| `ccCallEnded`    | Initiated call successfully ends           | `{ call }` |
| `ccCallFailled`  | Error occurs during the initiated call     | `{ call }` |

When to use: sync external UI with call state changes. For example, update a call status indicator, show notifications, or log call events.

```tsx lines theme={null}
import { useEffect } from "react";
import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";

function useIncomingCallEvents() {
  useEffect(() => {
    const listenerId = "INCOMING_CALL_EVENTS_" + Date.now();

    CometChatUIEventHandler.addCallListener(listenerId, {
      ccCallRejected: ({ call }) => {
        console.log("Call rejected:", call);
      },
      ccCallAccepted: ({ call }) => {
        console.log("Call accepted:", call);
      },
      ccCallEnded: ({ call }) => {
        console.log("Call ended:", call);
      },
      ccCallFailled: ({ call }) => {
        console.log("Call failed:", call);
      },
    });

    return () => {
      CometChatUIEventHandler.removeCallListener(listenerId);
    };
  }, []);
}
```

***

## Custom View Slots

Each slot replaces a section of the default UI. Slots that accept a call parameter receive the call object for customization.

| Slot           | Signature               | Replaces                  |
| -------------- | ----------------------- | ------------------------- |
| `ItemView`     | `(call) => JSX.Element` | Entire incoming call card |
| `LeadingView`  | `(call) => JSX.Element` | Avatar / left section     |
| `TitleView`    | `(call) => JSX.Element` | Caller name / title text  |
| `SubtitleView` | `(call) => JSX.Element` | Call type / status text   |
| `TrailingView` | `(call) => JSX.Element` | Accept/decline buttons    |

### ItemView

Custom view for the entire incoming call card.

```tsx lines theme={null}
ItemView?: (call: CometChat.Call | CometChat.CustomMessage) => JSX.Element
```

```tsx lines theme={null}
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function ItemViewDemo() {
  const getItemView = (call: CometChat.Call | CometChat.CustomMessage) => {
    return (
      <View style={{ padding: 20, backgroundColor: '#6852D6' }}>
        <Text style={{ color: 'white' }}>Incoming Call</Text>
      </View>
    );
  };

  return (
    <CometChatIncomingCall
      call={incomingCall}
      onDecline={() => setCallReceived(false)}
      ItemView={getItemView}
    />
  );
}
```

### LeadingView

Custom view for the avatar / left section.

```tsx lines theme={null}
LeadingView?: (call: CometChat.Call | CometChat.CustomMessage) => JSX.Element
```

```tsx lines theme={null}
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function LeadingViewDemo() {
  const getLeadingView = (call: CometChat.Call | CometChat.CustomMessage) => {
    const caller = call.getCallInitiator();
    return (
      <View style={{ width: 60, height: 60, borderRadius: 30, backgroundColor: '#6852D6' }}>
        <Text style={{ color: 'white', textAlign: 'center', lineHeight: 60 }}>
          {caller.getName().charAt(0)}
        </Text>
      </View>
    );
  };

  return (
    <CometChatIncomingCall
      call={incomingCall}
      onDecline={() => setCallReceived(false)}
      LeadingView={getLeadingView}
    />
  );
}
```

### SubtitleView

Custom view for the call type / status text.

```tsx lines theme={null}
SubtitleView?: (call: CometChat.Call | CometChat.CustomMessage) => JSX.Element
```

```tsx lines theme={null}
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { Text } from "react-native";

function SubtitleViewDemo() {
  const getSubtitleView = (call: CometChat.Call | CometChat.CustomMessage) => {
    const callType = call.getType() === "audio" ? "Voice Call" : "Video Call";
    return <Text style={{ color: '#727272' }}>{callType}</Text>;
  };

  return (
    <CometChatIncomingCall
      call={incomingCall}
      onDecline={() => setCallReceived(false)}
      SubtitleView={getSubtitleView}
    />
  );
}
```

***

## 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 `CometChatIncomingCall` component.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatIncomingCall, useTheme } from "@cometchat/chat-uikit-react-native";

function StylingDemo() {
  const theme = useTheme();

  return (
    <CometChatIncomingCall
      call={incomingCall}
      onDecline={() => setCallReceived(false)}
      style={{
        containerStyle: {
          backgroundColor: theme.color.extendedPrimary100,
        },
        avatarStyle: {
          containerStyle: {
            backgroundColor: theme.color.extendedPrimary500,
            borderRadius: 8,
          },
          imageStyle: {
            borderRadius: 8,
          },
        },
        declineCallButtonStyle: {
          backgroundColor: theme.color.staticWhite,
        },
        declineCallTextStyle: {
          color: theme.color.error,
        },
        acceptCallButtonStyle: {
          backgroundColor: theme.color.primary,
        },
      }}
    />
  );
}
```

### Visibility Props

| Property               | Description                                | Code                             |
| ---------------------- | ------------------------------------------ | -------------------------------- |
| `disableSoundForCalls` | Disable/enable the sound of incoming calls | `disableSoundForCalls?: boolean` |
| `customSoundForCalls`  | Set custom sound for incoming calls        | `customSoundForCalls?: string`   |

***

## Next Steps

<CardGroup>
  <Card title="Outgoing Call" icon="phone-arrow-up-right" href="/ui-kit/react-native/outgoing-call">
    Display and manage outgoing calls
  </Card>

  <Card title="Call Buttons" icon="phone" href="/ui-kit/react-native/call-buttons">
    Add voice and video call buttons to your UI
  </Card>

  <Card title="Call Features" icon="video" href="/ui-kit/react-native/call-features">
    Overview of all calling features
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>


# Changelog
Source: https://www.cometchat.com/docs/ui-kit/react-native/link/changelog

Navigate to Changelog documentation.



# React Native Sample App
Source: https://www.cometchat.com/docs/ui-kit/react-native/link/sample

Navigate to React Native Sample App documentation.



# Localization
Source: https://www.cometchat.com/docs/ui-kit/react-native/localize

Configure multi-language localization, custom translations, and automatic device language detection in CometChat React Native UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field               | Value                                                                                   |
  | ------------------- | --------------------------------------------------------------------------------------- |
  | Goal                | Add multi-language support with automatic device language detection                     |
  | Provider            | `CometChatI18nProvider` — wrap app to enable localization                               |
  | Import              | `import { CometChatI18nProvider } from "@cometchat/chat-uikit-react-native";`           |
  | Auto-detect         | `<CometChatI18nProvider autoDetectLanguage={true}>`                                     |
  | Set language        | `selectedLanguage="fr"` — manually set language code                                    |
  | Override strings    | `translations={{ "en-US": { CHATS: "My Chats" } }}`                                     |
  | Add language        | `translations={{ "custom": { CHATS: "Welcome" } }}` with `selectedLanguage="custom"`    |
  | Use in components   | `const { t } = useCometChatTranslation(); t("CHATS")`                                   |
  | Supported languages | 19: en-US, en-GB, zh, zh-TW, es, hi, ru, pt, ms, fr, de, sv, lt, hu, it, ko, ja, nl, tr |
  | Dependency          | Requires `react-native-localize` package for auto-detection                             |
</Accordion>

The `CometChatI18nProvider` manages multi-language localization for the UI Kit. It handles automatic language detection, manual language switching, and custom translations.

<Warning>
  Prerequisites:

  1. Install `react-native-localize`: `npm install react-native-localize`
  2. Wrap your app with `CometChatI18nProvider` inside `CometChatThemeProvider`
  3. Without the provider wrapper, automatic language detection won't work
</Warning>

***

## Supported Languages

| Language                 | Code    |
| ------------------------ | ------- |
| English (United States)  | `en-US` |
| English (United Kingdom) | `en-GB` |
| Chinese                  | `zh`    |
| Chinese (Traditional)    | `zh-TW` |
| Spanish                  | `es`    |
| Hindi                    | `hi`    |
| Russian                  | `ru`    |
| Portuguese               | `pt`    |
| Malay                    | `ms`    |
| French                   | `fr`    |
| German                   | `de`    |
| Swedish                  | `sv`    |
| Lithuanian               | `lt`    |
| Hungarian                | `hu`    |
| Italian                  | `it`    |
| Korean                   | `ko`    |
| Japanese                 | `ja`    |
| Dutch                    | `nl`    |
| Turkish                  | `tr`    |

***

## Provider Props

| Prop                 | Type      | Description                                                  |
| -------------------- | --------- | ------------------------------------------------------------ |
| `selectedLanguage`   | `string`  | Language code to use. Defaults to device language or English |
| `autoDetectLanguage` | `boolean` | Auto-detect device language. Default: `true`                 |
| `translations`       | `object`  | Custom translation overrides per language                    |
| `fallbackLanguage`   | `string`  | Fallback language if selected is unavailable                 |

***

## Prerequisites

To enable localization features in your React Native application, you need to install the `react-native-localize` package. This package provides native device locale detection and is required for the automatic language detection functionality.

### Installation

Install the required dependency:

```bash theme={null}
npm install react-native-localize
```

## Usage

Here is how you can implement custom localization:

### Basic Usage (System Language Detection)

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    import React from "react";
    import { SafeAreaView } from "react-native-safe-area-context";
    import {
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";

    const App = () => {
      return (
        <SafeAreaView style={{ flex: 1 }}>
          <CometChatThemeProvider theme={{ mode: "light" }}>
            <CometChatI18nProvider autoDetectLanguage={true}>
              {/* Other Components */}
            </CometChatI18nProvider>
          </CometChatThemeProvider>
        </SafeAreaView>
      );
    };
    ```
  </Tab>
</Tabs>

### Overriding Translations

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    import React from "react";
    import { SafeAreaView } from "react-native-safe-area-context";
    import {
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";

    const App = () => {
      const translations = {
        // Overridden translations
        "en-US": {
          CHATS: "Welcome to the CometChat App",
        },
        "en-GB": {
          CHATS: "Welcome to CometChat",
        },
        custom: {
          CHATS: "Welcome",
        },
      };

      return (
        <SafeAreaView style={{ flex: 1 }}>
          <CometChatThemeProvider theme={{ mode: "light" }}>
            <CometChatI18nProvider
              selectedLanguage="custom"
              translations={translations}
            >
              {/* Other Components */}
            </CometChatI18nProvider>
          </CometChatThemeProvider>
        </SafeAreaView>
      );
    };
    ```
  </Tab>
</Tabs>

### Using Translations in Custom Components

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    import React from "react";
    import { View, Text, TouchableOpacity } from "react-native";
    import { useCometChatTranslation } from "@cometchat/chat-uikit-react-native";

    const CustomComponent = () => {
      const { t } = useCometChatTranslation();

      return (
        <View style={{ padding: 20 }}>
          <Text style={{ fontSize: 18, fontWeight: "bold" }}>
            {t("WELCOME_MESSAGE")}
          </Text>
          <TouchableOpacity
            style={{ marginTop: 10, padding: 10, backgroundColor: "#007bff" }}
            onPress={() => {
              console.log(t("BUTTON_CLICKED"));
            }}
          >
            <Text style={{ color: "white", textAlign: "center" }}>
              {t("CLICK_HERE")}
            </Text>
          </TouchableOpacity>
        </View>
      );
    };
    ```
  </Tab>
</Tabs>

CometChat UI Kit provides a `useCometChatTranslation` hook to access translations within components, which can be used when developing custom components.

***

## Methods

### useCometChatTranslation

Hook to access translations within components.

```ts theme={null}
import { useCometChatTranslation } from "@cometchat/chat-uikit-react-native";

const { t } = useCometChatTranslation();
const translatedText = t("CHATS"); // Returns localized string
```

***

## Customization Capabilities

Below are the things which the developer can customize:

* **Set a supported language** (`selectedLanguage`): The developer can set a language out of the 19 supported languages.
* **Customize default localization strings** (`translations`): The developer can customize default localization strings for a particular language.
* **Add custom strings** (`translations`): A developer can add custom strings in the localization for a particular language.
* **Add a new language** (`translations`): The developer can add completely new languages.
* **Disable auto detection** (`autoDetectLanguage`): The developer can disable auto detection of device language.
* **Handle missing keys**: The developer can handle missing localization keys.
* **Set fallback language** (`fallbackLanguage`): The developer can set a fallback language.

By using the `CometChatI18nProvider` component and `useCometChatTranslation` hook, you can provide a user-friendly, localized experience to your users, enhancing the overall user experience within your application.

***

## Next Steps

<CardGroup>
  <Card title="Introduction to Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Learn how CometChatThemeProvider manages light and dark modes
  </Card>

  <Card title="Sound Manager" icon="volume" href="/ui-kit/react-native/sound-manager">
    Manage audio playback for incoming and outgoing events
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Explore all available UI Kit components
  </Card>

  <Card title="Getting Started" icon="rocket" href="/ui-kit/react-native/react-native-cli-integration">
    Set up CometChat UI Kit in your React Native app
  </Card>
</CardGroup>


# Mentions Formatter
Source: https://www.cometchat.com/docs/ui-kit/react-native/mentions-formatter-guide

Format and style @mentions in chat messages with customizable text styles and click handlers using CometChatMentionsFormatter.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                                                               |
  | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package        | `@cometchat/chat-uikit-react-native`                                                                                                                                                                |
  | Key class      | `CometChatMentionsFormatter` (extends `CometChatTextFormatter`)                                                                                                                                     |
  | Required setup | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")`                                                                                                                             |
  | Purpose        | Format and style @mentions in chat messages with customizable text styles and click handlers                                                                                                        |
  | Features       | Mention formatting, customizable styles, user/group member mentions, mention list generation, click handling                                                                                        |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/sample)                                                                                                                  |
  | Related        | [ShortCut Formatter](/docs/ui-kit/react-native/shortcut-formatter-guide) · [Custom Text Formatter](/docs/ui-kit/react-native/custom-text-formatter-guide) · [All Guides](/docs/ui-kit/react-native/guide-overview) |
</Accordion>

## Overview

The `CometChatMentionsFormatter` class is a part of the CometChat UI Kit, a ready-to-use chat UI component library for integrating CometChat into your Android applications. This class provides functionality to format mentions within text messages displayed in the chat interface. Mentions allow users to reference other users within a conversation, providing a convenient way to direct messages or involve specific participants.

## Features

* **Mention Formatting**: Automatically formats mentions within text messages based on provided styles and settings.
* **Customizable Styles**: Allows customization of text styles for mentions, including colors, fonts, and background colors.
* **User and Group Member Mentions**: Supports mentions for both individual users and group members, providing flexibility in communication scenarios.
* **Mention List Generation**: Generates a list of suggested mentions based on user input, facilitating easy selection of recipients during message composition.
* **Mention Click Handling**: Provides a listener interface for handling click events on mentions, enabling custom actions to be performed when a mention is tapped by the user.

## Usage

To integrate the `CometChatMentionsFormatter` class into your application:

1. **Initialization**: Create an instance of the `CometChatMentionsFormatter` class and configure it with desired settings, such as mention text styles and limit settings.

2. **Set Mention Listeners**: Set listeners for handling mention click events (`setOnMentionClick`).

3. **Customization**: Customize the appearance and behavior of mentions by adjusting the text styles, colors, and other formatting properties as needed.

Below is an example demonstrating how to use the `CometChatMentionsFormatter` class in components such as [CometChatConversations](/docs/ui-kit/react-native/conversations), [CometChatMessageList](/docs/ui-kit/react-native/message-list), [CometChatMessageComposer](/docs/ui-kit/react-native/message-composer).

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    // Initialize CometChatMentionsFormatter
    const mentionsFormatter: CometChatMentionsFormatter =
      new CometChatMentionsFormatter();
    const textFormatters: Array<CometChatTextFormatter> = [mentionsFormatter];
    textFormatters.push(mentionsFormatter);
    // This can be passed as an array of formatter in CometChatConversations, MessageList or Message Composer by using textFormatters prop.
    ```
  </Tab>
</Tabs>

***

## Actions

[Actions](/docs/ui-kit/react-native/components-overview#actions) dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the component to fit your specific needs.

##### setOnMentionClick

Setting a listener for mention-click events in Message Bubbles enhances interactivity within the chat. This listener is activated when a mention is clicked, returning the corresponding user object. This feature transforms mentions into interactive links, enabling more in-depth and contextual engagement with the user associated with the clicked mention.

**Example**

<Tabs>
  <Tab title="iOS">
    <img alt="Image" />
  </Tab>

  <Tab title="Android">
    <img alt="Image" />
  </Tab>
</Tabs>

<Tabs>
  <Tab title="TypeScript">
    ```tsx lines theme={null}

    import React from "react";
    import { CometChat } from '@cometchat/chat-sdk-react-native';
    import { CometChatMessageList, CometChatMentionsFormatter } from '@cometchat/chat-uikit-react-native';

    function App(): React.JSX.Element {
        const [chatUser, setChatUser] = React.useState<CometChat.User| undefined>();

        React.useEffect(() => {
            CometChat.getUser("uid").then((user) => {
                setChatUser(user);
            })
        }, []);

        const mentionsFormatter = new CometChatMentionsFormatter();

        mentionsFormatter.setOnMentionClick((message: CometChat.BaseMessage, uid: string) => {
           const mentionedUsers = message.getMentionedUsers();
           let user;
           for(let i = 0; i < mentionedUsers.length; i++) {
               if(uid == mentionedUsers[i].getUid()) {
                  user = mentionedUsers[i];
               }
            }
            console.log("Mention clicked:", user?.getName());
        })

        return (
         <>
            { chatUser && <CometChatMessageList
                 user={chatUser}
                 textFormatters={[mentionsFormatter]}
            />}
         </>
       );
      }
    ```
  </Tab>
</Tabs>

***

## Customization

| Methods                            | Description                                                  | Code                                                                                                               |
| ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| **Set Mention Limit**              | Sets the limit for the number of mentions allowed.           | `setLimit(limit: number)`                                                                                          |
| **Set GroupMembersRequestBuilder** | Sets the builder for fetching users or group members.        | `setSearchRequestBuilder(requestBuilder: CometChat.UsersRequestBuilder` \| `CometChat.GroupMembersRequestBuilder)` |
| **Set OnMentionClick**             | Sets a listener for mention click in Message Bubbles events. | `setOnMentionClick(callBack: (message: CometChat.BaseMessage, uid: string) => void);`                              |

***

## Advance

For advanced-level customization, you can set the style of the Mentions formatters. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your formatters style.

### MentionTextStyle

MentionTextStyle is a class that is used to provide over all styling to a particular mentions formatted text

| Methods           | Type      | Description                                                   |
| ----------------- | --------- | ------------------------------------------------------------- |
| **textStyle**     | TextStyle | The text style to be applied to mentions                      |
| **selfTextStyle** | TextStyle | The text style to be applied to the logged-in user's mentions |

<Tabs>
  <Tab title="TypeScript">
    ```tsx lines theme={null}

    import React from "react";
    import { CometChat } from '@cometchat/chat-sdk-react-native';
    import { CometChatMessageList, CometChatMentionsFormatter, TextStyle, MentionTextStyle } from '@cometchat/chat-uikit-react-native';

    function App(): React.JSX.Element {
        const [chatUser, setChatUser] = React.useState<CometChat.User| undefined>();

        React.useEffect(() => {
            CometChat.getUser("uid").then((user) => {
                setChatUser(user);
            })
        }, []);

        const mentionsFormatter = new CometChatMentionsFormatter();

        const selfTextStyle : TextStyle = {
          color: "red",
          fontWeight: "bold"
        }

        const otherUsersStyle :TextStyle  = {
          color: "red",
        }

        const mentiontextStyle : MentionTextStyle = {
          selfTextStyle: selfTextStyle,
          textStyle: otherUsersStyle
        }

      mentionsFormatter.setMentionsStyle(mentiontextStyle);

        return (
         <>
            { chatUser && <CometChatMessageList
                 user={chatUser}
                 textFormatters={[mentionsFormatter]}
            />}
         </>
       );
      }
    ```
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup>
  <Card title="ShortCut Formatter" icon="keyboard" href="/ui-kit/react-native/shortcut-formatter-guide">
    Create custom text shortcuts for quick message composition
  </Card>

  <Card title="URL Formatter" icon="link" href="/ui-kit/react-native/url-formatter-guide">
    Auto-detect and style URLs as clickable links
  </Card>

  <Card title="All Guides" icon="book" href="/ui-kit/react-native/guide-overview">
    Browse all feature and formatter guides
  </Card>

  <Card title="Message List" icon="list" href="/ui-kit/react-native/message-list">
    Customize how messages are displayed
  </Card>
</CardGroup>


# Message Bubble Styling
Source: https://www.cometchat.com/docs/ui-kit/react-native/message-bubble-styling

Customize CometChat React Native UI Kit message bubbles for text, image, video, audio, file, poll, and other message types.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                                                                     |
  | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Goal             | Customize incoming/outgoing message bubble appearance                                                                                                                     |
  | Provider         | `CometChatThemeProvider` — pass bubble styles in `theme.messageListStyles`                                                                                                |
  | Import           | `import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";`                                                                                            |
  | Incoming bubbles | `messageListStyles: { incomingMessageBubbleStyles: { containerStyle: { backgroundColor: "#FEEDE1" } } }`                                                                  |
  | Outgoing bubbles | `messageListStyles: { outgoingMessageBubbleStyles: { containerStyle: { backgroundColor: "#F76808" } } }`                                                                  |
  | Bubble types     | `textBubbleStyles`, `imageBubbleStyles`, `videoBubbleStyles`, `audioBubbleStyles`, `fileBubbleStyles`, `pollBubbleStyles`, `stickerBubbleStyles`, `assistantBubbleStyles` |
  | Special bubbles  | `deletedBubbleStyles`, `collaborativeBubbleStyles`, `groupCallBubbleStyles`, `linkPreviewBubbleStyles`                                                                    |
  | Action bubbles   | `groupActionBubbleStyles`, `callActionBubbleStyles`, `userCallBubbleStyles`                                                                                               |
  | Precedence       | Specific bubble style > Container style > Default (deep merge)                                                                                                            |
  | Source           | [GitHub theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts)                                          |
</Accordion>

Customize message bubble appearance by passing bubble styles in `theme.messageListStyles`.

<Warning>
  Prerequisites:

  1. Wrap your app with `CometChatThemeProvider`
  2. Bubble styles are passed via `theme={{ light: { messageListStyles: { ... } } }}`
  3. Specific bubble type styles (e.g., `textBubbleStyles`) override general `containerStyle`
</Warning>

***

## Bubble Style Keys

| Bubble Type   | Style Key                     | Common Properties                                                       |
| ------------- | ----------------------------- | ----------------------------------------------------------------------- |
| All incoming  | `incomingMessageBubbleStyles` | `containerStyle`, `avatarStyle`, `receiptStyles`, `reactionStyles`      |
| All outgoing  | `outgoingMessageBubbleStyles` | `containerStyle`, `avatarStyle`, `receiptStyles`, `reactionStyles`      |
| Text          | `textBubbleStyles`            | `containerStyle`, `textStyle`, `mentionsStyle`                          |
| AI Assistant  | `assistantBubbleStyles`       | `containerStyle`, `textStyle`, `copyButtonStyle`, `errorContainerStyle` |
| Image         | `imageBubbleStyles`           | `containerStyle`, `imageStyle`                                          |
| Video         | `videoBubbleStyles`           | `containerStyle`, `playIconStyle`, `playIconContainerStyle`             |
| Audio         | `audioBubbleStyles`           | `containerStyle`, `playIconStyle`, `waveStyle`                          |
| File          | `fileBubbleStyles`            | `containerStyle`, `titleStyle`, `subtitleStyle`, `downloadIconStyle`    |
| Sticker       | `stickerBubbleStyles`         | `containerStyle`, `imageStyle`                                          |
| Poll          | `pollBubbleStyles`            | `containerStyle`, `progressBarStyle`, `selectedIconStyle`, `titleStyle` |
| Link Preview  | `linkPreviewBubbleStyles`     | `containerStyle`, `bodyStyle`, `headerImageContainerStyle`              |
| Collaborative | `collaborativeBubbleStyles`   | `containerStyle`, `iconStyle`, `buttonTextStyle`, `dividerStyle`        |
| Meet Call     | `meetCallBubbleStyles`        | `containerStyle`, `iconStyle`, `dividerStyle`                           |
| Deleted       | `deletedBubbleStyles`         | `containerStyle`, `icon`                                                |
| Group Action  | `groupActionBubbleStyles`     | `containerStyle`, `textStyle`                                           |
| Call Action   | `callActionBubbleStyles`      | `containerStyle`, `textStyle`, `iconStyle`, `missedCallContainerStyle`  |

***

## Overview

Message bubbles are the core visual element in chat applications, encapsulating different types of messages like text, images, or attachments. Customizing message bubbles allows developers to create a consistent and engaging user experience that aligns with their app's theme and design language. This guide provides an overview of how to style outgoing and incoming message bubbles and customize the appearance for specific message types.

<Frame>
  <img />
</Frame>

### Types for Incoming and Outgoing Bubble Style

Incoming bubbles represent messages received from other users.

```ts theme={null}
import {
  ImageStyle,
  TextStyle,
  ViewStyle,
  //...
} from "react-native";

type BubbleStyles = {
  /**common bubble Style attributes for all message types**/
  containerStyle: ViewStyle;
  threadedMessageStyles: DeepPartial<CometChatTheme["threadedMessageStyles"]>;
  avatarStyles: DeepPartial<CometChatTheme["avatarStyles"]>;
  receiptStyles: DeepPartial<CometChatTheme["receiptStyles"]>;
  reactionStyles: DeepPartial<CometChatTheme["messageBubbleReactionStyles"]>;
  dateStyles: DeepPartial<CometChatTheme["dateStyles"]>;
  dateReceiptContainerStyle: ViewStyle;
  senderNameTextStyles: TextStyle;

  /**The above common properties are available for the below individual bubble styles as well**/
  textBubbleStyles?: DeepPartial<CometChatTheme["textBubbleStyles"]>;
  imageBubbleStyles?: DeepPartial<CometChatTheme["imageBubbleStyles"]>;
  videoBubbleStyles?: DeepPartial<CometChatTheme["videoBubbleStyles"]>;
  audioBubbleStyles?: DeepPartial<CometChatTheme["audioBubbleStyles"]>;
  deletedBubbleStyles?: DeepPartial<CometChatTheme["deletedBubbleStyles"]>;
  fileBubbleStyles?: DeepPartial<CometChatTheme["fileBubbleStyles"]>;
  collaborativeBubbleStyles?: DeepPartial<
    CometChatTheme["collaborativeBubbleStyles"]
  >;
  groupCallBubbleStyles?: DeepPartial<CometChatTheme["groupCallBubbleStyles"]>;
  stickerBubbleStyles?: DeepPartial<CometChatTheme["stickerBubbleStyles"]>;
  pollBubbleStyles?: DeepPartial<CometChatTheme["pollBubbleStyles"]>;
  linkPreviewBubbleStyles?: DeepPartial<
    CometChatTheme["linkPreviewBubbleStyles"]
  >;
};

type UserCallBubbleStyles = {
  containerStyle: ViewStyle;
  textStyle: TextStyle;
  iconStyle: ImageStyle;
};

interface CometChatTheme {
  groupActionBubbleStyles: {
    containerStyle: ViewStyle;
    textStyle: TextStyle;
    textContainerStyle?: ViewStyle;
  };
  messageListStyles: {
    incomingMessageBubbleStyles: DeepPartial<BubbleStyles>;
    outgoingMessageBubbleStyles: DeepPartial<BubbleStyles>;
    /** style for group action bubbles **/
    groupActionBubbleStyles: DeepPartial<
      CometChatTheme["groupActionBubbleStyles"]
    >;
    /** style for one to one calling bubbles **/
    userCallBubbleStyles: DeepPartial<UserCallBubbleStyles>;
    //other style properties for message list
  };
}
```

<Note>
  * `DeepPartial` is an internal utility that ensures all style properties are optional, allowing only the required fields to be overridden.
  * When customizing theme properties, whether by overriding specific properties or supplying a completely custom theme, the provided values will be deeply merged with the default theme. This means that only the specified properties will be overridden, while all other properties will retain their default values. Additionally, if a style is passed through props, it will take priority over the style provided via the theme.
</Note>

In the code snippet below, incoming text message bubbles will have a background color of `#f90ac6`, while all other incoming message bubbles will have `#f90a4e`. The `paddingHorizontal` value set in `incomingMessageBubbleStyles.containerStyle` will also apply to all incoming message bubbles, unless explicitly overridden for a specific bubble type. For instance, you can set `incomingMessageBubbleStyles.textBubbleStyles.containerStyle.paddingHorizontal` to `0` if you want to remove horizontal padding for text bubbles.

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      dark: {
        messageListStyles: {
          incomingMessageBubbleStyles: {
            //will apply to all the incoming bubble types
            containerStyle: {
              backgroundColor: "#f90a4e",
              paddingHorizontal: 20,
            },
            textBubbleStyles: {
              //will be merged with the container style above.
              //{paddingHorizontal: 20} will be applied unless overriden here
              containerStyle: {
                backgroundColor: "#f90ac6",
              },
            },
          },
        },
      },
    }}
  ></CometChatThemeProvider>
);
```

## Message Bubbles

Message bubbles are core elements of the messaging interface. Their collective appearance can be customized to create a consistent design, including color, shape, and overall style for both outgoing and incoming messages. The message bubbles' styles can be customized by extending the predefined styles in your theme.

**Customizing Incoming Message Bubble**

<Frame>
  <img />
</Frame>

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        messageListStyles: {
          incomingMessageBubbleStyles: {
            //will apply to all the incoming message bubbles
            containerStyle: {
              backgroundColor: "#F76808",
            },
          },
        },
      },
    }}
  ></CometChatThemeProvider>
);
```

**Customizing Outgoing Message Bubble**

<Frame>
  <img />
</Frame>

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        messageListStyles: {
          outgoingMessageBubbleStyles: {
            //will apply to all the outgoing message bubbles
            containerStyle: {
              backgroundColor: "#F76808",
            },
          },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Text Bubble

Text bubbles display plain text messages. These are the most common bubble type in a chat interface.

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

**Customizing Incoming and Outgoing Bubbles**

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        messageListStyles: {
          incomingMessageBubbleStyles: {
            textBubbleStyles: {
              containerStyle: {
                backgroundColor: "#FEEDE1",
              },
            },
          },
          outgoingMessageBubbleStyles: {
            textBubbleStyles: {
              containerStyle: {
                backgroundColor: "#F76808",
              },
            },
          },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Link Preview Bubble

The Link Preview Bubble is designed to display a preview of links shared in messages. It enriches the messaging experience by showing details such as the page title, description, and an image from the linked content, making links more engaging and informative.

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

**Customizing Incoming and Outgoing Bubble**

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        messageListStyles: {
          outgoingMessageBubbleStyles: {
            linkPreviewBubbleStyles: {
              containerStyle: {
                backgroundColor: "#F76808",
              },
              bodyStyle: {
                containerStyle: {
                  backgroundColor: "#FBAA75",
                },
              },
              headerImageContainerStyle: {
                backgroundColor: "#FBAA75",
              },
            },
          },
          incomingMessageBubbleStyles: {
            linkPreviewBubbleStyles: {
              containerStyle: {
                backgroundColor: "#FEEDE1",
              },
              bodyStyle: {
                containerStyle: {
                  backgroundColor: "#FBAA75",
                },
              },
              headerImageContainerStyle: {
                backgroundColor: "#FBAA75",
              },
            },
          },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Image Bubble

`CometChatImagesBubble` renders a message's image attachments as a grid inside a single bubble. When there are more images than visible cells, the last cell shows a **`+N`** overflow overlay; tapping any cell opens the full-screen viewer, and an optional caption renders below the grid.

<Frame>
  <img />
</Frame>

**Styling**

Style the bubble globally through the `mediaGridBubbleStyles` theme key:

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        mediaGridBubbleStyles: {
          cellStyle: { borderRadius: 12 },
          overflowTextStyle: { fontSize: 28 },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Video Bubble

`CometChatVideosBubble` renders a message's video attachments as a thumbnail grid — each cell showing a poster with a centered play overlay and a duration chip, plus a **`+N`** overflow overlay when there are more videos than visible cells. Tapping a cell opens full-screen playback.

<Frame>
  <img />
</Frame>

**Styling**

`CometChatVideosBubble` shares the `mediaGridBubbleStyles` theme key with the image grid:

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        mediaGridBubbleStyles: {
          durationChipStyle: { borderRadius: 6 },
          playButtonStyle: { opacity: 0.9 },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Audio Bubble

`CometChatAudiosBubble` renders a message's audio **file** attachments as stacked playback cards — each with play/pause, a draggable seek bar, elapsed/total time, and download. Past 3 attachments the rest collapse behind a "Show *N* more" toggle. Recorded voice notes render separately as a voice-note bubble with a waveform player.

<Frame>
  <img />
</Frame>

**Styling**

Style the bubble globally through the `audiosBubbleStyles` theme key:

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        audiosBubbleStyles: {
          seekProgressStyle: { backgroundColor: "#6852D6" },
          fileNameStyle: { fontWeight: "600" },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### File Bubble

`CometChatFilesBubble` renders a message's document attachments as a vertical list of downloadable cards — each with a per-type icon, file name, and size. Past 3 files the rest collapse behind a "Show *N* more" toggle, and an optional caption renders below.

<Frame>
  <img />
</Frame>

**Styling**

Style the bubble globally through the `filesBubbleStyles` theme key:

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        filesBubbleStyles: {
          expandButtonTextStyle: { fontWeight: "600" },
          fileNameStyle: { fontWeight: "600" },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Sticker Bubble

Sticker bubbles display stickers shared in a conversation, enhancing visual expression.

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

**Customizing Incoming and Outgoing Bubble**

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        messageListStyles: {
          incomingMessageBubbleStyles: {
            stickerBubbleStyles: {
              containerStyle: {
                backgroundColor: "#FEEDE1",
              },
            },
          },
          outgoingMessageBubbleStyles: {
            stickerBubbleStyles: {
              containerStyle: {
                backgroundColor: "#F76808",
              },
            },
          },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Poll Bubble

Poll bubbles represent polls shared within the chat, showing options and results.

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

**Customizing Incoming and Outgoing Bubble**

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        messageListStyles: {
          incomingMessageBubbleStyles: {
            pollBubbleStyles: {
              containerStyle: {
                backgroundColor: "#FEEDE1",
              },
              activeProgressBarTint: "#F76808",
            },
          },
          outgoingMessageBubbleStyles: {
            pollBubbleStyles: {
              containerStyle: {
                backgroundColor: "#F76808",
              },
              progressBarStyle: {
                backgroundColor: "#FBAA75",
              },
              selectedIconStyle: {
                tintColor: "#F76808",
              },
            },
          },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Collaborative Bubble

Collaborative bubbles display collaborative content, such as shared documents or tasks.

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

**Customizing Incoming and Outgoing Bubble**

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        typography: {
          heading4: {
            bold: {
              fontFamily: "TimesNewRoman-Bold",
            },
            medium: {
              fontFamily: "TimesNewRoman",
            },
            regular: {
              fontFamily: "TimesNewRoman",
            },
          },
        },
        messageListStyles: {
          incomingMessageBubbleStyles: {
            collaborativeBubbleStyles: {
              containerStyle: {
                backgroundColor: "#FEEDE1",
              },
              iconStyle: {
                tintColor: "#F76808",
              },
              buttonTextStyle: {
                color: "#F76808",
              },
            },
          },
          outgoingMessageBubbleStyles: {
            collaborativeBubbleStyles: {
              containerStyle: {
                backgroundColor: "#F76808",
              },
              dividerStyle: {
                backgroundColor: "#FBAA75",
              },
            },
          },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Meet Call Bubble

Meet call bubbles display call-related actions and statuses in the chat interface.

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

**Customizing Incoming and Outgoing Bubble**

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        typography: {
          button: {
            medium: {
              fontFamily: "TimesNewRoman",
            },
          },
        },
        messageListStyles: {
          incomingMessageBubbleStyles: {
            meetCallBubbleStyles: {
              containerStyle: {
                backgroundColor: "#FEEDE1",
              },
              iconStyle: {
                tintColor: "#F76808",
              },
              buttonTextStyle: {
                color: "#F76808",
              },
            },
          },
          outgoingMessageBubbleStyles: {
            meetCallBubbleStyles: {
              containerStyle: {
                backgroundColor: "#F76808",
              },
              iconStyle: {
                tintColor: "#F76808",
              },
              dividerStyle: {
                backgroundColor: "#FBAA75",
              },
            },
          },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Delete Bubble

Delete bubbles are used to display messages that have been deleted by the sender. These indicate the message removal within the chat interface.

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

**Customizing Incoming and Outgoing Bubble**

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        messageListStyles: {
          incomingMessageBubbleStyles: {
            deletedBubbleStyles: {
              containerStyle: {
                backgroundColor: "#FEEDE1",
              },
              icon: { uri: "url-to-icon" },
            },
          },
          outgoingMessageBubbleStyles: {
            deletedBubbleStyles: {
              containerStyle: {
                backgroundColor: "#F76808",
              },
              icon: { uri: "url-to-icon" },
            },
          },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Call Action Bubble

Call action bubbles display call-related actions, such as missed calls, in the chat interface.

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

**Customizing Bubble**

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        messageListStyles: {
          callActionBubbleStyles: {
            containerStyle: {
              backgroundColor: "#FEEDE1",
              borderWidth: 1,
              borderColor: "#F76808",
            },
            textStyle: {
              color: "#F76808",
            },
            iconStyle: {
              tintColor: "#F76808",
            },
            missedCallContainerStyle: {
              backgroundColor: "#FEEDE1",
              borderWidth: 1,
              borderColor: "#F76808",
            },
            missedCallTextStyle: {
              color: "#F76808",
            },
            missedCallIconStyle: {
              tintColor: "#F76808",
            },
          },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### Action Bubble

Action bubbles provide a customizable interface for displaying a variety of actions, such as group actions, within a chat.

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

**Customizing Bubble**

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        messageListStyles: {
          groupActionBubbleStyles: {
            containerStyle: {
              backgroundColor: "#FEEDE1",
              borderWidth: 1,
              borderColor: "#F76808",
            },
            textStyle: {
              color: "#F76808",
            },
          },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

### AI Assistant Bubble

AI Assistant bubbles display messages and interactions from an AI assistant within the chat interface.

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

**Customizing Bubble**

```tsx theme={null}
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

//other code
return (
  <CometChatThemeProvider
    theme={{
      light: {
        messageListStyles: {
          incomingMessageBubbleStyles: {
            assistantBubbleStyles: {
              containerStyle: {
                backgroundColor: "transparent",
              },
              textStyle: {
                color: "#F76808",
              },
              placeholderTextStyle: {
                color: "#F76808",
                opacity: 0.6,
              },
              copyButtonStyle: {
                backgroundColor: "#F76808",
              },
              errorContainerStyle: {
                backgroundColor: "#FEEDE1",
                borderWidth: 1,
                borderColor: "#F76808",
              },
              errorTextStyle: {
                color: "#F76808",
              },
            },
          },
        },
      },
    }}
  >
    {/*your component*/}
  </CometChatThemeProvider>
);
```

To learn more about such attributes, refer to the [theme interface](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts).

***

## Next Steps

<CardGroup>
  <Card title="Introduction to Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Learn how CometChatThemeProvider manages light and dark modes
  </Card>

  <Card title="Colors" icon="palette" href="/ui-kit/react-native/colors">
    Customize primary, neutral, alert, and other color tokens
  </Card>

  <Card title="Component Styling" icon="sliders" href="/ui-kit/react-native/component-styling">
    Style individual UI Kit components like Conversations and Users
  </Card>

  <Card title="Message List" icon="list" href="/ui-kit/react-native/message-list">
    Explore the Message List component and its customization options
  </Card>
</CardGroup>


# Message Composer
Source: https://www.cometchat.com/docs/ui-kit/react-native/message-composer

Compose and send messages including text, media, and attachments with CometChatMessageComposer component in React Native UI Kit.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatMessageComposer",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatMessageComposer } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Rich text input for composing and sending text, media, attachments, mentions, voice notes, and custom messages.",
    "primaryOutput": {
      "prop": "onSendButtonPress",
      "type": "(message: CometChat.BaseMessage) => void"
    },
    "props": {
      "data": {
        "user": { "type": "CometChat.User", "default": "undefined" },
        "group": { "type": "CometChat.Group", "default": "undefined" },
        "parentMessageId": { "type": "number", "default": "undefined" },
        "initialComposertext": { "type": "string", "default": "\"\"" }
      },
      "callbacks": {
        "onSendButtonPress": "(message: CometChat.BaseMessage) => void",
        "onTextChange": "(text: string) => void",
        "onError": "(error: CometChat.CometChatException) => void"
      },
      "visibility": {
        "hideVoiceRecordingButton": { "type": "boolean", "default": false },
        "hideCameraOption": { "type": "boolean", "default": false },
        "hideImageAttachmentOption": { "type": "boolean", "default": false },
        "hideVideoAttachmentOption": { "type": "boolean", "default": false },
        "hideAudioAttachmentOption": { "type": "boolean", "default": false },
        "hideFileAttachmentOption": { "type": "boolean", "default": false },
        "hidePollsAttachmentOption": { "type": "boolean", "default": false },
        "hideCollaborativeDocumentOption": { "type": "boolean", "default": false },
        "hideCollaborativeWhiteboardOption": { "type": "boolean", "default": false },
        "hideAttachmentButton": { "type": "boolean", "default": false },
        "hideStickersButton": { "type": "boolean", "default": false },
        "hideSendButton": { "type": "boolean", "default": false },
        "hideAuxiliaryButtons": { "type": "boolean", "default": false }
      },
      "configuration": {
        "imageQuality": { "type": "number (1-100)", "default": 20 },
        "auxiliaryButtonsAlignment": { "type": "\"left\" | \"right\"", "default": "\"left\"" }
      },
      "sound": {
        "disableSoundForOutgoingMessages": { "type": "boolean", "default": false },
        "customSoundForOutgoingMessage": { "type": "audio source", "default": "built-in" }
      },
      "behavior": {
        "disableTypingEvents": { "type": "boolean", "default": false },
        "disableMentions": { "type": "boolean", "default": false },
        "disableMentionAll": { "type": "boolean", "default": false },
        "mentionAllLabel": { "type": "string", "default": "\"all\"" }
      },
      "viewSlots": {
        "HeaderView": "({ user, group }: { user?: CometChat.User, group?: CometChat.Group }) => JSX.Element",
        "AuxiliaryButtonView": "({ user, group, composerId }: { user?: CometChat.User, group?: CometChat.Group, composerId: string | number }) => JSX.Element",
        "SendButtonView": "({ user, group, composerId }: { user?: CometChat.User, group?: CometChat.Group, composerId: string | number }) => JSX.Element"
      },
      "formatting": {
        "textFormatters": {
          "type": "CometChatTextFormatter[]",
          "default": "default formatters from data source"
        },
        "attachmentOptions": {
          "type": "CometChatMessageComposerAction[]",
          "note": "Custom attachment options list"
        },
        "addAttachmentOptions": {
          "type": "CometChatMessageComposerAction[]",
          "note": "Additional attachment options to append to defaults"
        },
        "enableMultipleAttachments": {
          "type": "boolean",
          "default": true,
          "note": "Enable the multi-attachment staging tray and batched send. Set false for legacy single-select, send-immediately behavior."
        }
      }
    },
    "events": [
      {
        "name": "ccMessageSent",
        "payload": "{ message: CometChat.BaseMessage, status: string }",
        "description": "Triggers when a message is sent with status: inprogress, success, or error"
      },
      {
        "name": "ccMessageEdited",
        "payload": "{ message: CometChat.BaseMessage, status: string }",
        "description": "Triggers when a message is edited with status: inprogress, success, or error"
      },
      {
        "name": "ccMessageLiveReaction",
        "payload": "object",
        "description": "Triggers when user clicks on live reaction"
      }
    ],
    "compositionExample": {
      "description": "Message composer wired with message header and list for complete chat view",
      "components": [
        "CometChatMessageHeader",
        "CometChatMessageList",
        "CometChatMessageComposer"
      ],
      "flow": "Pass user or group prop to composer -> onSendButtonPress fires with CometChat.BaseMessage -> message appears in MessageList"
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatMessageComposer` is a [Component](/docs/ui-kit/react-native/components-overview#components) that enables users to write and send a variety of messages, including text, image, video, and custom messages. Features such as **Live Reaction**, **Attachments**, and **Message Editing** are also supported.

Wire it alongside `CometChatMessageHeader` and `CometChatMessageList` to build a standard chat view.

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react-native";

function MessageComposerDemo() {
  return <CometChatMessageComposer group={group} />;
}

export default MessageComposerDemo;
```

***

## Multi-Attachment Staging Tray

When `enableMultipleAttachments` is `true` (the default), picking files does **not** send them immediately. Files are **staged in a tray** below the input, uploaded in the background, and sent together when the user taps send:

1. **Pick** — choose one or more files from the attachment (`+`) menu. In [`CometChatCompactMessageComposer`](/docs/ui-kit/react-native/compact-message-composer), images and files copied to the clipboard can also be pasted straight into the composer — they stage into the tray as tiles, just like a pick (subject to the same count and size limits).
2. **Stage & upload** — each file becomes a tile in the tray and starts uploading right away with its own progress. The user can keep typing or add more files while uploads run. The voice-recording button hides while attachments are staged.
3. **Review** — remove any tile, or retry one whose upload failed. Tapping a rejected tile shows *why* it was rejected (as a toast).
4. **Send** — the staged files fan out into media messages that share a single batch, and the [message list](/docs/ui-kit/react-native/message-list#multi-attachment-batch-grouping) renders them as one connected group of [plural bubbles](/docs/ui-kit/react-native/message-bubble-styling#image-bubble).

### Tray tile states

| State       | Meaning                                         | Tile UI                                                | Retryable |
| ----------- | ----------------------------------------------- | ------------------------------------------------------ | --------- |
| `UPLOADING` | Bytes are transferring                          | Progress overlay with percentage                       | —         |
| `COMPLETED` | Uploaded, ready to send                         | Thumbnail (image/video first frame) or file/audio card | —         |
| `FAILED`    | Transfer failed (transient — e.g. network drop) | Retry control on the tile                              | Yes       |
| `REJECTED`  | File not accepted (see below)                   | Rejected marker; tap for the reason                    | No        |

**Failed** uploads are transient and can be retried; **rejected** files must be swapped out.

### Attachment limits

* **Count** — a batch holds up to a server-configured maximum (default **10**, from the `file.count.max` app setting, resolved at runtime). The limit is **all-or-nothing**: if a pick would push the tray past the maximum, the **entire new selection is rejected** — nothing is staged — and a toast explains the limit. Already-staged files are untouched.
* **Per-file size** — a file larger than the allowed size (`file.size.max`) is rejected as an individual tile; tapping the tile shows the size limit.

### Batch send

On send, staged files are grouped by media kind and sent as **one media message per kind**, in a fixed order — **Images → Videos → Audios → Files** — all sharing a single `batchId`. The caption goes on the **last** message of the batch. The message list groups messages with the same `batchId` and renders them as one visually connected set.

### Disabling the tray

Set `enableMultipleAttachments={false}` to revert to legacy single-select, send-immediately behavior — each attachment option sends one file straight away, with no staging tray. Pass the same value to [`CometChatMessageList`](/docs/ui-kit/react-native/message-list) so rendering matches.

***

## Actions and Events

### Callback Props

#### onSendButtonPress

Fires when the send message button is clicked. Overrides the default send behavior.

```tsx lines theme={null}
onSendButtonPress?: (message: CometChat.BaseMessage) => void
```

```tsx lines theme={null}
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ComposerWithCustomSend() {
  const onSendButtonPressHandler = (message: CometChat.BaseMessage) => {
    console.log("Custom send:", message);
  };

  return (
    <CometChatMessageComposer
      group={group}
      onSendButtonPress={onSendButtonPressHandler}
    />
  );
}
```

#### onError

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

```tsx lines theme={null}
onError?: (error: CometChat.CometChatException) => void
```

```tsx lines theme={null}
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ComposerWithErrorHandler() {
  return (
    <CometChatMessageComposer
      group={group}
      onError={(error: CometChat.CometChatException) => {
        console.error("Composer error:", error);
      }}
    />
  );
}
```

#### onTextChange

Fires as the user types in the composer input.

```tsx lines theme={null}
onTextChange?: (text: string) => void
```

```tsx lines theme={null}
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react-native";

function ComposerWithTextTracking() {
  return (
    <CometChatMessageComposer
      group={group}
      onTextChange={(text: string) => {
        console.log("Text changed:", text);
      }}
    />
  );
}
```

### Global UI Events

`CometChatUIEventHandler` emits events subscribable from anywhere in the application. Add listeners and remove them on cleanup.

| Event                   | Fires when                   | Payload                                              |
| ----------------------- | ---------------------------- | ---------------------------------------------------- |
| `ccMessageSent`         | A message is sent            | `{ message: CometChat.BaseMessage, status: string }` |
| `ccMessageEdited`       | A message is edited          | `{ message: CometChat.BaseMessage, status: string }` |
| `ccMessageLiveReaction` | User clicks on live reaction | `object`                                             |

When to use: sync external UI with message state changes. For example, update a notification badge when messages are sent, or trigger analytics when a message is edited.

```tsx lines theme={null}
import { useEffect } from "react";
import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";

function useComposerEvents() {
  useEffect(() => {
    const listenerId = "MESSAGE_COMPOSER_EVENTS_" + Date.now();

    CometChatUIEventHandler.addMessageListener(listenerId, {
      ccMessageSent: (item) => {
        console.log("Message sent:", item);
      },
      ccMessageEdited: (item) => {
        console.log("Message edited:", item);
      },
      ccMessageLiveReaction: (item) => {
        console.log("Live reaction:", item);
      },
    });

    return () => {
      CometChatUIEventHandler.removeMessageListener(listenerId);
    };
  }, []);
}
```

<Note>
  In React 18 StrictMode, `useEffect` runs twice on mount in development. The component handles listener cleanup internally, but any additional listeners added alongside the component need cleanup in the `useEffect` return function to avoid duplicate event handling.
</Note>

***

## Custom View Slots

Each slot replaces a section of the default UI. Slots that accept parameters receive the relevant data for customization.

| Slot                  | Signature                                      | Replaces                        |
| --------------------- | ---------------------------------------------- | ------------------------------- |
| `HeaderView`          | `({ user, group }) => JSX.Element`             | Area above the composer input   |
| `AuxiliaryButtonView` | `({ user, group, composerId }) => JSX.Element` | Sticker button area             |
| `SendButtonView`      | `({ user, group, composerId }) => JSX.Element` | Send button                     |
| `attachmentOptions`   | `CometChatMessageComposerAction[]`             | Default attachment options list |
| `textFormatters`      | `CometChatTextFormatter[]`                     | Text formatting in composer     |

### textFormatters

Custom text formatters for the composer input. To configure the existing Mentions look and feel check out [CometChatMentionsFormatter](/docs/ui-kit/react-native/mentions-formatter-guide).

```tsx lines theme={null}
import {
  CometChatMessageComposer,
  CometChatTextFormatter,
  CometChatMentionsFormatter,
} from "@cometchat/chat-uikit-react-native";

const getTextFormatters = () => {
  const textFormatters: CometChatTextFormatter[] = [];
  const mentionsFormatter = new CometChatMentionsFormatter();
  mentionsFormatter.setMentionsStyle({
    textStyle: { color: "#D6409F" },
    selfTextStyle: { color: "#30A46C" },
  });
  textFormatters.push(mentionsFormatter);
  return textFormatters;
};

return (
  <CometChatMessageComposer
    group={group}
    textFormatters={getTextFormatters()}
  />
);
```

<Frame>
  <img />
</Frame>

### attachmentOptions

Override the default attachment options with custom actions.

```tsx lines theme={null}
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const getCustomAttachmentOptions = ({
  user,
  group,
  composerId,
}: {
  user?: CometChat.User;
  group?: CometChat.Group;
  composerId: Map<any, any>;
}): CometChatMessageComposerAction[] => {
  return [
    {
      id: "location",
      icon: LocationIcon,
      title: "Share Location",
      style: { iconStyle: { tintColor: "grey" } },
      onPress: () => {
        // handle location share
      },
    },
  ];
};

return (
  <CometChatMessageComposer
    group={group}
    attachmentOptions={getCustomAttachmentOptions}
  />
);
```

<Frame>
  <img />
</Frame>

### addAttachmentOptions

Extends the default attachment options with additional actions.

```tsx lines theme={null}
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const getAdditionalAttachmentOptions = ({
  user,
  group,
  composerId,
}: {
  user?: CometChat.User;
  group?: CometChat.Group;
  composerId: Map<any, any>;
}): CometChatMessageComposerAction[] => {
  return [
    {
      id: "location",
      icon: LocationIcon,
      title: "Share Location",
      style: { iconStyle: { tintColor: "grey" } },
      onPress: () => {
        // handle location share
      },
    },
  ];
};

return (
  <CometChatMessageComposer
    group={group}
    addAttachmentOptions={getAdditionalAttachmentOptions}
  />
);
```

### AuxiliaryButtonView

Replace the sticker button area with a custom view.

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react-native";
import { TouchableOpacity, Image, StyleSheet } from "react-native";

const styles = StyleSheet.create({
  button: {
    height: 25,
    width: 25,
    borderRadius: 0,
    backgroundColor: "transparent",
  },
  image: {
    height: 23,
    width: 24,
    tintColor: "#7E57C2",
  },
});

const customAuxiliaryButtonView = ({
  user,
  group,
  composerId,
}: {
  user?: CometChat.User;
  group?: CometChat.Group;
  composerId: string | number;
}): JSX.Element => {
  return (
    <TouchableOpacity style={styles.button} onPress={() => {}}>
      <Image source={LocationIcon} style={styles.image} />
    </TouchableOpacity>
  );
};

return (
  <CometChatMessageComposer
    group={group}
    AuxiliaryButtonView={customAuxiliaryButtonView}
  />
);
```

<Note>
  The MessageComposer Component utilizes the AuxiliaryButton to provide sticker functionality. Overriding the AuxiliaryButton will replace the sticker functionality.
</Note>

<Frame>
  <img />
</Frame>

### SendButtonView

Replace the send button with a custom view.

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react-native";
import { TouchableOpacity, Image, StyleSheet } from "react-native";

const styles = StyleSheet.create({
  button: {
    height: 25,
    width: 25,
    borderRadius: 0,
    backgroundColor: "transparent",
  },
  image: {
    height: 23,
    width: 24,
    tintColor: "#7E57C2",
  },
});

const customSendButtonView = ({
  user,
  group,
  composerId,
}: {
  user?: CometChat.User;
  group?: CometChat.Group;
  composerId: string | number;
}): JSX.Element => {
  return (
    <TouchableOpacity style={styles.button} onPress={() => {}}>
      <Image source={SendButtonIcon} style={styles.image} />
    </TouchableOpacity>
  );
};

return (
  <CometChatMessageComposer
    group={group}
    SendButtonView={customSendButtonView}
  />
);
```

<Frame>
  <img />
</Frame>

### HeaderView

Custom view above the composer input.

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatMessageComposer } from "@cometchat/chat-uikit-react-native";
import { View, Text, StyleProp, ViewStyle } from "react-native";

const viewStyle: StyleProp<ViewStyle> = {
  flexDirection: "row",
  alignItems: "flex-start",
  justifyContent: "center",
  padding: 5,
  borderColor: "black",
  borderWidth: 1,
  backgroundColor: "white",
  borderRadius: 10,
  margin: 2,
  marginLeft: 7.4,
  height: 30,
  width: "95.5%",
};

const customHeaderView = ({
  user,
  group,
}: {
  user?: CometChat.User;
  group?: CometChat.Group;
}) => {
  return (
    <View style={viewStyle}>
      <Text style={{ color: "#6851D6", fontWeight: "bold" }}>Chat Bot</Text>
    </View>
  );
};

return (
  <CometChatMessageComposer
    group={group}
    HeaderView={customHeaderView}
  />
);
```

<Frame>
  <img />
</Frame>

***

## Styling

Using Style you can customize the look and feel of the component in your app. These parameters typically control elements such as the color, size, shape, and fonts used within the component.

<Frame>
  <img />
</Frame>

### Visibility Props

| Property                            | Description                                                                                                          | Code                                         |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `user`                              | User object for 1-on-1 conversation                                                                                  | `user={chatUser}`                            |
| `group`                             | Group object for group conversation                                                                                  | `group={chatGroup}`                          |
| `disableTypingEvents`               | Disable/enable typing events                                                                                         | `disableTypingEvents={true}`                 |
| `disableSoundForOutgoingMessages`   | Toggle sound for outgoing messages                                                                                   | `disableSoundForOutgoingMessages={true}`     |
| `initialComposertext`               | Set predefined text                                                                                                  | `initialComposertext="Your custom text"`     |
| `customSoundForOutgoingMessage`     | Custom sound for outgoing messages                                                                                   | `customSoundForOutgoingMessage="your-sound"` |
| `hideVoiceRecordingButton`          | Hide voice recording option                                                                                          | `hideVoiceRecordingButton={true}`            |
| `enableMultipleAttachments`         | Multi-attachment staging tray and batched send (see [Multi-Attachment Staging Tray](#multi-attachment-staging-tray)) | `enableMultipleAttachments={false}`          |
| `hideCameraOption`                  | Hide camera option from attachments                                                                                  | `hideCameraOption={true}`                    |
| `hideImageAttachmentOption`         | Hide image attachment option                                                                                         | `hideImageAttachmentOption={true}`           |
| `hideVideoAttachmentOption`         | Hide video attachment option                                                                                         | `hideVideoAttachmentOption={true}`           |
| `hideAudioAttachmentOption`         | Hide audio attachment option                                                                                         | `hideAudioAttachmentOption={true}`           |
| `hideFileAttachmentOption`          | Hide file attachment option                                                                                          | `hideFileAttachmentOption={true}`            |
| `hidePollsAttachmentOption`         | Hide polls attachment option                                                                                         | `hidePollsAttachmentOption={true}`           |
| `hideCollaborativeDocumentOption`   | Hide collaborative document option                                                                                   | `hideCollaborativeDocumentOption={true}`     |
| `hideCollaborativeWhiteboardOption` | Hide collaborative whiteboard option                                                                                 | `hideCollaborativeWhiteboardOption={true}`   |
| `hideAttachmentButton`              | Hide attachment button                                                                                               | `hideAttachmentButton={true}`                |
| `hideStickersButton`                | Hide stickers button                                                                                                 | `hideStickersButton={true}`                  |
| `hideSendButton`                    | Hide send button                                                                                                     | `hideSendButton={true}`                      |
| `hideAuxiliaryButtons`              | Hide auxiliary buttons                                                                                               | `hideAuxiliaryButtons={true}`                |
| `disableMentions`                   | Disable mentions functionality                                                                                       | `disableMentions={true}`                     |
| `disableMentionAll`                 | Disable @all mention                                                                                                 | `disableMentionAll={true}`                   |
| `mentionAllLabel`                   | Custom label for @all mention                                                                                        | `mentionAllLabel="everyone"`                 |
| `imageQuality`                      | Image quality for camera (1-100)                                                                                     | `imageQuality={50}`                          |
| `auxiliaryButtonsAlignment`         | Alignment of auxiliary buttons                                                                                       | `auxiliaryButtonsAlignment="right"`          |

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="message" href="/ui-kit/react-native/message-list">
    Display the list of messages in a conversation
  </Card>

  <Card title="Message Header" icon="heading" href="/ui-kit/react-native/message-header">
    Display user or group details in the chat toolbar
  </Card>

  <Card title="Messages" icon="comments" href="/ui-kit/react-native/message-list">
    Complete messaging interface with header, list, and composer
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>


# Message Header
Source: https://www.cometchat.com/docs/ui-kit/react-native/message-header

Display user or group details in the chat toolbar with CometChatMessageHeader component in React Native UI Kit, including typing indicators and navigation.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatMessageHeader",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatMessageHeader } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Displays user or group details in the chat toolbar with typing indicators and navigation controls.",
    "props": {
      "data": {
        "user": {
          "type": "CometChat.User",
          "note": "User object for one-on-one chat header"
        },
        "group": {
          "type": "CometChat.Group",
          "note": "Group object for group chat header"
        }
      },
      "callbacks": {
        "onBack": "() => void",
        "onError": "(error: CometChat.CometChatException) => void",
        "onNewChatButtonClick": "() => void",
        "onChatHistoryButtonClick": "() => void"
      },
      "visibility": {
        "showBackButton": { "type": "boolean", "default": true },
        "hideVoiceCallButton": { "type": "boolean", "default": false },
        "hideVideoCallButton": { "type": "boolean", "default": false },
        "usersStatusVisibility": { "type": "boolean", "default": true },
        "hideNewChatButton": { "type": "boolean", "default": true },
        "hideChatHistoryButton": { "type": "boolean", "default": true }
      },
      "viewSlots": {
        "ItemView": "({ user, group }) => JSX.Element",
        "LeadingView": "({ user, group }) => JSX.Element",
        "TitleView": "({ user, group }) => JSX.Element",
        "SubtitleView": "({ user, group }) => JSX.Element",
        "TrailingView": "({ user, group }) => JSX.Element",
        "AuxiliaryButtonView": "({ user, group }) => JSX.Element"
      },
      "options": {
        "options": "({ user, group }) => MenuItemInterface[]"
      }
    },
    "compositionExample": {
      "description": "Header component for message view",
      "components": [
        "CometChatMessageHeader",
        "CometChatMessageList",
        "CometChatMessageComposer"
      ],
      "flow": "Displays user/group info at top of chat, handles back navigation and call buttons"
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatMessageHeader` is a [Component](/docs/ui-kit/react-native/components-overview#components) that showcases the [User](/docs/sdk/react-native/user-management) or [Group](/docs/sdk/react-native/retrieve-groups) details in the toolbar. It presents a typing indicator and a back navigation button for ease of use.

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
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).

```tsx lines theme={null}
onError?: (error: CometChat.CometChatException) => void
```

```tsx lines theme={null}
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}`.

```tsx lines theme={null}
onBack?: () => void
```

```tsx lines theme={null}
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.

```tsx lines theme={null}
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.

```tsx lines theme={null}
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.

```tsx lines theme={null}
TitleView?: ({ user, group }) => JSX.Element
```

```tsx lines theme={null}
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.

```tsx lines theme={null}
AuxiliaryButtonView?: ({ user, group }) => JSX.Element
```

```tsx lines theme={null}
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.

```tsx lines theme={null}
ItemView?: ({ user, group }) => JSX.Element
```

```tsx lines theme={null}
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.

```tsx lines theme={null}
SubtitleView?: ({ user, group }) => JSX.Element
```

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
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.

```tsx lines theme={null}
LeadingView?: ({ user, group }) => JSX.Element
```

```tsx lines theme={null}
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.

```tsx lines theme={null}
TrailingView?: ({ user, group }) => JSX.Element
```

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
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} />;
}
```

***

## 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.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
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` |

### options

Custom menu items for the header options menu.

```tsx lines theme={null}
options?: ({ user, group }) => MenuItemInterface[]
```

```tsx lines theme={null}
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

<CardGroup>
  <Card title="Message List" icon="message" href="/ui-kit/react-native/message-list">
    Display the list of messages in a conversation
  </Card>

  <Card title="Message Composer" icon="pen" href="/ui-kit/react-native/message-composer">
    Compose and send messages in a chat
  </Card>

  <Card title="Messages" icon="comments" href="/ui-kit/react-native/message-list">
    Complete messaging interface with header, list, and composer
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>


# Message List
Source: https://www.cometchat.com/docs/ui-kit/react-native/message-list

Display sent and received messages with text, media, reactions, read receipts, threaded replies, and AI features.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatMessageList",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatMessageList } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Scrollable list of sent and received messages with text, media, reactions, read receipts, threaded replies, and AI features.",
    "primaryOutput": {
      "prop": "onThreadRepliesPress",
      "type": "(messageObject: CometChat.BaseMessage, messageBubbleView: () => JSX.Element | null) => void"
    },
    "props": {
      "data": {
        "user": { "type": "CometChat.User", "default": "undefined", "note": "User object for 1-on-1 conversation" },
        "group": { "type": "CometChat.Group", "default": "undefined", "note": "Group object for group conversation" },
        "messageRequestBuilder": { "type": "CometChat.MessagesRequestBuilder", "default": "SDK default", "note": "UID/GUID/types/categories are always overridden internally" },
        "templates": { "type": "CometChatMessageTemplate[]", "default": "SDK defaults", "note": "Custom message bubble templates" },
        "addTemplates": { "type": "CometChatMessageTemplate[]", "default": "[]", "note": "Additional message templates to append to defaults" },
        "parentMessageId": { "type": "number", "default": "undefined", "note": "For threaded message view" },
        "goToMessageId": { "type": "string", "default": "undefined", "note": "Message ID to navigate to and highlight" },
        "searchKeyword": { "type": "string", "default": "undefined", "note": "Keyword to highlight in message text" }
      },
      "callbacks": {
        "onThreadRepliesPress": "(messageObject: CometChat.BaseMessage, messageBubbleView: () => JSX.Element | null) => void",
        "onError": "(error: CometChat.CometChatException) => void",
        "onReactionPress": "(reaction: CometChat.ReactionCount, messageObject: CometChat.BaseMessage) => void",
        "onReactionLongPress": "(reaction: CometChat.ReactionCount, messageObject: CometChat.BaseMessage) => void",
        "onReactionListItemPress": "(reaction: CometChat.Reaction, messageObject: CometChat.BaseMessage) => void",
        "onAddReactionPress": "() => void",
        "onSuggestedMessageClick": "(suggestion: string) => void",
        "onLoad": "(messageList: CometChat.BaseMessage[]) => void",
        "onEmpty": "() => void"
      },
      "visibility": {
        "receiptsVisibility": { "type": "boolean", "default": true },
        "avatarVisibility": { "type": "boolean", "default": true },
        "hideError": { "type": "boolean", "default": false },
        "hideTimestamp": { "type": "boolean", "default": false },
        "hideReplyOption": { "type": "boolean", "default": false },
        "hideReplyInThreadOption": { "type": "boolean", "default": false },
        "hideShareMessageOption": { "type": "boolean", "default": false },
        "hideEditMessageOption": { "type": "boolean", "default": false },
        "hideDeleteMessageOption": { "type": "boolean", "default": false },
        "hideTranslateMessageOption": { "type": "boolean", "default": false },
        "hideReactionOption": { "type": "boolean", "default": false },
        "hideMessagePrivatelyOption": { "type": "boolean", "default": false },
        "hideCopyMessageOption": { "type": "boolean", "default": false },
        "hideMessageInfoOption": { "type": "boolean", "default": false },
        "hideGroupActionMessages": { "type": "boolean", "default": false },
        "hideModerationStatus": { "type": "boolean", "default": false },
        "hideSuggestedMessages": { "type": "boolean", "default": false },
        "showMarkAsUnreadOption": { "type": "boolean", "default": false },
        "hideFlagMessageOption": { "type": "boolean", "default": false },
        "hideFlagRemarkField": { "type": "boolean", "default": false }
      },
      "behavior": {
        "alignment": { "type": "MessageListAlignmentType", "values": ["leftAligned", "standard"], "default": "standard" },
        "scrollToBottomOnNewMessage": { "type": "boolean", "default": false },
        "startFromUnreadMessages": { "type": "boolean", "default": false },
        "loadLastAgentConversation": { "type": "boolean", "default": false, "note": "Loads the most recent existing agent conversation on start" },
        "streamingSpeed": { "type": "number", "default": "undefined", "note": "AI response streaming speed in ms" },
        "enableMultipleAttachments": { "type": "boolean", "default": true, "note": "Enables multi-attachment batch grouping and the plural bubbles (Images/Videos/Audios/Files, Voice Note)" }
      },
      "sound": {
        "disableSoundForMessages": { "type": "boolean", "default": false },
        "customSoundForMessages": { "type": "audio source", "default": "built-in" }
      },
      "ai": {
        "suggestedMessages": { "type": "string[]", "note": "Predefined prompts for AI assistant chats" },
        "aiAssistantTools": { "type": "CometChatAIAssistantTools", "note": "Tool actions for AI assistant" },
        "quickReactionList": { "type": "string[]", "default": "predefined reactions" },
        "streamingSpeed": { "type": "number", "default": "undefined", "note": "AI response streaming speed in ms" }
      },
      "viewSlots": {
        "HeaderView": "({ user, group, id }) => JSX.Element",
        "FooterView": "({ user, group, id }) => JSX.Element",
        "LoadingView": "() => JSX.Element",
        "EmptyView": "() => JSX.Element",
        "ErrorView": "() => JSX.Element",
        "NewMessageIndicatorView": "() => JSX.Element",
        "emptyChatGreetingView": "JSX.Element",
        "emptyChatIntroMessageView": "JSX.Element",
        "emptyChatImageView": "JSX.Element"
      },
      "newMessageIndicator": {
        "newMessageIndicatorStyle": { "type": "NewMessageIndicatorStyle", "default": "built-in" },
        "newMessageIndicatorText": { "type": "string", "default": "built-in" }
      },
      "formatting": {
        "textFormatters": { "type": "CometChatTextFormatter[]", "default": "default formatters from data source" },
        "datePattern": "(message: CometChat.BaseMessage) => string",
        "dateSeperatorPattern": "(date: number) => string"
      }
    },
    "events": [
      { "name": "openChat", "payload": "{ user, group }", "description": "User opens a chat" },
      { "name": "ccMessageEdited", "payload": "{ message }", "description": "Message edited by logged-in user" },
      { "name": "ccMessageDeleted", "payload": "{ message }", "description": "Message deleted by logged-in user" },
      { "name": "ccActiveChatChanged", "payload": "chat details", "description": "User navigates to a different chat" },
      { "name": "ccMessageRead", "payload": "{ message }", "description": "Message read by logged-in user" },
      { "name": "ccMessageDelivered", "payload": "{ message }", "description": "Messages marked as delivered" }
    ],
    "sdkListeners": [
      "onTextMessageReceived", "onMediaMessageReceived", "onCustomMessageReceived",
      "onMessageEdited", "onMessageDeleted", "onTypingStarted", "onTypingEnded",
      "onMessagesDelivered", "onMessagesRead"
    ],
    "compositionExample": {
      "description": "Message list wired with header and composer for complete chat view",
      "components": ["CometChatMessageHeader", "CometChatMessageList", "CometChatMessageComposer"],
      "flow": "Pass user or group prop to all three components for a complete messaging interface"
    },
    "types": {
      "MessageListAlignmentType": { "leftAligned": "All messages aligned to left", "standard": "Sent messages right, received messages left" }
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatMessageList` renders a scrollable, real-time message feed for a user or group conversation. Wire it alongside `CometChatMessageHeader` and `CometChatMessageComposer` to build a standard chat view.

```tsx lines theme={null}
import { useState, useEffect } from "react";
import { View, StyleSheet } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { SafeAreaProvider } from "react-native-safe-area-context";
import {
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ChatView() {
  const [chatUser, setChatUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("uid").then((user) => setChatUser(user));
  }, []);

  return chatUser ? (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <SafeAreaProvider>
        <CometChatThemeProvider>
          <View style={styles.container}>
            <CometChatMessageHeader user={chatUser} />
            <CometChatMessageList user={chatUser} />
            <CometChatMessageComposer user={chatUser} />
          </View>
        </CometChatThemeProvider>
      </SafeAreaProvider>
    </GestureHandlerRootView>
  ) : null;
}

const styles = StyleSheet.create({
  container: { flex: 1 },
});
```

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";

function MessageListDemo() {
  return <CometChatMessageList user={chatUser} />;
}

export default MessageListDemo;
```

<Warning>
  Simply adding the `CometChatMessageList` component to the layout will result in an error. To fetch messages, you need to supplement it with `user` or `group` prop.
</Warning>

***

## Multi-Attachment Batch Grouping

When several attachments are sent together from the [composer's staging tray](/docs/ui-kit/react-native/message-composer#multi-attachment-staging-tray), they arrive as multiple media messages — one per media kind, in the fixed order **Images → Videos → Audios → Files** — that all share a single `batchId` in their metadata. The message list detects consecutive messages carrying the same `batchId` **from the same sender** and renders them as one visually connected group instead of separate, independently-chromed bubbles.

### Grouped chrome

Within a batch, the list renders shared chrome so the group reads as one logical message:

* The **avatar and sender name** render once, on the **first** message of the batch.
* **Delivery/read receipts** render once, on the **last** message of the batch.
* Interior spacing collapses so the bubbles sit tightly, reading as a single stack.
* The **caption** (if any) is carried by the last message of the batch.

This is computed automatically — you don't configure anything, and ordinary consecutive messages (without a `batchId`) are unaffected.

### What renders inside a batch

Each message in the batch is single-kind, so it renders the matching plural bubble — an image/video grid, a stacked audio-player list, or a connected file-card stack (see [Message Bubble Styling](/docs/ui-kit/react-native/message-bubble-styling)). Recorded voice notes are never batched with files — they render their own voice-note bubble.

Set [`enableMultipleAttachments`](#enablemultipleattachments) to `false` (together with the same prop on the composer) to disable multi-attachment rendering.

***

## Filtering Messages

Pass a `CometChat.MessagesRequestBuilder` to `messageRequestBuilder`. The `UID`/`GUID` parameters are always overridden internally based on the `user`/`group` prop.

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function FilteredMessageList() {
  return (
    <CometChatMessageList
      user={chatUser}
      messageRequestBuilder={
        new CometChat.MessagesRequestBuilder().setLimit(5)
      }
    />
  );
}
```

<Note>
  The following parameters in messageRequestBuilder will always be altered inside the message list:

  1. UID
  2. GUID
  3. types
  4. categories
</Note>

Refer to [MessagesRequestBuilder](/docs/sdk/react-native/additional-message-filtering) for the full builder API.

***

## Actions and Events

### Callback Props

#### onThreadRepliesPress

Fires when you press on the threaded message bubble.

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function MessageListWithThreads() {
  const handleThreadReplies = (
    msg: CometChat.BaseMessage,
    messageBubbleView: () => JSX.Element | null
  ) => {
    console.log("Thread replies pressed:", msg.getId());
  };

  return (
    <CometChatMessageList
      user={chatUser}
      onThreadRepliesPress={handleThreadReplies}
    />
  );
}
```

#### onError

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

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function MessageListWithErrorHandler() {
  return (
    <CometChatMessageList
      user={chatUser}
      onError={(error: CometChat.CometChatException) => {
        console.error("MessageList error:", error);
      }}
    />
  );
}
```

#### onReactionPress

Fires when a reaction on a message bubble is clicked.

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function MessageListWithReactions() {
  const handleReactionPress = (
    reaction: CometChat.ReactionCount,
    messageObject: CometChat.BaseMessage
  ) => {
    console.log("Reaction pressed:", reaction, messageObject.getId());
  };

  return (
    <CometChatMessageList
      user={chatUser}
      onReactionPress={handleReactionPress}
    />
  );
}
```

#### onLoad

Fires when messages are successfully fetched and loaded.

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function MessageListWithLoadHandler() {
  const handleLoad = (messageList: CometChat.BaseMessage[]) => {
    console.log("Messages loaded:", messageList.length);
  };

  return <CometChatMessageList user={chatUser} onLoad={handleLoad} />;
}
```

### Global UI Events

`CometChatUIEventHandler` emits events subscribable from anywhere in the application. Subscribe in a `useEffect` and unsubscribe on cleanup.

| Event                 | Fires when                         | Payload           |
| --------------------- | ---------------------------------- | ----------------- |
| `openChat`            | User opens a user or group chat    | `{ user, group }` |
| `ccMessageEdited`     | Message edited by logged-in user   | `{ message }`     |
| `ccMessageDeleted`    | Message deleted by logged-in user  | `{ message }`     |
| `ccActiveChatChanged` | User navigates to a different chat | `chat details`    |
| `ccMessageRead`       | Message read by logged-in user     | `{ message }`     |
| `ccMessageDelivered`  | Messages marked as delivered       | `{ message }`     |

```tsx lines theme={null}
import { useEffect } from "react";
import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";

function useMessageListEvents() {
  useEffect(() => {
    const uiListenerId = "UI_LISTENER_" + Date.now();
    const messageListenerId = "MESSAGE_LISTENER_" + Date.now();

    CometChatUIEventHandler.addUIListener(uiListenerId, {
      openChat: ({ user, group }) => {
        console.log("Chat opened:", user || group);
      },
    });

    CometChatUIEventHandler.addMessageListener(messageListenerId, {
      ccMessageEdited: ({ message }) => {
        console.log("Message edited:", message.getId());
      },
      ccMessageDeleted: ({ message }) => {
        console.log("Message deleted:", message.getId());
      },
    });

    return () => {
      CometChatUIEventHandler.removeUIListener(uiListenerId);
      CometChatUIEventHandler.removeMessageListener(messageListenerId);
    };
  }, []);
}
```

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual attachment needed unless additional side effects are required.

| SDK Listener                                                                   | Internal behavior               |
| ------------------------------------------------------------------------------ | ------------------------------- |
| `onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived` | Appends new message to list     |
| `onMessageEdited` / `onMessageDeleted`                                         | Updates/removes message in list |
| `onTypingStarted` / `onTypingEnded`                                            | Shows/hides typing indicator    |
| `onMessagesDelivered` / `onMessagesRead`                                       | Updates receipt ticks           |

***

## Custom View Slots

Each slot replaces a section of the default UI.

| Slot                      | Signature                              | Replaces                    |
| ------------------------- | -------------------------------------- | --------------------------- |
| `HeaderView`              | `({ user, group, id }) => JSX.Element` | Area above the message list |
| `FooterView`              | `({ user, group, id }) => JSX.Element` | Area below the message list |
| `LoadingView`             | `() => JSX.Element`                    | Loading state               |
| `EmptyView`               | `() => JSX.Element`                    | Empty state                 |
| `ErrorView`               | `() => JSX.Element`                    | Error state                 |
| `NewMessageIndicatorView` | `() => JSX.Element`                    | New messages indicator      |
| `templates`               | `CometChatMessageTemplate[]`           | Message bubble rendering    |
| `textFormatters`          | `CometChatTextFormatter[]`             | Text formatting in messages |

### HeaderView

Custom view above the message list.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text, TouchableOpacity } from "react-native";

function MessageListWithHeader() {
  const getHeaderView = ({
    user,
    group,
    id,
  }: {
    user?: CometChat.User;
    group?: CometChat.Group;
    id?: { uid?: string; guid?: string; parentMessageId?: string };
  }) => {
    return (
      <View style={{ flexDirection: "row", padding: 10, backgroundColor: "#edeafa", gap: 8 }}>
        <TouchableOpacity style={{ backgroundColor: "#fafafa", paddingHorizontal: 12, paddingVertical: 6, borderRadius: 16 }}>
          <Text style={{ color: "#6852D6" }}>Notes</Text>
        </TouchableOpacity>
        <TouchableOpacity style={{ backgroundColor: "#fafafa", paddingHorizontal: 12, paddingVertical: 6, borderRadius: 16 }}>
          <Text style={{ color: "#6852D6" }}>Pinned</Text>
        </TouchableOpacity>
      </View>
    );
  };

  return <CometChatMessageList user={chatUser} HeaderView={getHeaderView} />;
}
```

### FooterView

Custom view below the message list.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text, TouchableOpacity } from "react-native";

function MessageListWithFooter() {
  const getFooterView = ({
    user,
    group,
    id,
  }: {
    user?: CometChat.User;
    group?: CometChat.Group;
    id?: { uid?: string; guid?: string; parentMessageId?: string };
  }) => {
    return (
      <View style={{ flexDirection: "row", padding: 10, backgroundColor: "#edeafa", gap: 8 }}>
        <TouchableOpacity style={{ backgroundColor: "#fafafa", paddingHorizontal: 12, paddingVertical: 6, borderRadius: 16 }}>
          <Text style={{ color: "#6852D6" }}>Ice Breakers</Text>
        </TouchableOpacity>
      </View>
    );
  };

  return <CometChatMessageList user={chatUser} FooterView={getFooterView} />;
}
```

### templates

Custom message bubble templates via CometChatMessageTemplate.

```tsx lines theme={null}
import { CometChatMessageList, ChatConfigurator, CometChatMessageTemplate } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { Text } from "react-native";

function MessageListCustomTemplates() {
  const getTemplates = () => {
    let templates: CometChatMessageTemplate[] = ChatConfigurator.getDataSource().getAllMessageTemplates(theme);
    templates.map((data) => {
      if (data.type === "text") {
        data.ContentView = (messageObject: CometChat.BaseMessage) => {
          const textMessage = messageObject as CometChat.TextMessage;
          return (
            <Text style={{ backgroundColor: "#fff5fd", padding: 10 }}>
              {textMessage.getText()}
            </Text>
          );
        };
      }
    });
    return templates;
  };

  return <CometChatMessageList user={chatUser} templates={getTemplates()} />;
}
```

### dateSeperatorPattern

Custom format for displaying sticky date separators.

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";

function MessageListCustomDateSeparator() {
  const customDateSeparatorPattern = (date: number) => {
    const timeStampInSeconds = new Date(date * 1000);
    const day = String(timeStampInSeconds.getUTCDate()).padStart(2, "0");
    const month = String(timeStampInSeconds.getUTCMonth() + 1).padStart(2, "0");
    const year = timeStampInSeconds.getUTCFullYear();
    return `${day}/${month}/${year}`;
  };

  return (
    <CometChatMessageList
      user={chatUser}
      dateSeperatorPattern={customDateSeparatorPattern}
    />
  );
}
```

### datePattern

Custom format for message timestamps.

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function MessageListCustomDatePattern() {
  const generateDateString = (message: CometChat.BaseMessage) => {
    const days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
    const timeStamp = message.getSentAt();
    if (timeStamp) {
      const date = new Date(timeStamp * 1000);
      const day = days[date.getUTCDay()];
      const hours = date.getUTCHours();
      const minutes = String(date.getUTCMinutes()).padStart(2, "0");
      return `${day}, ${hours}:${minutes}`;
    }
    return "---, --:--";
  };

  return (
    <CometChatMessageList
      user={chatUser}
      datePattern={generateDateString}
    />
  );
}
```

### textFormatters

Custom text formatters for message content.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import {
  CometChatMessageList,
  CometChatTextFormatter,
  CometChatMentionsFormatter,
} from "@cometchat/chat-uikit-react-native";

function MessageListWithFormatters() {
  const getTextFormatters = () => {
    const textFormatters: CometChatTextFormatter[] = [];
    const mentionsFormatter = new CometChatMentionsFormatter();
    mentionsFormatter.setMentionsStyle({
      textStyle: { color: "#D6409F" },
      selfTextStyle: { color: "#30A46C" },
    });
    textFormatters.push(mentionsFormatter);
    return textFormatters;
  };

  return (
    <CometChatMessageList
      user={chatUser}
      textFormatters={getTextFormatters()}
    />
  );
}
```

See [CometChatMentionsFormatter](/docs/ui-kit/react-native/mentions-formatter-guide) for mention formatting.

***

## Common Patterns

### Threaded message list

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";

function ThreadedMessageList() {
  return (
    <CometChatMessageList
      user={chatUser}
      parentMessageId={parentMessage.getId()}
    />
  );
}
```

### Hide all chrome — minimal list

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";

function MinimalMessageList() {
  return (
    <CometChatMessageList
      user={chatUser}
      receiptsVisibility={false}
      avatarVisibility={false}
      hideTimestamp={true}
      hideGroupActionMessages={true}
    />
  );
}
```

### Left-aligned messages

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";

function LeftAlignedList() {
  return (
    <CometChatMessageList
      user={chatUser}
      alignment="leftAligned"
    />
  );
}
```

### AI conversation starters

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";

function AIMessageList() {
  const suggestedMessages = [
    "How can I help you today?",
    "Tell me more about your issue.",
    "What would you like to achieve?",
  ];

  return (
    <CometChatMessageList
      user={chatUser}
      suggestedMessages={suggestedMessages}
      onSuggestedMessageClick={(suggestion) => console.log("Clicked:", suggestion)}
    />
  );
}
```

### Navigate to specific message

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";

function NavigateToMessage() {
  return (
    <CometChatMessageList
      user={chatUser}
      goToMessageId="message_id_123"
    />
  );
}
```

### Load last agent conversation

Resume the most recent AI agent conversation on start:

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";

function AgentChat() {
  return (
    <CometChatMessageList
      user={agentUser}
      loadLastAgentConversation={true}
    />
  );
}
```

***

## Styling

The component uses the theme system from `CometChatThemeProvider`. Pass a `style` prop to customize the appearance.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";

function StyledMessageList() {
  return (
    <CometChatMessageList
      user={chatUser}
      style={{
        containerStyle: {
          backgroundColor: "#FEEDE1",
        },
        outgoingMessageBubbleStyles: {
          containerStyle: {
            backgroundColor: "#F76808",
          },
        },
      }}
    />
  );
}
```

### Style Properties

| Property                      | Type        | Description                        |
| ----------------------------- | ----------- | ---------------------------------- |
| `containerStyle`              | `ViewStyle` | Style for the root container       |
| `incomingMessageBubbleStyles` | `object`    | Style for incoming message bubbles |
| `outgoingMessageBubbleStyles` | `object`    | Style for outgoing message bubbles |
| `dateSeparatorStyle`          | `object`    | Style for date separators          |
| `actionSheetStyle`            | `object`    | Style for the action sheet         |

***

## Props

All props are optional unless noted. Either `user` or `group` is required.

### alignment

Controls message alignment.

|         |                               |
| ------- | ----------------------------- |
| Type    | `"leftAligned" \| "standard"` |
| Default | `"standard"`                  |

***

### avatarVisibility

Shows/hides avatars on messages.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### enableMultipleAttachments

Enables multi-attachment rendering: [batch grouping](#multi-attachment-batch-grouping) and the plural bubbles (Images/Videos/Audios/Files, Voice Note). Set `false` (with the matching composer prop) for legacy single-attachment rendering.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### customSoundForMessages

Custom sound file for incoming message notifications.

|         |                |
| ------- | -------------- |
| Type    | `audio source` |
| Default | Built-in sound |

***

### datePattern

Custom function to format message timestamps.

|         |                                              |
| ------- | -------------------------------------------- |
| Type    | `(message: CometChat.BaseMessage) => string` |
| Default | Component default                            |

***

### dateSeperatorPattern

Custom function to format date separator timestamps.

|         |                            |
| ------- | -------------------------- |
| Type    | `(date: number) => string` |
| Default | Component default          |

***

### disableSoundForMessages

Disables the notification sound for incoming messages.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### EmptyView

Custom component displayed when there are no messages.

|         |                      |
| ------- | -------------------- |
| Type    | `() => JSX.Element`  |
| Default | Built-in empty state |

***

### ErrorView

Custom component displayed when an error occurs.

|         |                      |
| ------- | -------------------- |
| Type    | `() => JSX.Element`  |
| Default | Built-in error state |

***

### FooterView

Custom component displayed below the message list.

|         |                                        |
| ------- | -------------------------------------- |
| Type    | `({ user, group, id }) => JSX.Element` |
| Default | `undefined`                            |

***

### goToMessageId

Scrolls to the specified message on initial load.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### group

The group for group conversation messages.

|         |                   |
| ------- | ----------------- |
| Type    | `CometChat.Group` |
| Default | `undefined`       |

***

### HeaderView

Custom component displayed above the message list.

|         |                                        |
| ------- | -------------------------------------- |
| Type    | `({ user, group, id }) => JSX.Element` |
| Default | `undefined`                            |

***

### hideCopyMessageOption

Hides the copy message option.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideDeleteMessageOption

Hides the delete message option.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideEditMessageOption

Hides the edit message option.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideError

Hides the error state view.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideFlagMessageOption

Hides the "Report Message" option.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideFlagRemarkField

Hides the remark text area in the flag message dialog.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideGroupActionMessages

Hides group action messages (join, leave, kick, etc.).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideMessageInfoOption

Hides the message info option.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideMessagePrivatelyOption

Hides the "Message Privately" option.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideModerationStatus

Hides the moderation status UI.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideReactionOption

Hides the reaction option.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideReplyInThreadOption

Hides the "Reply in Thread" option.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideReplyOption

Hides the reply option.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideShareMessageOption

Hides the share message option.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideSuggestedMessages

Hides suggested messages in AI view.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideTimestamp

Hides timestamps on messages.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideTranslateMessageOption

Hides the translate message option.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### loadLastAgentConversation

Automatically loads the most recent agent conversation when set to `true`.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### LoadingView

Custom component displayed during the loading state.

|         |                            |
| ------- | -------------------------- |
| Type    | `() => JSX.Element`        |
| Default | Built-in loading indicator |

***

### messageRequestBuilder

Controls which messages load and in what order.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `CometChat.MessagesRequestBuilder` |
| Default | SDK default                        |

UID/GUID are always overridden internally.

***

### NewMessageIndicatorView

Custom view for the "New Messages" indicator.

|         |                     |
| ------- | ------------------- |
| Type    | `() => JSX.Element` |
| Default | Built-in indicator  |

***

### onAddReactionPress

Callback fired when the "Add More Reactions" button is clicked.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onEmpty

Callback fired when the message list is empty.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onError

Callback fired when the component encounters an error.

|         |                                                 |
| ------- | ----------------------------------------------- |
| Type    | `(error: CometChat.CometChatException) => void` |
| Default | `undefined`                                     |

***

### onLoad

Callback fired when messages are loaded.

|         |                                                  |
| ------- | ------------------------------------------------ |
| Type    | `(messageList: CometChat.BaseMessage[]) => void` |
| Default | `undefined`                                      |

***

### onReactionLongPress

Callback fired when a reaction is long-pressed.

|         |                                                                                     |
| ------- | ----------------------------------------------------------------------------------- |
| Type    | `(reaction: CometChat.ReactionCount, messageObject: CometChat.BaseMessage) => void` |
| Default | `undefined`                                                                         |

***

### onReactionPress

Callback fired when a reaction is clicked.

|         |                                                                                     |
| ------- | ----------------------------------------------------------------------------------- |
| Type    | `(reaction: CometChat.ReactionCount, messageObject: CometChat.BaseMessage) => void` |
| Default | `undefined`                                                                         |

***

### onSuggestedMessageClick

Callback fired when a suggested message is clicked.

|         |                                |
| ------- | ------------------------------ |
| Type    | `(suggestion: string) => void` |
| Default | `undefined`                    |

***

### onThreadRepliesPress

Callback fired when a threaded message reply count is clicked.

|         |                                                                                                |
| ------- | ---------------------------------------------------------------------------------------------- |
| Type    | `(messageObject: CometChat.BaseMessage, messageBubbleView: () => JSX.Element \| null) => void` |
| Default | `undefined`                                                                                    |

***

### parentMessageId

Displays threaded conversation for the specified parent message.

|         |             |
| ------- | ----------- |
| Type    | `number`    |
| Default | `undefined` |

***

### quickReactionList

Custom list of quick reactions.

|         |                      |
| ------- | -------------------- |
| Type    | `string[]`           |
| Default | Predefined reactions |

***

### receiptsVisibility

Shows/hides read/delivery receipt indicators.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### scrollToBottomOnNewMessage

Auto-scrolls to bottom when new messages arrive.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### searchKeyword

Keyword to highlight in message text.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### showMarkAsUnreadOption

Shows "Mark Unread" option in message actions.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### startFromUnreadMessages

Loads from the first unread message if available.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### suggestedMessages

Predefined prompts for AI assistant chats.

|         |             |
| ------- | ----------- |
| Type    | `string[]`  |
| Default | `undefined` |

***

### templates

Custom message bubble templates. Replaces all default templates.

|         |                              |
| ------- | ---------------------------- |
| Type    | `CometChatMessageTemplate[]` |
| Default | SDK defaults                 |

***

### addTemplates

Additional message templates to append to the default templates.

|         |                              |
| ------- | ---------------------------- |
| Type    | `CometChatMessageTemplate[]` |
| Default | `[]`                         |

***

### newMessageIndicatorStyle

Custom styles for the "New Messages" indicator.

|         |                            |
| ------- | -------------------------- |
| Type    | `NewMessageIndicatorStyle` |
| Default | Built-in style             |

***

### newMessageIndicatorText

Custom text for the "New Messages" indicator.

|         |               |
| ------- | ------------- |
| Type    | `string`      |
| Default | Built-in text |

***

### streamingSpeed

Speed in milliseconds for AI response streaming animation.

|         |             |
| ------- | ----------- |
| Type    | `number`    |
| Default | `undefined` |

***

### aiAssistantTools

Tool actions for AI assistant functionality.

|         |                             |
| ------- | --------------------------- |
| Type    | `CometChatAIAssistantTools` |
| Default | `undefined`                 |

***

### textFormatters

Custom text formatters for message content.

|         |                                     |
| ------- | ----------------------------------- |
| Type    | `CometChatTextFormatter[]`          |
| Default | Default formatters from data source |

***

### user

The user for 1-on-1 conversation messages.

|         |                  |
| ------- | ---------------- |
| Type    | `CometChat.User` |
| Default | `undefined`      |

***

## Next Steps

<CardGroup>
  <Card title="Message Header" icon="heading" href="/ui-kit/react-native/message-header">
    Display user or group details in the chat toolbar
  </Card>

  <Card title="Message Composer" icon="pen" href="/ui-kit/react-native/message-composer">
    Compose and send messages in a chat
  </Card>

  <Card title="Messages" icon="comments" href="/ui-kit/react-native/message-list">
    Complete messaging interface with header, list, and composer
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>


# Methods
Source: https://www.cometchat.com/docs/ui-kit/react-native/methods

Use CometChat React Native UI Kit methods for initialization, login, logout, users, groups, messages, calls, and session handling.

<Accordion title="AI Integration Quick Reference">
  | Field                | Value                                                                                                                   |
  | -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
  | Package              | `@cometchat/chat-uikit-react-native`                                                                                    |
  | Import               | `import { CometChatUIKit, UIKitSettings } from "@cometchat/chat-uikit-react-native";`                                   |
  | Init                 | `CometChatUIKit.init(UIKitSettings)`                                                                                    |
  | Login (dev)          | `CometChatUIKit.login({ uid: "UID" })`                                                                                  |
  | Login (prod)         | `CometChatUIKit.login({ authToken: "AUTH_TOKEN" })`                                                                     |
  | Other methods        | `CometChatUIKit.logout()`, `CometChatUIKit.createUser(user)`, `CometChatUIKit.updateUser(user)`                         |
  | Send messages        | `CometChatUIKit.sendTextMessage()`, `CometChatUIKit.sendMediaMessage()`, `CometChatUIKit.sendCustomMessage()`           |
  | Interactive messages | `CometChatUIKit.sendFormMessage()`, `CometChatUIKit.sendCardMessage()`, `CometChatUIKit.sendCustomInteractiveMessage()` |
  | Note                 | Use these wrapper methods instead of raw SDK calls — they manage internal UI Kit eventing                               |
</Accordion>

The UI Kit wraps the [Chat SDK](/docs/sdk/react-native/overview) methods to manage internal eventing and keep UI components synchronized. Use these wrapper methods instead of raw SDK calls.

<Warning>
  `CometChatUIKit.init(UIKitSettings)` must be called before rendering any UI Kit components or calling any SDK methods. Initialization must complete before login.
</Warning>

<Warning>
  Auth Key is for development/testing only. In production, generate Auth Tokens on the server using the REST API and pass them to the client. Never expose Auth Keys in production client code.
</Warning>

## Methods

All methods are accessed via the `CometChatUIKit` class.

### Init

Initializes the [CometChat React Native SDK](/docs/sdk/react-native/overview). Must be called on app startup before any other UI Kit method.

<Note>
  Replace `APP_ID`, `REGION`, and `AUTH_KEY` with values from the CometChat Dashboard. `Auth Key` is optional — use [Auth Token](#login-using-auth-token) for production.
</Note>

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    import { CometChatUIKit, UIKitSettings } from "@cometchat/chat-uikit-react-native";

    const uikitSettings = new UIKitSettings({
      appId: "APP_ID",     // Replace with your App ID
      region: "REGION",    // Replace with your App Region ("eu" or "us")
      authKey: "AUTH_KEY", // Replace with your Auth Key (optional for Auth Token flow)
    });

    CometChatUIKit.init(uikitSettings)
      .then(() => {
        console.log("Initialization completed successfully");
      })
      .catch((error) => {
        console.log("Initialization failed with exception:", error);
      });
    ```
  </Tab>
</Tabs>

***

### Login using Auth Key

Simple authentication for development/POC. For production, use [Auth Token](#login-using-auth-token).

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";

    const uid = "user_uid";

    CometChatUIKit.login({ uid: uid })
      .then((user) => {
        console.log("User logged in successfully:", user);
      })
      .catch((error) => {
        console.log("Login failed with exception:", error);
      });
    ```
  </Tab>
</Tabs>

***

### Login using Auth Token

Production-safe authentication that does not expose the Auth Key in client code.

1. [Create a User](/docs/rest-api/chat-apis) via the CometChat API when the user signs up in your app.
2. [Create an Auth Token](/docs/rest-api/chat-apis) via the CometChat API for the new user and save the token in your database.
3. Load the Auth Token in your client and pass it to the `login()` method.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";

    const authToken = "AUTH_TOKEN";

    CometChatUIKit.login({ authToken: authToken })
      .then((user) => {
        console.log("User logged in successfully:", user);
      })
      .catch((error) => {
        console.log("Login failed with exception:", error);
      });
    ```
  </Tab>
</Tabs>

***

### Logout

Ends the current user session.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";

    CometChatUIKit.logout();
    ```
  </Tab>
</Tabs>

***

### Create User

Takes a `User` object and returns the created `User` object.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";

    const uid = "user1";
    const name = "Kevin";
    const avatar = "https://example.com/avatar.png";

    const user = new CometChat.User(uid, name);
    user.setAvatar(avatar);

    CometChatUIKit.createUser(user)
      .then((user) => {
        console.log("User created:", user);
      })
      .catch((error) => {
        console.log("Creating new user failed:", error);
      });
    ```
  </Tab>
</Tabs>

***

### Update User

Takes a `User` object and returns the updated `User` object.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";

    const uid = "user1";
    const name = "Kevin Fernandez";
    const avatar = "https://example.com/new-avatar.png";

    const user = new CometChat.User(uid, name);
    user.setAvatar(avatar);

    CometChatUIKit.updateUser(user)
      .then((user) => {
        console.log("User updated:", user);
      })
      .catch((error) => {
        console.log("Updating user failed:", error);
      });
    ```
  </Tab>
</Tabs>

***

## Sending Messages

### Text Message

Sends a text message in a 1:1 or group chat.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import {
      CometChatUIKit,
      CometChatUiKitConstants,
    } from "@cometchat/chat-uikit-react-native";

    const receiverID = "uid";
    const messageText = "Hello world!";
    const receiverType = CometChatUiKitConstants.ReceiverTypeConstants.user;
    const textMessage = new CometChat.TextMessage(
      receiverID,
      messageText,
      receiverType
    );

    CometChatUIKit.sendTextMessage(textMessage)
      .then((message) => {
        console.log("Message sent successfully:", message);
      })
      .catch(console.log);
    ```
  </Tab>
</Tabs>

***

### Media Message

Sends a media message in a 1:1 or group chat.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import {
      CometChatUIKit,
      CometChatUiKitConstants,
    } from "@cometchat/chat-uikit-react-native";

    const receiverID = "uid";
    const messageType = CometChatUiKitConstants.MessageTypeConstants.file;
    const receiverType = CometChatUiKitConstants.ReceiverTypeConstants.user;
    const mediaMessage = new CometChat.MediaMessage(
      receiverID,
      `INPUT FILE OBJECT`,
      messageType,
      receiverType
    );

    CometChatUIKit.sendMediaMessage(mediaMessage)
      .then((message) => {
        console.log("Media message sent successfully", message);
      })
      .catch(console.log);
    ```
  </Tab>
</Tabs>

***

### Custom Message

Sends a custom message (neither text nor media) in a 1:1 or group chat.

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import {
      CometChatUIKit,
      CometChatUiKitConstants,
    } from "@cometchat/chat-uikit-react-native";

    const receiverID = "uid";
    const customData = {
      latitude: "50.6192171633316",
      longitude: "-72.68182268750002",
    };
    const customType = "location";
    const receiverType = CometChatUiKitConstants.ReceiverTypeConstants.user;
    const customMessage = new CometChat.CustomMessage(
      receiverID,
      receiverType,
      customType,
      customData
    );

    CometChatUIKit.sendCustomMessage(customMessage)
      .then((message) => {
        console.log("Custom message sent successfully", message);
      })
      .catch(console.log);
    ```
  </Tab>
</Tabs>

***

## Interactive Messages

### Form Message

Sends a Form message which is an extension of Interactive Message.

<Tabs>
  <Tab title="1:1 Chat">
    ```js theme={null}
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";

    const receiverID = "UID";

    // Create an instance of APIAction
    let apiAction = new APIAction("https://example.com/api", "POST");

    // Create an instance of ButtonElement
    let submitButton = new ButtonElement("1", apiAction, "Submit");

    // Create an instance of TextInput
    let nameInput = new TextInputElement("1", "Please enter your name");

    // Create a new instance of FormMessage
    let formMessage = new FormMessage(
      receiverID,
      CometChat.RECEIVER_TYPE.USER,
      "Title",
      [nameInput],
      submitButton
    );

    CometChatUIKit.sendFormMessage(formMessage)
      .then((message) => {
        console.log("Form message sent successfully", message);
      })
      .catch(console.log);
    ```
  </Tab>

  <Tab title="Group Chat">
    ```js theme={null}
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";

    const receiverID = "GUID";

    // Create an instance of APIAction
    let apiAction = new APIAction("https://example.com/api", "POST");

    // Create an instance of ButtonElement
    let submitButton = new ButtonElement("1", apiAction, "Submit");

    // Create an instance of TextInput
    let nameInput = new TextInputElement("1", "Please enter your name");

    // Create a new instance of FormMessage
    let formMessage = new FormMessage(
      receiverID,
      CometChat.RECEIVER_TYPE.GROUP,
      "Title",
      [nameInput],
      submitButton
    );

    CometChatUIKit.sendFormMessage(formMessage)
      .then((message) => {
        console.log("Form message sent successfully", message);
      })
      .catch(console.log);
    ```
  </Tab>
</Tabs>

***

### Card Message

Sends a Card message which is an extension of Interactive Message.

<Tabs>
  <Tab title="1:1 Chat">
    ```js theme={null}
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";

    const receiverID = "UID";

    // Create instance of ButtonElement for card actions
    let cardAction = new ButtonElement(
      "1",
      new APIAction("https://example.com/api", "POST"),
      "Click Me"
    );

    // Create a new instance of CardMessage
    let cardMessage = new CardMessage(
      receiverID,
      CometChat.RECEIVER_TYPE.USER,
      "This is a card",
      [cardAction]
    );

    CometChatUIKit.sendCardMessage(cardMessage)
      .then((message) => {
        console.log("Card message sent successfully", message);
      })
      .catch(console.log);
    ```
  </Tab>

  <Tab title="Group Chat">
    ```js theme={null}
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";

    const receiverID = "GUID";

    // Create instance of ButtonElement for card actions
    let cardAction = new ButtonElement(
      "1",
      new APIAction("https://example.com/api", "POST"),
      "Click Me"
    );

    // Create a new instance of CardMessage
    let cardMessage = new CardMessage(
      receiverID,
      CometChat.RECEIVER_TYPE.GROUP,
      "This is a card",
      [cardAction]
    );

    CometChatUIKit.sendCardMessage(cardMessage)
      .then((message) => {
        console.log("Card message sent successfully", message);
      })
      .catch(console.log);
    ```
  </Tab>
</Tabs>

***

### Custom Interactive Message

Sends a CustomInteractive message which is an extension of Interactive Message.

<Tabs>
  <Tab title="1:1 Chat">
    ```js theme={null}
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";

    const receiverID = "UID";
    const customData = { /* your custom JSON data */ };

    let customMessage = new CustomInteractiveMessage(
      receiverID,
      CometChat.RECEIVER_TYPE.USER,
      customData
    );

    CometChatUIKit.sendCustomInteractiveMessage(customMessage)
      .then((message) => {
        console.log("CustomInteractive message sent successfully", message);
      })
      .catch(console.log);
    ```
  </Tab>

  <Tab title="Group Chat">
    ```js theme={null}
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";

    const receiverID = "GUID";
    const customData = { /* your custom JSON data */ };

    let customMessage = new CustomInteractiveMessage(
      receiverID,
      CometChat.RECEIVER_TYPE.GROUP,
      customData
    );

    CometChatUIKit.sendCustomInteractiveMessage(customMessage)
      .then((message) => {
        console.log("CustomInteractive message sent successfully", message);
      })
      .catch(console.log);
    ```
  </Tab>
</Tabs>

***

## UIKitSettings

`UIKitSettings` is an object containing credentials to initialize CometChat SDK.

| Property                        | Type      | Description                                                                                                   |
| ------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
| `appId`                         | `string`  | The unique ID for the app, available on dashboard                                                             |
| `region`                        | `string`  | The region for the app (`us` or `eu`)                                                                         |
| `authKey`                       | `string`  | The auth key for the app, available on dashboard                                                              |
| `subscriptionType`              | `string`  | Sets user presence subscription for all users                                                                 |
| `autoEstablishSocketConnection` | `boolean` | Configure if web socket connections will be established automatically on app initialization (default: `true`) |
| `disableCalling`                | `boolean` | Disable calling features                                                                                      |
| `overrideAdminHost`             | `string`  | Used to set the admin host                                                                                    |
| `overrideClientHost`            | `string`  | Used to set the client host                                                                                   |

***

## Next Steps

<CardGroup>
  <Card title="Integration" icon="plug" href="/ui-kit/react-native/react-native-cli-integration">
    Complete guide to integrating the UI Kit
  </Card>

  <Card title="Events" icon="bolt" href="/ui-kit/react-native/events">
    Listen to UI Kit events for custom behavior
  </Card>

  <Card title="Components Overview" icon="puzzle-piece" href="/ui-kit/react-native/components-overview">
    Explore all available UI components
  </Card>

  <Card title="Theme" icon="palette" href="/ui-kit/react-native/theme">
    Customize the look and feel of the UI Kit
  </Card>
</CardGroup>


# Notification Feed
Source: https://www.cometchat.com/docs/ui-kit/react-native/notification-feed

Full-screen notification feed component with category filtering, card rendering, real-time updates, and engagement reporting.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatNotificationFeed",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatNotificationFeed } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Full-screen notification feed with category filtering, timestamp grouping, card rendering via @cometchat/cards-react-native, real-time updates, and automatic engagement reporting.",
    "props": {
      "data": {
        "title": { "type": "string", "default": "\"Notifications\"" },
        "scrollToItemId": { "type": "string", "default": "undefined", "note": "Deep link to a specific feed item" },
        "notificationFeedRequestBuilder": { "type": "NotificationFeedRequestBuilder", "default": "SDK default (20 per page)" },
        "notificationCategoriesRequestBuilder": { "type": "NotificationCategoriesRequestBuilder", "default": "SDK default (50 per page)" }
      },
      "callbacks": {
        "onItemClick": "(feedItem: NotificationFeedItem) => void",
        "onActionClick": "(feedItem: NotificationFeedItem, action: { type: string, params: object, elementId: string }) => void",
        "onError": "(error: CometChat.CometChatException) => void",
        "onBackPress": "() => void"
      },
      "visibility": {
        "showHeader": { "type": "boolean", "default": true },
        "showBackButton": { "type": "boolean", "default": false },
        "showFilterChips": { "type": "boolean", "default": true }
      },
      "viewSlots": {
        "HeaderView": "() => JSX.Element",
        "EmptyView": "() => JSX.Element",
        "ErrorView": "() => JSX.Element",
        "LoadingView": "() => JSX.Element"
      },
      "cards": {
        "cardThemeMode": { "type": "\"auto\" | \"light\" | \"dark\"", "default": "\"auto\"" },
        "cardThemeOverride": { "type": "CometChatCardThemeOverride", "default": "undefined" }
      }
    },
    "automaticBehaviors": [
      "Real-time updates via WebSocket listener",
      "Delivery reporting on fetch",
      "Read reporting on viewport visibility",
      "Unread count polling every 30 seconds",
      "Infinite scroll pagination",
      "Pull-to-refresh",
      "Timestamp grouping (Today, Yesterday, day name, date)",
      "Category filter chips"
    ]
  }
  ```
</Accordion>

`CometChatNotificationFeed` displays a scrollable notification feed where each item is rendered as a native card using the CometChat Cards library. It handles fetching, pagination, category filtering, timestamp grouping, real-time updates, and read/delivered/engagement reporting automatically.

***

## Where It Fits

`CometChatNotificationFeed` is a full-screen component. Drop it into a screen or navigation destination. It manages its own data fetching, state, and real-time listeners — you just handle navigation callbacks.

```tsx lines theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react-native";

function NotificationsScreen({ navigation }) {
  return (
    <CometChatNotificationFeed
      showBackButton={true}
      onBackPress={() => navigation.goBack()}
      onItemClick={(item) => {
        // Handle item tap (e.g., open detail or deep link)
      }}
    />
  );
}
```

***

## Minimal Render

```tsx lines theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react-native";

function NotificationsDemo() {
  return <CometChatNotificationFeed />;
}

export default NotificationsDemo;
```

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()` and a user logged in.

***

## Filtering Feed Items

Control what loads using custom request builders:

```tsx lines theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function UnreadNotifications() {
  return (
    <CometChatNotificationFeed
      notificationFeedRequestBuilder={
        new CometChat.NotificationFeedRequestBuilder()
          .setLimit(30)
          .setReadState(CometChat.FeedReadState.UNREAD)
          .setCategory("promotions")
          .build()
      }
    />
  );
}
```

### Filter Options

| Builder Method                 | Description                          |
| ------------------------------ | ------------------------------------ |
| `.setLimit(number)`            | Items per page (default 20, max 100) |
| `.setReadState(FeedReadState)` | `READ`, `UNREAD`, or `ALL`           |
| `.setCategory(string)`         | Filter by category label             |
| `.setChannelId(string)`        | Filter by channel                    |
| `.setTags(string[])`           | Filter by tags                       |
| `.setDateFrom(string)`         | ISO 8601 date lower bound            |
| `.setDateTo(string)`           | ISO 8601 date upper bound            |

***

## Actions and Events

### Callback Props

#### onItemClick

Fires when a feed item card is tapped.

```tsx lines theme={null}
<CometChatNotificationFeed
  onItemClick={(item) => {
    console.log("Item tapped:", item.getId());
  }}
/>
```

#### onActionClick

Fires when an interactive element (button, link) inside a card is tapped.

```tsx lines theme={null}
<CometChatNotificationFeed
  onActionClick={(item, action) => {
    const { type, params, elementId } = action;
    switch (type) {
      case "openUrl":
        // Open params.url in browser
        break;
      case "chatWithUser":
        // Navigate to chat with params.uid
        break;
    }
  }}
/>
```

#### onError

Fires when an internal error occurs (network failure, SDK exception).

```tsx lines theme={null}
<CometChatNotificationFeed
  onError={(error) => {
    console.error("Feed error:", error.message);
  }}
/>
```

#### onBackPress

Fires when the back button in the header is tapped.

```tsx lines theme={null}
<CometChatNotificationFeed
  showBackButton={true}
  onBackPress={() => navigation.goBack()}
/>
```

### Automatic Behaviors

The component handles these automatically — no manual setup needed:

| Behavior             | Description                                             |
| -------------------- | ------------------------------------------------------- |
| Real-time updates    | New items appear at the top via WebSocket listener      |
| Delivery reporting   | Items are reported as delivered when fetched            |
| Read reporting       | Items are reported as read when visible in viewport     |
| Unread count polling | Polls unread count every 30 seconds to update badges    |
| Infinite scroll      | Fetches next page when scrolling near the bottom        |
| Pull-to-refresh      | Resets and fetches fresh data on pull                   |
| Timestamp grouping   | Groups items as "Today", "Yesterday", day name, or date |
| Category filtering   | Filter chips row for category-based filtering           |

***

## Custom View Slots

### HeaderView

Replace the entire header:

```tsx lines theme={null}
<CometChatNotificationFeed
  HeaderView={() => (
    <View style={{ padding: 16, flexDirection: "row", alignItems: "center" }}>
      <Text style={{ fontSize: 20, fontWeight: "bold" }}>My Notifications</Text>
    </View>
  )}
/>
```

### State Views

```tsx lines theme={null}
<CometChatNotificationFeed
  EmptyView={() => (
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
      <Text>No notifications yet</Text>
    </View>
  )}
  ErrorView={() => (
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
      <Text>Something went wrong</Text>
    </View>
  )}
  LoadingView={() => (
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
      <ActivityIndicator size="large" />
    </View>
  )}
/>
```

***

## Styling

The component uses the theme system from `CometChatThemeProvider`. Pass a `style` prop to customize the appearance.

```tsx lines theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react-native";

function StyledNotifications() {
  return (
    <CometChatNotificationFeed
      style={{
        containerStyle: { backgroundColor: "#F5F5F5" },
        chipActiveStyle: {
          containerStyle: { backgroundColor: "#6852D6" },
          textStyle: { color: "#FFFFFF" },
        },
        chipInactiveStyle: {
          containerStyle: { backgroundColor: "#FFFFFF", borderColor: "#E0E0E0" },
          textStyle: { color: "#727272" },
        },
        cardContainerStyle: { backgroundColor: "#FFFFFF" },
        cardBorderColor: "#E0E0E0",
        unreadIndicatorColor: "#6852D6",
      }}
    />
  );
}
```

### Style Properties

| Property                 | Description                                                               |
| ------------------------ | ------------------------------------------------------------------------- |
| `containerStyle`         | Root container style                                                      |
| `headerContainerStyle`   | Header bar style                                                          |
| `titleStyle`             | Header title text style                                                   |
| `chipActiveStyle`        | Selected filter chip (containerStyle + textStyle)                         |
| `chipInactiveStyle`      | Unselected filter chip (containerStyle + textStyle)                       |
| `chipBadgeStyle`         | Active chip badge (containerStyle + textStyle)                            |
| `chipInactiveBadgeStyle` | Inactive chip badge (containerStyle + textStyle)                          |
| `sectionHeaderStyle`     | Timestamp section header (containerStyle + textStyle)                     |
| `itemHeaderStyle`        | Per-item header (containerStyle + categoryTextStyle + timestampTextStyle) |
| `cardContainerStyle`     | Card container style                                                      |
| `cardBorderColor`        | Card border color                                                         |
| `cardBorderRadius`       | Card corner radius                                                        |
| `cardBorderWidth`        | Card border width                                                         |
| `unreadIndicatorStyle`   | Unread dot style                                                          |
| `unreadIndicatorColor`   | Unread dot color                                                          |
| `emptyStateStyle`        | Empty state (containerStyle + titleStyle + subTitleStyle)                 |
| `errorStateStyle`        | Error state (containerStyle + titleStyle + subTitleStyle)                 |
| `separatorStyle`         | Separator between cards                                                   |

***

## Props

All props are optional.

### cardThemeMode

Theme mode for the card renderer.

|         |                               |
| ------- | ----------------------------- |
| Type    | `"auto" \| "light" \| "dark"` |
| Default | `"auto"`                      |

***

### cardThemeOverride

Custom theme override for the card renderer.

|         |                              |
| ------- | ---------------------------- |
| Type    | `CometChatCardThemeOverride` |
| Default | `undefined`                  |

***

### EmptyView

Custom component displayed when there are no notifications.

|         |                      |
| ------- | -------------------- |
| Type    | `() => JSX.Element`  |
| Default | Built-in empty state |

***

### ErrorView

Custom component displayed when an error occurs.

|         |                      |
| ------- | -------------------- |
| Type    | `() => JSX.Element`  |
| Default | Built-in error state |

***

### HeaderView

Custom component replacing the entire header.

|         |                     |
| ------- | ------------------- |
| Type    | `() => JSX.Element` |
| Default | Built-in header     |

***

### LoadingView

Custom component displayed during the loading state.

|         |                            |
| ------- | -------------------------- |
| Type    | `() => JSX.Element`        |
| Default | Built-in loading indicator |

***

### notificationCategoriesRequestBuilder

Custom request builder for fetching categories.

|         |                                        |
| ------- | -------------------------------------- |
| Type    | `NotificationCategoriesRequestBuilder` |
| Default | SDK default (50 per page)              |

***

### notificationFeedRequestBuilder

Custom request builder for fetching feed items.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `NotificationFeedRequestBuilder` |
| Default | SDK default (20 per page)        |

***

### onActionClick

Callback fired when an interactive element inside a card is tapped.

|         |                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------- |
| Type    | `(feedItem: NotificationFeedItem, action: { type: string, params: object, elementId: string }) => void` |
| Default | `undefined`                                                                                             |

***

### onBackPress

Callback fired when the back button is pressed.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onError

Callback fired when the component encounters an error.

|         |                                                 |
| ------- | ----------------------------------------------- |
| Type    | `(error: CometChat.CometChatException) => void` |
| Default | `undefined`                                     |

***

### onItemClick

Callback fired when a feed item card is tapped.

|         |                                            |
| ------- | ------------------------------------------ |
| Type    | `(feedItem: NotificationFeedItem) => void` |
| Default | `undefined`                                |

***

### scrollToItemId

Deep link to a specific feed item by ID.

|         |             |
| ------- | ----------- |
| Type    | `string`    |
| Default | `undefined` |

***

### showBackButton

Shows/hides the back button in the header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showFilterChips

Shows/hides the category filter chips row.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### showHeader

Shows/hides the entire header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### title

Header title text.

|         |                   |
| ------- | ----------------- |
| Type    | `string`          |
| Default | `"Notifications"` |

***

## Common Patterns

### Show only unread items

```tsx lines theme={null}
<CometChatNotificationFeed
  notificationFeedRequestBuilder={
    new CometChat.NotificationFeedRequestBuilder()
      .setReadState(CometChat.FeedReadState.UNREAD)
      .build()
  }
/>
```

### Hide filter chips and header

```tsx lines theme={null}
<CometChatNotificationFeed
  showHeader={false}
  showFilterChips={false}
/>
```

### Deep link to a specific notification

```tsx lines theme={null}
<CometChatNotificationFeed
  scrollToItemId="notification-item-id-123"
/>
```

***

## Next Steps

<CardGroup>
  <Card title="Campaigns Feature" icon="bullhorn" href="/ui-kit/react-native/campaigns">
    Overview of how campaigns work end-to-end
  </Card>

  <Card title="SDK Campaigns API" icon="code" href="/sdk/react-native/campaigns">
    Low-level SDK APIs for feed items, categories, and engagement
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Full styling reference for all components
  </Card>

  <Card title="Theming" icon="palette" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and appearance
  </Card>
</CardGroup>


# Outgoing Call
Source: https://www.cometchat.com/docs/ui-kit/react-native/outgoing-call

Display and manage outgoing voice and video calls with CometChatOutgoingCall component in React Native UI Kit, providing call status and controls.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatOutgoingCall",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatOutgoingCall } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Visual representation for outgoing voice and video calls with call status and end call controls.",
    "props": {
      "data": {
        "call": {
          "type": "CometChat.Call | CometChat.CustomMessage",
          "note": "The outgoing call object"
        }
      },
      "callbacks": {
        "onEndCallButtonPressed": "(call: CometChat.Call) => void",
        "onError": "(error: CometChat.CometChatException) => void"
      },
      "sound": {
        "disableSoundForCalls": { "type": "boolean", "default": false },
        "customSoundForCalls": { "type": "string", "default": "built-in" }
      },
      "viewSlots": {
        "TitleView": "(call) => JSX.Element",
        "SubtitleView": "(call) => JSX.Element",
        "AvatarView": "(call) => JSX.Element",
        "EndCallView": "(call) => JSX.Element"
      }
    },
    "events": [
      { "name": "ccCallEnded", "payload": "{ call }", "description": "Call successfully ended" },
      { "name": "ccCallFailled", "payload": "{ call }", "description": "Error during call" }
    ]
  }
  ```
</Accordion>

## Where It Fits

`CometChatOutgoingCall` is a [Component](/docs/ui-kit/react-native/components-overview#components) that provides a visual representation of a user-initiated call, whether it's a voice or video call. It serves as an interface for managing outgoing calls, providing users with essential options to control the call experience.

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import {
  CometChatOutgoingCall,
  CometChatUiKitConstants,
} from "@cometchat/chat-uikit-react-native";
import { useState, useEffect } from "react";

function OutgoingCallDemo() {
  const [call, setCall] = useState<CometChat.Call>();

  useEffect(() => {
    const callObject = new CometChat.Call(
      "receiver-uid",
      CometChatUiKitConstants.MessageTypeConstants.audio,
      CometChatUiKitConstants.ReceiverTypeConstants.user
    );

    CometChat.initiateCall(callObject)
      .then((c) => setCall(c))
      .catch(console.log);
  }, []);

  return <>{call && <CometChatOutgoingCall call={call} />}</>;
}
```

***

## Actions and Events

### Callback Props

#### onEndCallButtonPressed

Fires when the end call button is pressed.

```tsx lines theme={null}
onEndCallButtonPressed?: (call: CometChat.Call) => void
```

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react-native";

function OutgoingCallWithEndButton() {
  const cancelCall = (c: CometChat.Call) => {
    CometChat.endCall(c.getSessionId()).then(() => {
      setCall(undefined);
    });
  };

  return (
    <CometChatOutgoingCall
      call={call}
      onEndCallButtonPressed={cancelCall}
    />
  );
}
```

#### onError

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

```tsx lines theme={null}
onError?: (error: CometChat.CometChatException) => void
```

```tsx lines theme={null}
import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function OutgoingCallWithError() {
  return (
    <CometChatOutgoingCall
      call={call}
      onError={(error: CometChat.CometChatException) => {
        console.error("OutgoingCall error:", error);
      }}
    />
  );
}
```

### Global UI Events

`CometChatUIEventHandler` emits events subscribable from anywhere in the application. Add listeners and remove them on cleanup.

| Event           | Fires when                             | Payload    |
| --------------- | -------------------------------------- | ---------- |
| `ccCallEnded`   | Initiated call successfully ends       | `{ call }` |
| `ccCallFailled` | Error occurs during the initiated call | `{ call }` |

When to use: sync external UI with call state changes. For example, update a call status indicator, show notifications, or log call events.

```tsx lines theme={null}
import { useEffect } from "react";
import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";

function useOutgoingCallEvents() {
  useEffect(() => {
    const listenerId = "OUTGOING_CALL_EVENTS_" + Date.now();

    CometChatUIEventHandler.addCallListener(listenerId, {
      ccCallEnded: ({ call }) => {
        console.log("Call ended:", call);
      },
      ccCallFailled: ({ call }) => {
        console.log("Call failed:", call);
      },
    });

    return () => {
      CometChatUIEventHandler.removeCallListener(listenerId);
    };
  }, []);
}
```

***

## Custom View Slots

Each slot replaces a section of the default UI. Slots that accept a call parameter receive the call object for customization.

| Slot           | Signature               | Replaces                 |
| -------------- | ----------------------- | ------------------------ |
| `TitleView`    | `(call) => JSX.Element` | Caller name / title text |
| `SubtitleView` | `(call) => JSX.Element` | Call status text         |
| `AvatarView`   | `(call) => JSX.Element` | Avatar / profile picture |
| `EndCallView`  | `(call) => JSX.Element` | End call button          |

### TitleView

Custom view for the caller name / title text.

```tsx lines theme={null}
TitleView?: (call: CometChat.Call | CometChat.CustomMessage) => JSX.Element
```

```tsx lines theme={null}
import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { Text } from "react-native";

function TitleViewDemo() {
  const getTitleView = (call: CometChat.Call | CometChat.CustomMessage) => {
    const receiver = call.getCallReceiver();
    return <Text style={{ fontSize: 18, fontWeight: 'bold' }}>{receiver.getName()}</Text>;
  };

  return <CometChatOutgoingCall call={call} TitleView={getTitleView} />;
}
```

### SubtitleView

Custom view for the call status text.

```tsx lines theme={null}
SubtitleView?: (call: CometChat.Call | CometChat.CustomMessage) => JSX.Element
```

```tsx lines theme={null}
import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { Text } from "react-native";

function SubtitleViewDemo() {
  const getSubtitleView = (call: CometChat.Call | CometChat.CustomMessage) => {
    return <Text style={{ color: '#727272' }}>Calling...</Text>;
  };

  return <CometChatOutgoingCall call={call} SubtitleView={getSubtitleView} />;
}
```

### AvatarView

Custom view for the avatar / profile picture.

```tsx lines theme={null}
AvatarView?: (call: CometChat.Call | CometChat.CustomMessage) => JSX.Element
```

```tsx lines theme={null}
import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function AvatarViewDemo() {
  const getAvatarView = (call: CometChat.Call | CometChat.CustomMessage) => {
    const receiver = call.getCallReceiver();
    return (
      <View style={{ width: 80, height: 80, borderRadius: 40, backgroundColor: '#6852D6' }}>
        <Text style={{ color: 'white', textAlign: 'center', lineHeight: 80, fontSize: 24 }}>
          {receiver.getName().charAt(0)}
        </Text>
      </View>
    );
  };

  return <CometChatOutgoingCall call={call} AvatarView={getAvatarView} />;
}
```

### EndCallView

Custom view for the end call button.

```tsx lines theme={null}
EndCallView?: (call: CometChat.Call | CometChat.CustomMessage) => JSX.Element
```

```tsx lines theme={null}
import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { TouchableOpacity, Text } from "react-native";

function EndCallViewDemo() {
  const getEndCallView = (call: CometChat.Call | CometChat.CustomMessage) => {
    return (
      <TouchableOpacity
        style={{ backgroundColor: '#E54D2E', padding: 16, borderRadius: 30 }}
        onPress={() => CometChat.endCall(call.getSessionId())}
      >
        <Text style={{ color: 'white' }}>End Call</Text>
      </TouchableOpacity>
    );
  };

  return <CometChatOutgoingCall call={call} EndCallView={getEndCallView} />;
}
```

***

## 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 `CometChatOutgoingCall` component.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react-native";

function StylingDemo() {
  return (
    <CometChatOutgoingCall
      call={call}
      style={{
        avatarStyle: {
          containerStyle: {
            borderRadius: 8,
          },
          imageStyle: {
            borderRadius: 8,
          },
        },
        endCallButtonStyle: {
          borderRadius: 8,
        },
      }}
    />
  );
}
```

### Visibility Props

| Property               | Description                                | Code                             |
| ---------------------- | ------------------------------------------ | -------------------------------- |
| `disableSoundForCalls` | Disable/enable the sound of outgoing calls | `disableSoundForCalls?: boolean` |
| `customSoundForCalls`  | Set custom sound for outgoing calls        | `customSoundForCalls?: string`   |

***

## Next Steps

<CardGroup>
  <Card title="Incoming Call" icon="phone-arrow-down-left" href="/ui-kit/react-native/incoming-call">
    Display and handle incoming calls
  </Card>

  <Card title="Call Buttons" icon="phone" href="/ui-kit/react-native/call-buttons">
    Add voice and video call buttons to your UI
  </Card>

  <Card title="Call Features" icon="video" href="/ui-kit/react-native/call-features">
    Overview of all calling features
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>


# React Native UI Kit
Source: https://www.cometchat.com/docs/ui-kit/react-native/overview

Prebuilt React Native components for chat, voice, and video calling. Supports React Native CLI and Expo.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                                       |
  | ------------ | --------------------------------------------------------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react-native` v5.x                                                                                   |
  | Peer deps    | `react-native` >=0.70, `@cometchat/chat-sdk-react-native`, `react-native-gesture-handler`, `react-native-safe-area-context` |
  | Calling      | Optional — `@cometchat/calls-sdk-react-native`                                                                              |
  | Localization | Built-in localization support                                                                                               |
  | Source       | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5)                                                 |
  | AI Skills    | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills)                                       |
</Accordion>

The CometChat React Native UI Kit provides prebuilt, customizable components for adding chat, voice, and video calling to any React Native app. Each component handles its own data fetching, real-time listeners, and state — you just drop them into your layout.

<Frame>
  <img />
</Frame>

<Warning>
  `CometChatUIKit.init(UIKitSettings)` must be called before rendering any UI Kit components or calling any SDK methods. Initialization must complete before login.
</Warning>

<Warning>
  Auth Key is for development/testing only. In production, generate Auth Tokens on your server using the REST API and pass them to the client. Never expose Auth Keys in production client code.
</Warning>

***

## Integrate with AI Coding Agents

Use [CometChat Skills](https://github.com/cometchat/cometchat-skills) to add chat to any React Native project through your AI coding agent. The skill takes an AI-first approach — your agent has a short conversation with you to understand your project and chat requirements, then writes production-grade integration code tailored to the files you already have.

Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [30+ more agents](https://github.com/cometchat/cometchat-skills).

```bash theme={null}
npx @cometchat/skills add
```

Use `--ide <name>` to target a specific IDE (e.g. `--ide cursor`), or `--ide all` to install for all supported IDEs.

Then in your IDE:

```
/cometchat add chat to my app
```

The skill detects your framework (Expo or bare React Native), navigation setup, and existing auth system. It onboards you to CometChat directly in the terminal — signup, login, and app creation all via the CLI. It reads your screens, nav, and components before proposing a placement (stack, tab, modal, or bottom sheet), shows the plan (which files it will create, modify, and leave untouched), and waits for your approval before writing code.

After the first integration, re-run `/cometchat` anytime to pick from the iteration menu:

* **Customize look & feel** — theme presets (slack / whatsapp / imessage / discord / notion) or your own brand color
* **Add a feature** — 40+ features including calls, reactions, polls, AI smart replies, file sharing, presence
* **Customize a component** — custom message bubbles, headers, composer actions, empty/loading states
* **Add another placement** — modal / bottom sheet / extra tab
* **Set up production auth** — replace the dev Auth Key with a server-side token endpoint
* **Set up user management** — server endpoints for creating/updating/deleting CometChat users
* **Set up push notifications** — APNs + FCM end-to-end
* **Run diagnostics** — verify, drift detection, symptom-to-cause lookup

***

## Get Started

Pick your framework and follow the step-by-step integration guide:

<CardGroup>
  <Card title="React Native CLI" icon="react" href="/ui-kit/react-native/react-native-cli-integration">
    Standard React Native project setup
  </Card>

  <Card title="Expo" icon={<img src="https://mintcdn.com/cometchat-22654f5b/_qoyT92TVR_JeFMf/images/icons/expo.svg?fit=max&auto=format&n=_qoyT92TVR_JeFMf&q=85&s=f5e62fd9004bb8b33c6dbb715a9a82d5" alt="Expo" />} href="/ui-kit/react-native/expo-integration">
    Expo managed workflow
  </Card>
</CardGroup>

***

## Explore

<CardGroup>
  <Card title="Components" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Features" icon="comments" href="/ui-kit/react-native/core-features">
    Chat, calling, AI, and extensions
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Colors, fonts, dark mode, and custom styling
  </Card>

  <Card title="Methods" icon="code" href="/ui-kit/react-native/methods">
    Initialize, authenticate, and send messages
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/react-native/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>

***

## Resources

<CardGroup>
  <Card title="Sample App" icon="github" href="https://github.com/cometchat/cometchat-uikit-react-native/tree/v5">
    Working reference app
  </Card>

  <Card title="Source Code" icon="code" href="https://github.com/cometchat/cometchat-uikit-react-native/tree/v5">
    Full UI Kit source on GitHub
  </Card>

  <Card title="Support" icon="headset" href="https://help.cometchat.com/hc/en-us/requests/new">
    Open a support ticket
  </Card>
</CardGroup>


# Property Changes
Source: https://www.cometchat.com/docs/ui-kit/react-native/property-changes

Comprehensive reference of new, renamed, and removed properties for each CometChat React Native UI Kit v5 component.

<Accordion title="AI Integration Quick Reference">
  | Field           | Value                                                                                                                    |
  | --------------- | ------------------------------------------------------------------------------------------------------------------------ |
  | Package         | `@cometchat/chat-uikit-react-native`                                                                                     |
  | Common renames  | `ListItemView` → `ItemView`, `TailView` → `TrailingView`, `EmptyStateView` → `EmptyView`, `ErrorStateView` → `ErrorView` |
  | Style changes   | `[component]Style` → `style` (e.g., `conversationsStyle` → `style`), all use `DeepPartial<>` types                       |
  | Migration guide | [Upgrading from V4](/docs/ui-kit/react-native/upgrading-from-v4)                                                              |
</Accordion>

## Conversations

### New Properties

| Name                                 | Type                                                                                    | Description                                                                               |
| ------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `hideSubmitButton`                   | boolean                                                                                 | Hide the submit (selection) button.                                                       |
| `receiptsVisibility`                 | boolean                                                                                 | Toggles message receipts (single/double-tick) inside the subtitle.                        |
| `disableSoundForMessages`            | boolean                                                                                 | Toggle sound playback for received messages.                                              |
| `customSoundForMessages`             | string                                                                                  | Custom sound file path for received messages.                                             |
| `datePattern`                        | `(conversation: CometChat.Conversation) => string`                                      | Function to generate a custom date string for a conversation.                             |
| `ItemView`                           | `(item: CometChat.Conversation) => JSX.Element`                                         | Completely overrides the default rendering of each conversation item in the list.         |
| `AppBarOptions`                      | `() => JSX.Element`                                                                     | Functional component for rendering options in the app bar.                                |
| `hideBackButton`                     | boolean                                                                                 | Hide the back button.                                                                     |
| `selectionMode`                      | `'none' \| 'single' \| 'multiple'`                                                      | Selection mode: `'none'`, `'single'`, or `'multiple'`.                                    |
| `onSelection`                        | `(conversations: Array<CometChat.Conversation>) => void`                                | Callback when conversation selection is complete.                                         |
| `onSubmit`                           | `(conversations: Array<CometChat.Conversation>) => void`                                | Callback when submit selection button is pressed.                                         |
| `EmptyView`                          | `() => JSX.Element`                                                                     | Custom view for the empty state.                                                          |
| `ErrorView`                          | `() => JSX.Element`                                                                     | Custom view for the error state.                                                          |
| `LoadingView`                        | `() => JSX.Element`                                                                     | Custom view for the loading state.                                                        |
| `conversationsRequestBuilder`        | `CometChat.ConversationsRequestBuilder`                                                 | Request builder to fetch conversations.                                                   |
| `LeadingView`                        | `(conversation: CometChat.Conversation) => JSX.Element`                                 | Custom leading view for a conversation item.                                              |
| `TitleView`                          | `(conversation: CometChat.Conversation) => JSX.Element`                                 | Custom title view for a conversation item.                                                |
| `SubtitleView`                       | `(conversation: CometChat.Conversation) => JSX.Element`                                 | Custom subtitle view for a conversation item.                                             |
| `TrailingView`                       | `(conversation: CometChat.Conversation) => JSX.Element`                                 | Custom tail view for a conversation item.                                                 |
| `hideError`                          | boolean                                                                                 | Hide error view.                                                                          |
| `onItemPress`                        | `(item: CometChat.Conversation) => void`                                                | Callback for when a conversation item is pressed.                                         |
| `onItemLongPress`                    | `(item: CometChat.Conversation) => void`                                                | Callback for when a conversation item is long pressed.                                    |
| `onError`                            | `(e: CometChat.CometChatException) => void`                                             | Callback when an error occurs while fetching conversations.                               |
| `onBack`                             | `() => void`                                                                            | Callback for when the back action is triggered.                                           |
| `textFormatters`                     | `Array<CometChatMentionsFormatter \| CometChatUrlsFormatter \| CometChatTextFormatter>` | Array of text formatter classes.                                                          |
| `style`                              | `DeepPartial<ConversationStyle>`                                                        | Custom styles for the conversation view.                                                  |
| `hideHeader`                         | boolean                                                                                 | Hide the header of the conversation list.                                                 |
| `onEmpty`                            | `() => void`                                                                            | Callback triggered when the fetched list is empty.                                        |
| `onLoad`                             | `(list: CometChat.Conversation[]) => void`                                              | Callback triggered once the users have loaded and are not empty.                          |
| `options`                            | `(conversation: CometChat.Conversation) => MenuItemInterface[]`                         | A function to replace the default menu items entirely for a conversation.                 |
| `addOptions`                         | `(conversation: CometChat.Conversation) => MenuItemInterface[]`                         | A function to append more menu items on top of the default menu items for a conversation. |
| `usersStatusVisibility`              | boolean                                                                                 | Toggle user status visibility.                                                            |
| `groupTypeVisibility`                | boolean                                                                                 | Toggle group type visibility.                                                             |
| `deleteConversationOptionVisibility` | boolean                                                                                 | Toggle delete conversation option visibility.                                             |

### Renamed Properties

| V4 Name                          | V5 Name                 | Type     | Description                                                                       |
| -------------------------------- | ----------------------- | -------- | --------------------------------------------------------------------------------- |
| `hideSubmitIcon`                 | `hideSubmitButton`      | boolean  | Hide the submit (selection) button.                                               |
| `disableUsersPresence`           | `usersStatusVisibility` | boolean  | Toggle user status visibility.                                                    |
| `hideReceipt` / `disableReceipt` | `receiptsVisibility`    | boolean  | Controls receipt visibility.                                                      |
| `tailView`                       | `TrailingView`          | function | Custom tail/trailing view for a conversation item.                                |
| `ListItemView`                   | `ItemView`              | function | Completely overrides the default rendering of each conversation item in the list. |
| `AppBarOption`                   | `AppBarOptions`         | function | Functional component for rendering options in the app bar.                        |
| `showBackButton`                 | `hideBackButton`        | boolean  | In v5, the prop is inverted (showBackButton=false → hideBackButton=true).         |
| `conversationsStyle`             | `style`                 | object   | Style object for conversations (renamed and type changed).                        |
| `EmptyStateView`                 | `EmptyView`             | function | Custom view for the empty state.                                                  |
| `ErrorStateView`                 | `ErrorView`             | function | Custom view for the error state.                                                  |
| `LoadingStateView`               | `LoadingView`           | function | Custom view for the loading state.                                                |

### Removed Properties

| V4 Name                         | Type      | Description                                              |
| ------------------------------- | --------- | -------------------------------------------------------- |
| `protectedGroupIcon`            | ImageType | Custom icon for protected group.                         |
| `privateGroupIcon`              | ImageType | Custom icon for private group.                           |
| `readIcon`                      | ImageType | Custom icon for read message.                            |
| `deliveredIcon`                 | ImageType | Custom icon for delivered message.                       |
| `sentIcon`                      | ImageType | Custom icon for sent message.                            |
| `errorIcon`                     | ImageType | Custom icon for error message.                           |
| `waitingIcon`                   | ImageType | Custom icon for waiting message.                         |
| `options (swipe actions)`       | function  | Pass array of `CometChatOptions` type for swipe actions. |
| `hideSeparator`                 | boolean   | Toggle separator.                                        |
| `backButtonIcon`                | ImageType | Icon for back button.                                    |
| `title`                         | string    | Title to be shown, default `"Chats"`.                    |
| `emptyStateText`                | string    | Text to be displayed if no conversation found.           |
| `errorStateText`                | string    | Text to be displayed if there is an error.               |
| `conversationsStyle (old type)` | object    | (Renamed to `style`, but if old type, it's removed).     |
| `listItemStyle`                 | object    | Style object for list item.                              |
| `avatarStyle`                   | object    | Style object for avatar.                                 |
| `statusIndicatorStyle`          | object    | Style object for status indicator.                       |
| `dateStyle`                     | object    | Style object for date.                                   |
| `receiptStyle`                  | object    | Style object for receipt.                                |
| `badgeStyle`                    | object    | Style object for badge.                                  |
| `confirmDialogStyle`            | object    | Style object for confirm dialog.                         |
| `disableTyping`                 | boolean   | Toggle typing indicator.                                 |
| `disableMentions`               | boolean   | If true, mentions will be disabled.                      |

## Users

### New Properties

| Name                     | Type                                            | Description                                                                       |
| ------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------- |
| `onSubmit`               | `(list: Array<CometChat.User>) => void`         | Callback when submit selection button is pressed.                                 |
| `style`                  | `DeepPartial<UserStyle>`                        | Custom styling for the users list.                                                |
| `TitleView`              | `(user: CometChat.User) => JSX.Element`         | Custom title view component.                                                      |
| `ItemView`               | `(user: CometChat.User) => JSX.Element`         | Function that returns a custom list item view.                                    |
| `EmptyView`              | `() => JSX.Element`                             | Custom component to display for the empty state.                                  |
| `ErrorView`              | `() => JSX.Element`                             | Custom component to display for the error state.                                  |
| `LoadingView`            | `() => JSX.Element`                             | Custom component to display for the loading state.                                |
| `LeadingView`            | `(user: CometChat.User) => JSX.Element`         | Custom leading view component.                                                    |
| `hideHeader`             | boolean                                         | Hide the header view.                                                             |
| `searchPlaceholderText`  | string                                          | Placeholder text for the search input.                                            |
| `usersStatusVisibility`  | boolean                                         | Hide the users status.                                                            |
| `searchKeyword`          | string                                          | Search keyword.                                                                   |
| `onError`                | `(e: CometChat.CometChatException) => void`     | Callback when an error occurs.                                                    |
| `hideLoadingState`       | boolean                                         | Hide the loading skeleton.                                                        |
| `title`                  | string                                          | Title for the header.                                                             |
| `addOptions`             | `(user: CometChat.User) => MenuItemInterface[]` | A function to append more menu items on top of the default menu items for a user. |
| `hideError`              | boolean                                         | Toggle error view visibility.                                                     |
| `showBackButton`         | boolean                                         | Toggle back button visibility.                                                    |
| `stickyHeaderVisibility` | boolean                                         | Toggle sticky header visibility.                                                  |

### Renamed Properties

| V4 Name                | V5 Name                 | Type     | Description                                              |
| ---------------------- | ----------------------- | -------- | -------------------------------------------------------- |
| `usersStyle`           | `style`                 | object   | Custom styling for the users list.                       |
| `TailView`             | `TrailingView`          | function | Function that returns a custom trailing view for a user. |
| `disableUsersPresence` | `usersStatusVisibility` | boolean  | Toggle user status visibility                            |
| `ListItemView`         | `ItemView`              | function | Function that returns a custom list item view.           |

### Removed Properties

| V4 Name       | Type | Description                          |
| ------------- | ---- | ------------------------------------ |
| `listItemKey` | any  | Key for list item *(removed in v5)*. |

## Groups

### New Properties

| Name                    | Type                                              | Description                                                                        |
| ----------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `TitleView`             | `(group: CometChat.Group) => JSX.Element`         | Custom title view for a group item.                                                |
| `SubtitleView`          | `(group: CometChat.Group) => JSX.Element`         | Custom subtitle view for a group item.                                             |
| `TrailingView`          | `(group: CometChat.Group) => JSX.Element`         | Custom trailing view for a group item.                                             |
| `ItemView`              | `(group: CometChat.Group) => JSX.Element`         | Completely overrides the default rendering of each group item in the list.         |
| `AppBarOptions`         | `() => JSX.Element`                               | Functional component for rendering options in the app bar.                         |
| `hideSubmitButton`      | boolean                                           | Hide the submit (selection) button.                                                |
| `style`                 | `DeepPartial<GroupStyle>`                         | Custom styles for the groups view.                                                 |
| `searchPlaceholderText` | string                                            | Placeholder text for the search input.                                             |
| `selectionMode`         | `'none' \| 'single' \| 'multiple'`                | Selection mode: `'none'`, `'single'`, or `'multiple'`.                             |
| `onSelection`           | `(list: Array<CometChat.Group>) => void`          | Callback when group selection is complete.                                         |
| `onSubmit`              | `(list: Array<CometChat.Group>) => void`          | Callback when submit selection button is pressed.                                  |
| `hideSearch`            | boolean                                           | Hide the search box.                                                               |
| `EmptyView`             | `() => JSX.Element`                               | Custom view for the empty state.                                                   |
| `ErrorView`             | `() => JSX.Element`                               | Custom view for the error state.                                                   |
| `LoadingView`           | `() => JSX.Element`                               | Custom view for the loading state.                                                 |
| `groupsRequestBuilder`  | `CometChat.GroupsRequestBuilder`                  | Request builder to fetch groups.                                                   |
| `searchRequestBuilder`  | `CometChat.GroupsRequestBuilder`                  | Request builder for search functionality.                                          |
| `privateGroupIcon`      | `ImageSourcePropType`                             | Icon to be used for private groups.                                                |
| `passwordGroupIcon`     | `ImageSourcePropType`                             | Icon to be used for password-protected groups.                                     |
| `hideError`             | boolean                                           | Hide error view.                                                                   |
| `onItemPress`           | `(item: CometChat.Group) => void`                 | Callback for when a group item is pressed.                                         |
| `onItemLongPress`       | `(item: CometChat.Group) => void`                 | Callback for when a group item is long pressed.                                    |
| `onError`               | `(e: CometChat.CometChatException) => void`       | Callback when an error occurs while fetching groups.                               |
| `onBack`                | `() => void`                                      | Callback for when the back action is triggered.                                    |
| `hideHeader`            | boolean                                           | Hide the header of the group list.                                                 |
| `LeadingView`           | `(group: CometChat.Group) => JSX.Element`         | Custom leading view for a group item.                                              |
| `searchKeyword`         | string                                            | Search keyword.                                                                    |
| `onEmpty`               | `() => void`                                      | Callback triggered when the fetched list is empty.                                 |
| `onLoad`                | `(list: CometChat.GroupMember[]) => void`         | Callback triggered once the groups have loaded and are not empty.                  |
| `hideLoadingState`      | boolean                                           | Hide the loading skeleton.                                                         |
| `groupTypeVisibility`   | boolean                                           | Hide the group type *(public/private/password)*.                                   |
| `addOptions`            | `(group: CometChat.Group) => MenuItemInterface[]` | A function to append more menu items on top of the default menu items for a group. |
| `options`               | `(group: CometChat.Group) => MenuItemInterface[]` | A function to replace the default menu items entirely for a group.                 |

### Renamed Properties

| V4 Name                 | V5 Name                 | Type                                | Description                                                                |
| ----------------------- | ----------------------- | ----------------------------------- | -------------------------------------------------------------------------- |
| `ListItemView`          | `ItemView`              | function                            | Completely overrides the default rendering of each group item in the list. |
| `AppBarOption`          | `AppBarOptions`         | function                            | Functional component for rendering options in the app bar.                 |
| `hideSubmitIcon`        | `hideSubmitButton`      | boolean                             | Hide the submit (selection) button.                                        |
| `groupsStyle`           | `style`                 | object                              | Style object for groups *(renamed and type changed)*.                      |
| `searchPlaceHolderText` | `searchPlaceholderText` | string                              | Placeholder text for the search input.                                     |
| `EmptyStateView`        | `EmptyView`             | function                            | Custom view for the empty state.                                           |
| `ErrorStateView`        | `ErrorView`             | function                            | Custom view for the error state.                                           |
| `LoadingStateView`      | `LoadingView`           | function                            | Custom view for the loading state.                                         |
| `privateGroupIcon`      | `privateGroupIcon`      | `ImageType` → `ImageSourcePropType` | Icon to be used for private groups *(type changed)*.                       |
| `passwordGroupIcon`     | `passwordGroupIcon`     | `ImageType` → `ImageSourcePropType` | Icon to be used for password-protected groups *(type changed)*.            |

### Removed Properties

| V4 Name                | Type      | Description                                                               |
| ---------------------- | --------- | ------------------------------------------------------------------------- |
| `hideSeperator`        | boolean   | Toggle separator *(removed, not present in v5)*.                          |
| `listItemStyle`        | object    | Style object for list item *(removed, not present in v5)*.                |
| `avatarStyle`          | object    | Style object for avatar *(removed, not present in v5)*.                   |
| `statusIndicatorStyle` | object    | Style object for status indicator *(removed, not present in v5)*.         |
| `backButtonIcon`       | ImageType | Icon for back button *(removed, not present in v5)*.                      |
| `searchBoxIcon`        | ImageType | Icon for search box *(removed, not present in v5)*.                       |
| `title`                | string    | Title to be shown, default `"Groups"` *(removed, not present in v5)*.     |
| `emptyStateText`       | string    | Text to be displayed if no group found *(removed, not present in v5)*.    |
| `errorStateText`       | string    | Text to be displayed if there is an error *(removed, not present in v5)*. |

## Group Members

### New Properties

| Name                        | Type                                                                             | Description                                                                         |
| --------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `SubtitleView`              | `(item: CometChat.GroupMember) => JSX.Element`                                   | Custom subtitle view for a group member item.                                       |
| `TitleView`                 | `(item: CometChat.GroupMember) => JSX.Element`                                   | Custom title view for a group member item.                                          |
| `TrailingView`              | `(item: CometChat.GroupMember) => JSX.Element`                                   | Custom trailing view for a group member item.                                       |
| `EmptyView`                 | `() => JSX.Element`                                                              | Custom view for the empty state.                                                    |
| `ErrorView`                 | `() => JSX.Element`                                                              | Custom view for the error state.                                                    |
| `LoadingView`               | `() => JSX.Element`                                                              | Custom view for the loading state.                                                  |
| `onItemPress`               | `(groupMember: CometChat.GroupMember) => void`                                   | Callback when a group member item is pressed.                                       |
| `onItemLongPress`           | `(groupMember: CometChat.GroupMember) => void`                                   | Callback when a group member item is long pressed.                                  |
| `onSelection`               | `(list: CometChat.GroupMember[]) => void`                                        | Callback when group member selection is complete.                                   |
| `onSubmit`                  | `(list: Array<CometChat.GroupMember>) => void`                                   | Callback when submit selection button is pressed.                                   |
| `searchRequestBuilder`      | `CometChat.GroupMembersRequestBuilder`                                           | Request builder for search functionality.                                           |
| `groupMemberRequestBuilder` | `CometChat.GroupMembersRequestBuilder`                                           | Request builder to fetch group members.                                             |
| `group`                     | `CometChat.Group`                                                                | The group object for which members are listed.                                      |
| `style`                     | `DeepPartial<GroupMemberStyle>`                                                  | Custom styles for the group member view.                                            |
| `ItemView`                  | `(item: CometChat.GroupMember) => JSX.Element`                                   | Completely overrides the default rendering of each group member item.               |
| `LeadingView`               | `(item: CometChat.GroupMember) => JSX.Element`                                   | Custom leading view for a group member item.                                        |
| `onEmpty`                   | `() => void`                                                                     | Callback triggered when the fetched list is empty.                                  |
| `onLoad`                    | `(list: CometChat.GroupMember[]) => void`                                        | Callback triggered once the group members have loaded and are not empty.            |
| `options`                   | `(member: CometChat.GroupMember, group: CometChat.Group) => MenuItemInterface[]` | Function to replace default menu items entirely for a group member.                 |
| `addOptions`                | `(member: CometChat.GroupMember, group: CometChat.Group) => MenuItemInterface[]` | Function to append more menu items on top of default menu items for a group member. |
| `hideKickMemberOption`      | `boolean`                                                                        | Hide the "Remove" (Kick) option from the default menu.                              |
| `hideBanMemberOption`       | `boolean`                                                                        | Hide the "Ban" option from the default menu.                                        |
| `hideScopeChangeOption`     | `boolean`                                                                        | Hide the "Change Scope" option from the default menu.                               |
| `hideLoadingState`          | `boolean`                                                                        | Hide the loading skeleton.                                                          |
| `usersStatusVisibility`     | `boolean`                                                                        | Toggle user status visibility.                                                      |
| `hideHeader`                | `boolean`                                                                        | Hide the header view.                                                               |
| `onError`                   | `() => void`                                                                     | Callback when an error occurs.                                                      |
| `searchKeyword`             | `string`                                                                         | Search keyword.                                                                     |
| `showBackButton`            | `boolean`                                                                        | Toggle back button visibility.                                                      |
| `excludeOwner`              | `boolean`                                                                        | Exclude owner from the list.                                                        |

### Renamed Properties

| V4 Name                | V5 Name                 | Type     | Description                                                           |
| ---------------------- | ----------------------- | -------- | --------------------------------------------------------------------- |
| `TailView`             | `TrailingView`          | function | Custom trailing view for a group member item.                         |
| `groupMemberStyle`     | `style`                 | object   | Style object for group member (renamed and type changed).             |
| `disableUsersPresence` | `usersStatusVisibility` | boolean  | Toggle user status visibility                                         |
| `ListItemView`         | `ItemView`              | function | Completely overrides the default rendering of each group member item. |
| `EmptyStateView`       | `EmptyView`             | function | Custom view for the empty state.                                      |
| `ErrorStateView`       | `ErrorView`             | function | Custom view for the error state.                                      |
| `LoadingStateView`     | `LoadingView`           | function | Custom view for the loading state.                                    |

### Removed Properties

| V4 Name                | Type             | Description                                                            |
| ---------------------- | ---------------- | ---------------------------------------------------------------------- |
| `listItemStyle`        | object           | Style object for list item *(removed in v5)*.                          |
| `avatarStyle`          | object           | Style object for avatar *(removed in v5)*.                             |
| `statusIndicatorStyle` | object           | Style object for status indicator *(removed in v5)*.                   |
| `groupScopeStyle`      | object           | Styling properties for group scope *(removed in v5)*.                  |
| `title`                | string           | Title for the list *(removed in v5)*.                                  |
| `errorStateText`       | string           | Text to be displayed when error occurs *(removed in v5)*.              |
| `emptyStateText`       | string           | Text to be displayed when the list is empty *(removed in v5)*.         |
| `theme`                | `CometChatTheme` | Theme configuration for the group members component *(removed in v5)*. |

***

## Message Header

### New Properties

| Name                       | Type                                                                                   | Description                                                                          |
| -------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `ItemView`                 | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element` | Custom item view. Receives `{ user, group }`.                                        |
| `LeadingView`              | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element` | Custom leading view. Receives `{ user, group }`.                                     |
| `TitleView`                | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element` | Custom title view. Receives `{ user, group }`.                                       |
| `SubtitleView`             | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element` | Custom subtitle view. Receives `{ user, group }`.                                    |
| `TrailingView`             | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element` | Custom trailing view. Receives `{ user, group }`.                                    |
| `AuxiliaryButtonView`      | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element` | Custom auxiliary button view. Receives `{ user, group }`.                            |
| `user`                     | `CometChat.User`                                                                       | User object.                                                                         |
| `group`                    | `CometChat.Group`                                                                      | Group object.                                                                        |
| `showBackButton`           | `boolean`                                                                              | Toggle back button visibility.                                                       |
| `onBack`                   | `() => void`                                                                           | Callback when back button is pressed.                                                |
| `style`                    | `DeepPartial<MessageHeaderStyle>`                                                      | Custom styles.                                                                       |
| `onError`                  | `(error: CometChat.CometChatException) => void`                                        | Error callback.                                                                      |
| `hideVoiceCallButton`      | `boolean`                                                                              | Toggle visibility of voice call button.                                              |
| `hideVideoCallButton`      | `boolean`                                                                              | Toggle visibility of video call button.                                              |
| `usersStatusVisibility`    | `boolean`                                                                              | Toggle visibility of user status.                                                    |
| `hideNewChatButton`        | `boolean`                                                                              | Flag to hide the new chat button for AI agents (only applies to @agentic users).     |
| `hideChatHistoryButton`    | `boolean`                                                                              | Flag to hide the chat history button for AI agents (only applies to @agentic users). |
| `onNewChatButtonClick`     | `() => void`                                                                           | Callback when agent new chat button is clicked (only applies to @agentic users).     |
| `onChatHistoryButtonClick` | `() => void`                                                                           | Callback when agent chat history button is clicked (only applies to @agentic users). |

### Renamed Properties

| V4 Name                | V5 Name                 | Type     | Description                                                             |
| ---------------------- | ----------------------- | -------- | ----------------------------------------------------------------------- |
| `ListItemView`         | `ItemView`              | function | Custom item view.                                                       |
| `AppBarOptions`        | `TrailingView`          | function | Custom trailing view.                                                   |
| `hideBackIcon`         | `showBackButton`        | boolean  | In v5, the prop is inverted (hideBackIcon=true → showBackButton=false). |
| `disableUsersPresence` | `usersStatusVisibility` | boolean  | Toggle user status visibility                                           |
| `style`                | `style`                 | object   | Style object for message header (renamed and type changed).             |

### Removed Properties

| V4 Name                  | Type        | Description                                                               |
| ------------------------ | ----------- | ------------------------------------------------------------------------- |
| `protectedGroupIcon`     | `ImageType` | Custom icon for protected group *(removed in v5)*.                        |
| `privateGroupIcon`       | `ImageType` | Custom icon for private group *(removed in v5)*.                          |
| `backButtonIcon`         | `ImageType` | Icon for back button *(removed in v5)*.                                   |
| `disableTyping`          | `boolean`   | Controls typing indicator functionality *(removed in v5)*.                |
| `avatarStyle`            | `object`    | Style configuration for avatar *(removed in v5)*.                         |
| `statusIndicatorStyle`   | `object`    | Style configuration for status indicator *(removed in v5)*.               |
| `headViewContainerStyle` | `object`    | Custom styling for headViewContainer in list item *(removed in v5)*.      |
| `bodyViewContainerStyle` | `object`    | Custom styling for bodyViewContainerStyle in list item *(removed in v5)*. |
| `tailViewContainerStyle` | `object`    | Custom styling for tailViewContainerStyle in list item *(removed in v5)*. |
| `listItemStyle`          | `object`    | Custom styling for list item *(removed in v5)*.                           |

## Message List

### New Properties

| Name                          | Type                                                                                                                                                       | Description                                                                              |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `parentMessageId`             | `string`                                                                                                                                                   | ID of the parent message when rendering threaded messages.                               |
| `user`                        | `CometChat.User`                                                                                                                                           | The user object associated with the message list.                                        |
| `group`                       | `CometChat.Group`                                                                                                                                          | The group object associated with the message list.                                       |
| `EmptyView`                   | `() => JSX.Element`                                                                                                                                        | A component to display when there are no messages.                                       |
| `ErrorView`                   | `() => JSX.Element`                                                                                                                                        | A component to display when an error occurs.                                             |
| `hideError`                   | `boolean`                                                                                                                                                  | Flag to hide the error view.                                                             |
| `LoadingView`                 | `() => JSX.Element`                                                                                                                                        | A component to display while messages are loading.                                       |
| `receiptsVisibility`          | `boolean`                                                                                                                                                  | Flag to hide read receipts.                                                              |
| `disableSoundForMessages`     | `boolean`                                                                                                                                                  | Flag to disable sound for incoming messages.                                             |
| `customSoundForMessages`      | `string`                                                                                                                                                   | Custom sound URL for messages.                                                           |
| `alignment`                   | `MessageListAlignmentType`                                                                                                                                 | Alignment type for the message list.                                                     |
| `avatarVisibility`            | `boolean`                                                                                                                                                  | Flag to show or hide the user's avatar.                                                  |
| `datePattern`                 | `(message: CometChat.BaseMessage) => string`                                                                                                               | Function that returns a custom string representation for a message's date.               |
| `dateSeparatorPattern`        | `(date: number) => string`                                                                                                                                 | Function that returns a custom date separator string based on a timestamp.               |
| `templates`                   | `Array<CometChatMessageTemplate>`                                                                                                                          | An array of message templates for rendering custom message types.                        |
| `addTemplates`                | `Array<CometChatMessageTemplate>`                                                                                                                          | An array of message templates for rendering custom message types.                        |
| `messageRequestBuilder`       | `CometChat.MessagesRequestBuilder`                                                                                                                         | Builder for constructing a request to fetch messages.                                    |
| `scrollToBottomOnNewMessages` | `boolean`                                                                                                                                                  | If true, the message list will scroll to the bottom when new messages arrive.            |
| `onThreadRepliesPress`        | `(messageObject: CometChat.BaseMessage, messageBubbleView: () => JSX.Element \| null) => void`                                                             | Callback invoked when the thread replies view is pressed.                                |
| `HeaderView`                  | `({ user, group, id }: { user?: CometChat.User; group?: CometChat.Group; id?: { uid?: string; guid?: string; parentMessageId?: string } }) => JSX.Element` | Custom header view component.                                                            |
| `FooterView`                  | `({ user, group, id }: { user?: CometChat.User; group?: CometChat.Group; id?: { uid?: string; guid?: string; parentMessageId?: string } }) => JSX.Element` | Custom footer view component.                                                            |
| `onError`                     | `(e: CometChat.CometChatException) => void`                                                                                                                | Callback to handle errors.                                                               |
| `onBack`                      | `() => void`                                                                                                                                               | Callback invoked on back navigation.                                                     |
| `textFormatters`              | `Array<CometChatMentionsFormatter \| CometChatUrlsFormatter \| CometChatTextFormatter>`                                                                    | Collection of text formatter classes to apply custom formatting.                         |
| `onReactionPress`             | `(reaction: CometChat.ReactionCount, messageObject: CometChat.BaseMessage) => void`                                                                        | Callback invoked when a reaction is pressed.                                             |
| `onReactionLongPress`         | `(reaction: CometChat.ReactionCount, messageObject: CometChat.BaseMessage) => void`                                                                        | Callback invoked when a reaction is long pressed.                                        |
| `onReactionListItemPress`     | `(messageReaction: CometChat.Reaction, messageObject: CometChat.BaseMessage) => void`                                                                      | Callback invoked when an item in the reaction list is pressed.                           |
| `style`                       | `DeepPartial<CometChatTheme["messageListStyles"]>`                                                                                                         | Custom styles for the message list component.                                            |
| `reactionsRequestBuilder`     | `CometChat.ReactionsRequestBuilder`                                                                                                                        | Builder for constructing a request to fetch reactions.                                   |
| `onAddReactionPress`          | `() => void`                                                                                                                                               | Callback invoked when the add reaction button is pressed.                                |
| `quickReactionList`           | `[string, string?, string?, string?, string?]`                                                                                                             | List of quick reactions.                                                                 |
| `onLoad`                      | `(messageList: CometChat.BaseMessage[]) => void`                                                                                                           | Callback to handle when the message list is loaded.                                      |
| `onEmpty`                     | `() => void`                                                                                                                                               | Callback to handle when the message list is empty.                                       |
| `hideReplyInThreadOption`     | `boolean`                                                                                                                                                  | Flag to hide the reply in thread option.                                                 |
| `hideShareMessageOption`      | `boolean`                                                                                                                                                  | Flag to hide the share message option.                                                   |
| `hideEditMessageOption`       | `boolean`                                                                                                                                                  | Flag to hide the edit message option.                                                    |
| `hideTranslateMessageOption`  | `boolean`                                                                                                                                                  | Flag to hide the translate message option.                                               |
| `hideDeleteMessageOption`     | `boolean`                                                                                                                                                  | Flag to hide the delete message option.                                                  |
| `hideReactionOption`          | `boolean`                                                                                                                                                  | Flag to hide the react to message option.                                                |
| `hideMessagePrivatelyOption`  | `boolean`                                                                                                                                                  | Flag to hide the message privately option.                                               |
| `hideCopyMessageOption`       | `boolean`                                                                                                                                                  | Flag to hide the copy message option.                                                    |
| `hideMessageInfoOption`       | `boolean`                                                                                                                                                  | Flag to hide the message info option.                                                    |
| `hideGroupActionMessages`     | `boolean`                                                                                                                                                  | Flag to hide group action messages.                                                      |
| `hideTimestamp`               | `boolean`                                                                                                                                                  | Flag to hide the timestamp on message bubbles.                                           |
| `suggestedMessages`           | `Array<string>`                                                                                                                                            | Array of suggested messages for AI agent empty view (only applies to @agentic users).    |
| `hideSuggestedMessages`       | `boolean`                                                                                                                                                  | Flag to hide suggested messages in AI agent empty view (only applies to @agentic users). |
| `emptyChatGreetingView`       | `React.ReactNode`                                                                                                                                          | Custom AI agent greeting view (only applies to @agentic users).                          |
| `emptyChatIntroMessageView`   | `React.ReactNode`                                                                                                                                          | Custom AI agent intro message view (only applies to @agentic users).                     |
| `emptyChatImageView`          | `React.ReactNode`                                                                                                                                          | Custom AI agent image/avatar view (only applies to @agentic users).                      |
| `onSuggestedMessageClick`     | `(suggestion: string) => void`                                                                                                                             | Callback when suggested message is clicked (only applies to @agentic users).             |
| `aiAssistantTools`            | `CometChatAIAssistantTools`                                                                                                                                | Custom AI assistant tools with action functions (only applies to @agentic users).        |
| `streamingSpeed`              | `number`                                                                                                                                                   | Controls the speed of AI message streaming (only applies to @agentic users).             |

### Renamed Properties

| V4 Name                          | V5 Name                | Type                       | Description                                        |
| -------------------------------- | ---------------------- | -------------------------- | -------------------------------------------------- |
| `EmptyStateView`                 | `EmptyView`            | `() => JSX.Element`        | Custom component to display for the empty state.   |
| `ErrorStateView`                 | `ErrorView`            | `() => JSX.Element`        | Custom component to display for the error state.   |
| `LoadingStateView`               | `LoadingView`          | `() => JSX.Element`        | Custom component to display for the loading state. |
| `hideReceipt` / `disableReceipt` | `receiptsVisibility`   | `boolean`                  | Controls receipt visibility.                       |
| `showAvatar`                     | `avatarVisibility`     | `boolean`                  | Toggle visibility for avatar.                      |
| `dateSeparatorPattern`           | `dateSeparatorPattern` | `(date: number) => string` | Signature clarified with parameter name.           |

### Removed Properties

| V4 Name                           | Type                                                | Description                                |
| --------------------------------- | --------------------------------------------------- | ------------------------------------------ |
| `emptyStateText`                  | `string`                                            | Text to be displayed if no message found.  |
| `errorStateText`                  | `string`                                            | Text to be displayed if there is an error. |
| `readIcon`                        | `ImageType`                                         | Custom icon for read message.              |
| `deliveredIcon`                   | `ImageType`                                         | Custom icon for delivered message.         |
| `sentIcon`                        | `ImageType`                                         | Custom icon for sent message.              |
| `waitIcon`                        | `ImageType`                                         | Custom icon for waiting message.           |
| `errorIcon`                       | `ImageType`                                         | Custom icon for error message.             |
| `wrapperMessageBubbleStyle`       | `MessageBubbleStyleInterface`                       | Style for message bubble wrapper.          |
| `avatarStyle`                     | `AvatarStyleInterface`                              | Style configuration for avatar.            |
| `dateSeperatorStyle`              | `DateStyleInterface`                                | Style for date separator.                  |
| `actionSheetStyle`                | `ActionSheetStylesInterface`                        | Style for action sheet.                    |
| `messageListStyle`                | `MessageListStyleInterface`                         | Style configuration for message list.      |
| `messageInformationConfiguration` | `CometChatMessageInformationConfigurationInterface` | Configuration for message information.     |
| `reactionsConfiguration`          | `ReactionsConfigurationInterface`                   | Message Reaction Configuration.            |
| `reactionListConfiguration`       | `ReactionListConfigurationInterface`                | Message Reaction List Configuration.       |
| `quickReactionConfiguration`      | `QuickReactionsConfigurationInterface`              | Quick Reaction Configuration.              |
| `emojiKeyboardStyle`              | `EmojiKeyboardStyle`                                | Emoji Keyboard style.                      |
| `disableReactions`                | `boolean`                                           | Disables the reactions functionality.      |
| `disableMentions`                 | `boolean`                                           | Disables mentions functionality.           |
| `timeStampAlignment`              | `MessageTimeAlignmentType`                          | Alignment for message timestamps.          |
| `newMessageIndicatorText`         | `string`                                            | Custom text for new message indicator.     |
| `hideActionSheetHeader`           | `boolean`                                           | Hide the header of the action sheet.       |

## Message Composer

### New Properties

| Name                                | Type                                                                                                                                                | Description                                                                                |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `id`                                | `string \| number`                                                                                                                                  | Message composer identifier.                                                               |
| `user`                              | `CometChat.User`                                                                                                                                    | CometChat SDK’s user object.                                                               |
| `group`                             | `CometChat.Group`                                                                                                                                   | CometChat SDK’s group object.                                                              |
| `disableSoundForOutgoingMessages`   | `boolean`                                                                                                                                           | Flag to turn off sound for outgoing messages.                                              |
| `customSoundForOutgoingMessage`     | `any`                                                                                                                                               | Custom audio sound to be played while sending messages.                                    |
| `disableTypingEvents`               | `boolean`                                                                                                                                           | Flag to disable typing events.                                                             |
| `initialComposertext`               | `string`                                                                                                                                            | Initial text to be displayed in the composer.                                              |
| `HeaderView`                        | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element`                                                              | Renders a preview section at the top of the composer.                                      |
| `onTextChange`                      | `(text: string) => void`                                                                                                                            | Callback triggered when the input text changes.                                            |
| `attachmentOptions`                 | `({ user, group, composerId }: { user?: CometChat.User; group?: CometChat.Group; composerId: Map<any, any>; }) => CometChatMessageComposerAction[]` | Returns the attachment options for the composer.                                           |
| `AuxiliaryButtonView`               | `({ user, group, composerId }: { user?: CometChat.User; group?: CometChat.Group; composerId: string \| number; }) => JSX.Element`                   | Replaces the default Auxiliary Button.                                                     |
| `SendButtonView`                    | `({ user, group, composerId }: { user?: CometChat.User; group?: CometChat.Group; composerId: string \| number; }) => JSX.Element`                   | Replaces the default Send Button.                                                          |
| `parentMessageId`                   | `string \| number`                                                                                                                                  | Message id required for threaded messages.                                                 |
| `style`                             | `DeepPartial<CometChatTheme["messageComposerStyles"]>`                                                                                              | Custom styles for the message composer component.                                          |
| `hideVoiceRecordingButton`          | `boolean`                                                                                                                                           | Flag to hide the voice recording button.                                                   |
| `onSendButtonPress`                 | `(message: CometChat.BaseMessage) => void`                                                                                                          | Callback triggered when the send button is pressed.                                        |
| `onError`                           | `(error: CometChat.CometChatException) => void`                                                                                                     | Callback triggered when an error occurs.                                                   |
| `keyboardAvoidingViewProps`         | `KeyboardAvoidingViewProps`                                                                                                                         | Override properties for the KeyboardAvoidingView.                                          |
| `textFormatters`                    | `Array<CometChatMentionsFormatter \| CometChatUrlsFormatter \| CometChatTextFormatter>`                                                             | Collection of text formatter classes to apply custom formatting.                           |
| `disableMentions`                   | `boolean`                                                                                                                                           | Flag to disable mention functionality.                                                     |
| `imageQuality`                      | `IntRange<1, 100>`                                                                                                                                  | Controls image quality when taking pictures from the camera.                               |
| `hideCameraOption`                  | `boolean`                                                                                                                                           | If true, hides the camera option from the attachment options.                              |
| `hideImageAttachmentOption`         | `boolean`                                                                                                                                           | If true, hides the image attachment option from the attachment options.                    |
| `hideVideoAttachmentOption`         | `boolean`                                                                                                                                           | If true, hides the video attachment option from the attachment options.                    |
| `hideAudioAttachmentOption`         | `boolean`                                                                                                                                           | If true, hides the audio attachment option from the attachment options.                    |
| `hideFileAttachmentOption`          | `boolean`                                                                                                                                           | If true, hides the file/document attachment option from the attachment options.            |
| `hidePollsAttachmentOption`         | `boolean`                                                                                                                                           | If true, hides the polls option from the attachment options.                               |
| `hideCollaborativeDocumentOption`   | `boolean`                                                                                                                                           | If true, hides the collaborative document option.                                          |
| `hideCollaborativeWhiteboardOption` | `boolean`                                                                                                                                           | If true, hides the collaborative whiteboard option.                                        |
| `hideAttachmentButton`              | `boolean`                                                                                                                                           | If true, hides the entire attachment button from the composer.                             |
| `hideStickersButton`                | `boolean`                                                                                                                                           | If true, hides the stickers button from the composer.                                      |
| `hideSendButton`                    | `boolean`                                                                                                                                           | If true, hides the send button from the composer.                                          |
| `hideAuxiliaryButtons`              | `boolean`                                                                                                                                           | If true, hides all auxiliary buttons (such as voice input, GIFs, or other plugin buttons). |
| `addAttachmentOptions`              | `({ user, group, composerId }: { user?: CometChat.User; group?: CometChat.Group; composerId: Map<any, any>; }) => CometChatMessageComposerAction[]` | Returns additional attachment options for the composer.                                    |
| `auxiliaryButtonsAlignment`         | `"left" \| "right"`                                                                                                                                 | Determines the alignment of auxiliary buttons.                                             |

### Renamed Properties

| V4 Name                   | V5 Name                           | Type                       | Description                             |
| ------------------------- | --------------------------------- | -------------------------- | --------------------------------------- |
| `disableSoundForMessages` | `disableSoundForOutgoingMessages` | `boolean`                  | Renamed for clarity.                    |
| `customSoundForMessage`   | `customSoundForOutgoingMessage`   | `any`                      | Renamed for clarity.                    |
| `text`                    | `initialComposertext`             | `string`                   | Renamed for clarity.                    |
| `onChangeText`            | `onTextChange`                    | `(text: string) => void`   | Renamed for clarity.                    |
| `hideVoiceRecording`      | `hideVoiceRecordingButton`        | `boolean`                  | Renamed for clarity.                    |
| `attachmentOptions`       | `attachmentOptions`               | function signature changed | Function signature updated.             |
| `SecondaryButtonView`     | `AuxiliaryButtonView`             | function signature changed | Function signature updated and renamed. |

### Removed Properties

| V4 Name                 | Type                            | Description                                                 |
| ----------------------- | ------------------------------- | ----------------------------------------------------------- |
| `FooterView`            | `React.FC`                      | Preview section at the bottom of the composer.              |
| `placeHolderText`       | `string`                        | Text shown in the composer when the input message is empty. |
| `maxHeight`             | `number`                        | Threshold value for input expansion.                        |
| `attachmentIcon`        | `ImageType`                     | Attachment icon.                                            |
| `messageComposerStyle`  | `MessageComposerStyleInterface` | Message Composer Styles.                                    |
| `hideLiveReaction`      | `boolean`                       | Hide the live reaction button.                              |
| `liveReactionIcon`      | `ImageType`                     | Live reaction icon.                                         |
| `voiceRecordingIconURL` | `string \| ImageType`           | Image URL for the voice recording icon.                     |
| `mediaRecorderStyle`    | `MediaRecorderStyle`            | Voice Recording Styles.                                     |
| `pauseIconUrl`          | `ImageType`                     | Pause icon.                                                 |
| `playIconUrl`           | `ImageType`                     | Play icon.                                                  |
| `recordIconUrl`         | `ImageType`                     | Record icon.                                                |
| `deleteIconUrl`         | `ImageType`                     | Delete icon.                                                |
| `stopIconUrl`           | `ImageType`                     | Stop icon.                                                  |
| `submitIconUrl`         | `ImageType`                     | Submit icon.                                                |
| `AIIconURL`             | `string`                        | AI Icon URL.                                                |
| `aiOptionsStyle`        | `AIOptionsStyle`                | AI Options Style.                                           |

## Incoming Call

### New Properties

| Name                   | Type                                                               | Description                                                       |
| ---------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------- |
| `call`                 | `CometChat.Call \| CometChat.CustomMessage \| any`                 | The incoming call object, which can be a Call or a CustomMessage. |
| `ItemView`             | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the entire call item.                             |
| `TitleView`            | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the title section of the call item.               |
| `SubtitleView`         | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the subtitle section of the call item.            |
| `LeadingView`          | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the leading section of the call item.             |
| `TrailingView`         | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the trailing section of the call item.            |
| `disableSoundForCalls` | `boolean`                                                          | Flag to disable sound for incoming calls.                         |
| `customSoundForCalls`  | `string`                                                           | Path or identifier for a custom sound to play for incoming calls. |
| `onAccept`             | `(message: CometChat.BaseMessage) => void`                         | Callback fired when the call is accepted.                         |
| `onDecline`            | `(message: CometChat.BaseMessage) => void`                         | Callback fired when the call is declined.                         |
| `onError`              | `(e: CometChat.CometChatException) => void`                        | Callback fired when an error occurs.                              |
| `callSettingsBuilder`  | `typeof CometChatCalls.CallSettingsBuilder`                        | Optional custom call settings builder.                            |
| `style`                | `DeepPartial<IncomingCallStyle>`                                   | Custom style overrides for the incoming call component.           |

### Renamed Properties

| V4 Name             | V5 Name        | Type                                                            | Description                                                |
| ------------------- | -------------- | --------------------------------------------------------------- | ---------------------------------------------------------- |
| `SubtitleView`      | `SubtitleView` | function signature changed                                      | Function signature updated.                                |
| `incomingCallStyle` | `style`        | `IncomingCallStyleInterface` → `DeepPartial<IncomingCallStyle>` | Style object for incoming call (renamed and type changed). |
| `onAccept`          | `onAccept`     | function signature changed                                      | Function signature updated.                                |
| `onDecline`         | `onDecline`    | function signature changed                                      | Function signature updated.                                |

### Removed Properties

| V4 Name                  | Type                        | Description                     |
| ------------------------ | --------------------------- | ------------------------------- |
| `title`                  | `string`                    | Custom title text.              |
| `acceptButtonText`       | `string`                    | Accept button text.             |
| `declineButtonText`      | `string`                    | Decline button text.            |
| `avatarStyle`            | `AvatarStyleInterface`      | Style configuration for avatar. |
| `ongoingCallScreenStyle` | `OngoingCallStyleInterface` | Style for ongoing call screen.  |

## Outgoing Call

### New Properties

| Name                     | Type                                                               | Description                                         |
| ------------------------ | ------------------------------------------------------------------ | --------------------------------------------------- |
| `onEndCallButtonPressed` | `(call: CometChat.Call) => void`                                   | Callback for when the end/cancel button is pressed. |
| `EndCallView`            | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the end call button.                |
| `TitleView`              | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the title section.                  |
| `SubtitleView`           | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the subtitle section.               |
| `AvatarView`             | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the avatar section.                 |

### Renamed Properties

| V4 Name                  | V5 Name                  | Type                                                                             | Description                             |
| ------------------------ | ------------------------ | -------------------------------------------------------------------------------- | --------------------------------------- |
| `onDeclineButtonPressed` | `onEndCallButtonPressed` | `(call: CometChat.Call) => void`                                                 | Renamed for clarity and consistency.    |
| `declineButtonIcon`      | `EndCallView`            | `ImageType` → `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Changed from icon/image to custom view. |
| `declineButtonText`      | `EndCallView`            | `string` → `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element`    | Changed from text to custom view.       |
| `outgoingCallStyle`      | `style`                  | `OutgoingCallStyleInterface` → `DeepPartial<OutgoingCallStyle>`                  | Style object renamed and type changed.  |

### Removed Properties

| V4 Name                    | Type                                        | Description                                           |
| -------------------------- | ------------------------------------------- | ----------------------------------------------------- |
| `buttonStyle`              | `ButtonStyleInterface`                      | Style object for button (removed, not present in v5). |
| `avatarStyle`              | `AvatarStyleInterface`                      | Style object for avatar (removed, not present in v5). |
| `declineButtonText`        | `string`                                    | Decline button text (replaced by `EndCallView`).      |
| `declineButtonIcon`        | `ImageType`                                 | Decline button icon (replaced by `EndCallView`).      |
| `onDeclineButtonPressed`   | `(call: CometChat.Call) => void`            | Callback (renamed to `onEndCallButtonPressed`).       |
| `outgoingCallStyle`        | `OutgoingCallStyleInterface`                | Style object (renamed to `style`).                    |
| `callSettingsBuilder`      | `typeof CometChatCalls.CallSettingsBuilder` | (Moved to new properties, type clarified).            |
| `theme`                    | `CometChatTheme`                            | Theme configuration (removed, not present in v5).     |
| `cardStyle`                | `CardStyleInterface`                        | Card style (removed, not present in v5).              |
| `ongoingCallConfiguration` | `OngoingCallConfigurationInterface`         | Ongoing call config (removed, not present in v5).     |

## Call Buttons

### New Properties

| Name                        | Type                                                                                                                   | Description                                              |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `callSettingsBuilder`       | `(user?: CometChat.User, group?: CometChat.Group, isAudioOnly?: boolean) => typeof CometChatCalls.CallSettingsBuilder` | Function to build call settings for call initialization. |
| `outgoingCallConfiguration` | `OutgoingCallConfiguration`                                                                                            | Configuration for outgoing calls.                        |
| `style`                     | `DeepPartial<CallButtonStyle>`                                                                                         | Custom style overrides for the call button.              |

### Renamed Properties

| V4 Name           | V5 Name               | Type                                                        | Description                            |
| ----------------- | --------------------- | ----------------------------------------------------------- | -------------------------------------- |
| `hideVoiceCall`   | `hideVoiceCallButton` | `boolean`                                                   | Renamed for clarity.                   |
| `hideVideoCall`   | `hideVideoCallButton` | `boolean`                                                   | Renamed for clarity.                   |
| `callButtonStyle` | `style`               | `CallButtonStyleInterface` → `DeepPartial<CallButtonStyle>` | Style object renamed and type changed. |

### Removed Properties

| V4 Name              | Type                                                                   | Description                         |
| -------------------- | ---------------------------------------------------------------------- | ----------------------------------- |
| `voiceCallIconImage` | `ImageType`                                                            | Image icon for voice calls.         |
| `voiceCallIconText`  | `string`                                                               | Text label for the voice call icon. |
| `videoCallIconImage` | `ImageType`                                                            | Image icon for video calls.         |
| `videoCallIconText`  | `string`                                                               | Text label for the video call icon. |
| `onVoiceCallPress`   | `(params: { user?: CometChat.User, group?: CometChat.Group }) => void` | Callback for voice call icon click. |
| `onVideoCallPress`   | `(params: { user?: CometChat.User, group?: CometChat.Group }) => void` | Callback for video call icon click. |
| `callButtonStyle`    | `CallButtonStyleInterface`                                             | Style object (renamed to `style`).  |

## Call Logs

### New Properties

| Name                        | Type                                               | Description                                                             |
| --------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------- |
| `LeadingView`               | `(call?: any) => JSX.Element`                      | Custom component for the leading view of each call log item.            |
| `TitleView`                 | `(call?: any) => JSX.Element`                      | Custom component for the title view of each call log item.              |
| `SubtitleView`              | `(call?: any) => JSX.Element`                      | Custom component for the subtitle view of each call log item.           |
| `ItemView`                  | `(call?: any) => JSX.Element`                      | Custom component for the entire call log item.                          |
| `TrailingView`              | `(call?: any) => JSX.Element`                      | Custom component for the trailing view of each call log item.           |
| `AppBarOptions`             | `() => JSX.Element`                                | Custom options to render in the AppBar.                                 |
| `callLogRequestBuilder`     | `any`                                              | Builder for custom call log requests.                                   |
| `datePattern`               | `ValueOf<typeof DateHelper.patterns>`              | Date format pattern for call logs.                                      |
| `showBackButton`            | `boolean`                                          | Flag to show the back button in the header.                             |
| `EmptyView`                 | `() => JSX.Element`                                | Custom component to render when the call log list is empty.             |
| `ErrorView`                 | `(e: CometChat.CometChatException) => JSX.Element` | Custom component to render in case of an error.                         |
| `LoadingView`               | `() => JSX.Element`                                | Custom component to render while loading call logs.                     |
| `hideError`                 | `boolean`                                          | Flag to hide the error view.                                            |
| `onCallIconPress`           | `(item: any) => void`                              | Callback when the call icon is pressed.                                 |
| `onError`                   | `(e: CometChat.CometChatException) => void`        | Callback for handling errors.                                           |
| `onBack`                    | `() => void`                                       | Callback for when the back button is pressed.                           |
| `onItemPress`               | `(call: any) => void`                              | Callback for when a call log item is pressed.                           |
| `style`                     | `DeepPartial<CometChatTheme["callLogsStyles"]>`    | Custom style overrides for the call logs.                               |
| `outgoingCallConfiguration` | `CometChatOutgoingCallInterface`                   | Configuration for outgoing calls.                                       |
| `onLoad`                    | `(list: any[]) => void`                            | Callback when the list is fetched and loaded.                           |
| `onEmpty`                   | `() => void`                                       | Callback when the list is empty (no items).                             |
| `onItemLongPress`           | `(prop: { call: any }) => void`                    | Called on a long press of the default list item view.                   |
| `hideHeader`                | `boolean`                                          | Hide the toolbar header.                                                |
| `hideLoadingState`          | `boolean`                                          | Hide the loading state.                                                 |
| `addOptions`                | `(call: any) => MenuItemInterface[]`               | Append more menu items on top of the default menu items for a call log. |
| `options`                   | `(call: any) => MenuItemInterface[]`               | Replace the default menu items entirely for a call log.                 |

### Renamed Properties

| V4 Name            | V5 Name          | Type                                                                       | Description                                               |
| ------------------ | ---------------- | -------------------------------------------------------------------------- | --------------------------------------------------------- |
| `TailView`         | `TrailingView`   | `(param: { call?: any }) => JSX.Element` → `(call?: any) => JSX.Element`   | Signature and name updated for trailing view.             |
| `ListItemView`     | `ItemView`       | `(param: { call?: any }) => JSX.Element` → `(call?: any) => JSX.Element`   | Signature and name updated for item view.                 |
| `EmptyStateView`   | `EmptyView`      | `() => JSX.Element`                                                        | Custom component for empty state.                         |
| `ErrorStateView`   | `ErrorView`      | `() => JSX.Element` → `(e: CometChat.CometChatException) => JSX.Element`   | Signature and name updated for error view.                |
| `LoadingStateView` | `LoadingView`    | `() => JSX.Element`                                                        | Custom component for loading state.                       |
| `callLogsStyle`    | `style`          | `CallLogsStyleInterface` → `DeepPartial<CometChatTheme["callLogsStyles"]>` | Style object renamed and type changed.                    |
| `AppBarOptions`    | `AppBarOptions`  | `() => JSX.Element`                                                        | (Remains, but usage clarified.)                           |
| `options`          | `options`        | Function signature updated                                                 | Now receives `(call: any)` instead of `{ message: any }`. |
| `datePattern`      | `datePattern`    | Type updated                                                               | Now uses `ValueOf<typeof DateHelper.patterns>`.           |
| `showBackButton`   | `showBackButton` | `boolean`                                                                  | (Remains, but usage clarified.)                           |

### Removed Properties

| V4 Name                    | Type                            | Description                                      |
| -------------------------- | ------------------------------- | ------------------------------------------------ |
| `title`                    | `string`                        | Title of the call log list component.            |
| `emptyStateText`           | `string`                        | Text to be displayed when the state is empty.    |
| `errorStateText`           | `string`                        | Text to be displayed when error occurs.          |
| `loadingIcon`              | `ImageType`                     | Icon to be displayed when loading.               |
| `avatarStyle`              | `AvatarStyleInterface`          | Style configuration for avatar.                  |
| `listItemStyle`            | `ListItemStyleInterface`        | Style configuration for individual list items.   |
| `headViewContainerStyle`   | `StyleProp<ViewStyle>`          | Custom styling for headViewContainer.            |
| `bodyViewContainerStyle`   | `StyleProp<ViewStyle>`          | Custom styling for bodyViewContainer.            |
| `tailViewContainerStyle`   | `StyleProp<ViewStyle>`          | Custom styling for tailViewContainer.            |
| `missedAudioCallIconUrl`   | `string`                        | Custom missed audio call icon URL.               |
| `missedVideoCallIconUrl`   | `string`                        | Custom missed video call icon URL.               |
| `incomingAudioCallIconUrl` | `string`                        | Custom incoming audio call icon URL.             |
| `incomingVideoCallIconUrl` | `string`                        | Custom incoming video call icon URL.             |
| `outgoingAudioCallIconUrl` | `string`                        | Custom outgoing audio call icon URL.             |
| `outgoingVideoCallIconUrl` | `string`                        | Custom outgoing video call icon URL.             |
| `BackButton`               | `JSX.Element`                   | Custom back button element.                      |
| `onInfoIconPress`          | `(prop: { call: any }) => void` | Callback for info icon press.                    |
| `infoIcon`                 | `ImageType`                     | Info icon image.                                 |
| `theme`                    | `CometChatTheme`                | Theme configuration for the call logs component. |
| `hideSeperator`            | `boolean`                       | Toggle visibility of separator.                  |

***

## Next Steps

<CardGroup>
  <Card title="Upgrading From V4" icon="arrow-up" href="/ui-kit/react-native/upgrading-from-v4">
    Overview of architectural changes between v4 and v5
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Learn the v5 approach to styling individual components
  </Card>

  <Card title="Theming" icon="palette" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and styles with the theme provider
  </Card>

  <Card title="Getting Started" icon="rocket" href="/ui-kit/react-native/react-native-cli-integration">
    Set up the v5 UI Kit from scratch
  </Card>
</CardGroup>


# React Native CLI Integration
Source: https://www.cometchat.com/docs/ui-kit/react-native/react-native-cli-integration

Integrate CometChat React Native UI Kit with React Native CLI using app credentials, package setup, initialization, login, and rendering.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                 |
  | ---------------- | ------------------------------------------------------------------------------------- |
  | Package          | `@cometchat/chat-uikit-react-native`                                                  |
  | Peer deps        | `react-native` >=0.77.0, `@cometchat/chat-sdk-react-native`                           |
  | Init             | `CometChatUIKit.init(UIKitSettings)` — must resolve before `login()`                  |
  | Login            | `CometChatUIKit.login({ uid })` — must resolve before rendering components            |
  | Order            | `init()` → `login()` → render. Breaking this order = blank screen                     |
  | Auth Key         | Dev/testing only. Use Auth Token in production                                        |
  | Calling          | Optional. Install `@cometchat/calls-sdk-react-native` to enable                       |
  | Other frameworks | [Expo](/docs/ui-kit/react-native/expo-integration)                                         |
  | AI Skills        | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills) |
</Accordion>

This guide walks you through adding CometChat to a React Native CLI app. By the end you'll have a working chat UI.

***

## Integrate with AI Coding Agents

Skip the manual steps — use [CometChat Skills](https://github.com/cometchat/cometchat-skills) to integrate via your AI coding agent. Your agent has a short conversation with you to understand your project and chat requirements, then writes production-grade integration code tailored to the files you already have.

```bash theme={null}
npx @cometchat/skills add
```

Use `--ide <name>` to target a specific IDE (e.g. `--ide cursor`), or `--ide all` for all supported IDEs.

Then in your IDE:

```
/cometchat add chat to my app
```

The skill detects your React Native setup, navigation library, and existing auth system. It onboards you to CometChat directly in the terminal — signup, login, and app creation all via the CLI. It reads your screens, nav, and components before proposing a placement (stack, tab, modal, or bottom sheet), shows the plan, and waits for your approval before writing code.

After the first integration, re-run `/cometchat` to access the iteration menu: theme presets, 40+ features, component customization, push notifications, production auth, user management, and diagnostics.

Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [30+ more agents](https://github.com/cometchat/cometchat-skills).

***

## Prerequisites

You need three things from the [CometChat Dashboard](https://app.cometchat.com/):

| Credential | Where to find it                                           |
| ---------- | ---------------------------------------------------------- |
| App ID     | Dashboard → Your App → Credentials                         |
| Auth Key   | Dashboard → Your App → Credentials                         |
| Region     | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) |

You also need:

* Node.js (v16+) and npm/yarn installed
* React Native development environment set up ([React Native CLI Quickstart](https://reactnative.dev/docs/environment-setup))
* Xcode (for iOS) and Android Studio (for Android)

<Warning>
  Auth Key is for development only. In production, generate Auth Tokens server-side via the [REST API](/docs/rest-api/chat-apis) and use [`loginWithAuthToken()`](/docs/ui-kit/react-native/methods#how-to-login-a-user-with-auth-token). Never ship Auth Keys in client code.
</Warning>

***

## Step 1 — Create a React Native Project

```bash theme={null}
npx @react-native-community/cli init MyApp
cd MyApp
```

<Warning>
  The CometChat React Native UI Kit is officially built and tested with React Native version 0.77.0 and above. While it may work with older versions, they are not officially supported.
</Warning>

***

## Step 2 — Install the UI Kit

```bash theme={null}
npm install @cometchat/chat-uikit-react-native
```

This installs the UI Kit. You also need to install the SDK and peer dependencies:

```bash theme={null}
npm install @cometchat/chat-sdk-react-native
npm install @react-native-community/datetimepicker
npm install @react-native-clipboard/clipboard
npm install react-native-svg
npm install react-native-video
npm install dayjs
npm install @react-native-async-storage/async-storage
npm install react-native-gesture-handler
npm install react-native-localize
npm install react-native-safe-area-context
```

### Android: Add Local Maven Repository for Async Storage

<Warning>
  **Android only:** `@react-native-async-storage/async-storage` v3 ships a local Maven artifact. Add this to your `android/build.gradle` or the Android build will fail.
</Warning>

```gradle title="android/build.gradle" theme={null}
allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri(project(":react-native-async-storage_async-storage").file("local_repo"))
        }
    }
}
```

### Add Permissions for Android

Open `android/app/src/main/AndroidManifest.xml` and add:

```xml theme={null}
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

### Install iOS Pods

```bash theme={null}
cd ios && pod install && cd ..
```

### Configure Gesture Handler

Add this import at the very top of your entry file (before any other imports):

```js title="index.js" theme={null}
import 'react-native-gesture-handler';
```

<Warning>
  This import must be at the top of your entry file. Failing to do so may cause crashes in production.
</Warning>

### Optional: Install Calling SDK

To enable voice/video calling:

```bash theme={null}
npm install @cometchat/calls-sdk-react-native
npm install @react-native-community/netinfo
npm install react-native-background-timer
npm install react-native-callstats
npm install react-native-webrtc
```

Add iOS permissions to `ios/MyApp/Info.plist`:

```xml theme={null}
<key>NSCameraUsageDescription</key>
<string>Camera access for video calls</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access for voice/video calls</string>
```

***

## Step 3 — Initialize CometChat

<Warning>
  `init()` must resolve before you call `login()`. If you call `login()` before init completes, it will fail silently.
</Warning>

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { CometChatUIKit, UIKitSettings } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    const COMETCHAT_CONSTANTS = {
      APP_ID: "APP_ID",       // Replace with your App ID
      REGION: "REGION",       // Replace with your Region
      AUTH_KEY: "AUTH_KEY",   // Replace with your Auth Key (dev only)
    };

    const uiKitSettings: UIKitSettings = {
      appId: COMETCHAT_CONSTANTS.APP_ID,
      authKey: COMETCHAT_CONSTANTS.AUTH_KEY,
      region: COMETCHAT_CONSTANTS.REGION,
      subscriptionType: CometChat.AppSettings.SUBSCRIPTION_TYPE_ALL_USERS as UIKitSettings["subscriptionType"],
    };

    CometChatUIKit.init(uiKitSettings)
      .then(() => {
        console.log("CometChat UI Kit initialized successfully.");
      })
      .catch((error) => {
        console.error("CometChat UI Kit initialization failed:", error);
      });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    const COMETCHAT_CONSTANTS = {
      APP_ID: "APP_ID",       // Replace with your App ID
      REGION: "REGION",       // Replace with your Region
      AUTH_KEY: "AUTH_KEY",   // Replace with your Auth Key (dev only)
    };

    const uiKitSettings = {
      appId: COMETCHAT_CONSTANTS.APP_ID,
      authKey: COMETCHAT_CONSTANTS.AUTH_KEY,
      region: COMETCHAT_CONSTANTS.REGION,
      subscriptionType: CometChat.AppSettings.SUBSCRIPTION_TYPE_ALL_USERS,
    };

    CometChatUIKit.init(uiKitSettings)
      .then(() => {
        console.log("CometChat UI Kit initialized successfully.");
      })
      .catch((error) => {
        console.error("CometChat UI Kit initialization failed:", error);
      });
    ```
  </Tab>
</Tabs>

***

## Step 4 — Login

After init resolves, log the user in. For development, use one of the pre-created test UIDs:

`cometchat-uid-1` · `cometchat-uid-2` · `cometchat-uid-3` · `cometchat-uid-4` · `cometchat-uid-5`

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    const UID = "cometchat-uid-1"; // Replace with your actual UID

    CometChatUIKit.login({ uid: UID })
      .then((user: CometChat.User) => {
        console.log("Login Successful:", user.getName());
      })
      .catch((error) => {
        console.error("Login failed:", error);
      });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    const UID = "cometchat-uid-1"; // Replace with your actual UID

    CometChatUIKit.login({ uid: UID })
      .then((user) => {
        console.log("Login Successful:", user.getName());
      })
      .catch((error) => {
        console.error("Login failed:", error);
      });
    ```
  </Tab>
</Tabs>

<Note>
  For production, use [`loginWithAuthToken()`](/docs/ui-kit/react-native/methods#how-to-login-a-user-with-auth-token) instead of Auth Key. Generate tokens server-side via the REST API.
</Note>

***

## Step 5 — Choose a Chat Experience

Integrate a conversation view that suits your app's UX. Each option below includes a step-by-step guide.

### Conversation List + Message View

List of conversations on one screen, tap to open messages. Standard mobile chat pattern.

* Conversation list with real-time updates
* Tap-to-view — tapping a conversation opens the message view
* Switch between one-to-one and group conversations
* Back navigation to return to the list

<Frame>
  <img />
</Frame>

<Card title="Build Conversation List + Message View" href="/ui-kit/react-native/react-native-conversation" icon="comments">
  Step-by-step guide to build this layout
</Card>

***

### One-to-One / Group Chat

Single chat window — no conversation list. Good for support chat, embedded widgets, or focused messaging.

* Dedicated chat window for one-on-one or group messaging
* No conversation list — users go directly into the chat
* Full-screen experience
* Ideal for support chat or community messaging

<Frame>
  <img />
</Frame>

<Card title="Build One-to-One / Group Chat" href="/ui-kit/react-native/react-native-one-to-one-chat" icon="message">
  Step-by-step guide to build this layout
</Card>

***

### Tab-Based Chat

Tabbed navigation — Chats, Users, Groups, Calls in separate tabs. Good for full-featured apps.

* Tab navigation between Chats, Users, Groups, and Calls
* Full-screen messaging within each tab
* Uses React Navigation bottom tabs
* Scales well for adding future features

<Frame>
  <img />
</Frame>

<Card title="Build Tab-Based Chat" href="/ui-kit/react-native/react-native-tab-based-chat" icon="table-columns">
  Step-by-step guide to build this layout
</Card>

***

## Build Your Own Chat Experience

Need full control over the UI? Use individual components, customize themes, and wire up your own layouts.

* [Sample App](https://github.com/cometchat/cometchat-uikit-react-native) — Working reference app to compare against
* [Components](/docs/ui-kit/react-native/components-overview) — All prebuilt UI elements with props and customization options
* [Core Features](/docs/ui-kit/react-native/core-features) — Messaging, real-time updates, and other capabilities
* [Theming](/docs/ui-kit/react-native/theme) — Colors, fonts, dark mode, and custom styling

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and styles
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/react-native/core-features">
    Chat features included out of the box
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/react-native/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Conversation List + Message View
Source: https://www.cometchat.com/docs/ui-kit/react-native/react-native-conversation

Build a conversation list + message view layout in React Native with CometChat UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                      |
  | ------------ | ---------------------------------------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react-native`                                                                       |
  | Framework    | React Native CLI                                                                                           |
  | Components   | `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`     |
  | Layout       | Conversation list → tap → message view                                                                     |
  | Prerequisite | Complete [React Native CLI Integration](/docs/ui-kit/react-native/react-native-cli-integration) Steps 1–4 first |
  | Pattern      | WhatsApp, Telegram, Signal                                                                                 |
</Accordion>

This guide builds a standard mobile chat layout — conversation list on one screen, tap to open messages. Users tap a conversation to view and send messages.

This assumes you've already completed [React Native CLI Integration](/docs/ui-kit/react-native/react-native-cli-integration) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Two screens working together:

1. **Conversation list** — shows all active conversations (users and groups)
2. **Message view** — displays chat messages for the selected conversation with header, message list, and composer

***

## Step 1 — Create the Messages Component

Create a `Messages.tsx` file that combines the message header, list, and composer:

<Tabs>
  <Tab title="TypeScript">
    ```tsx title="Messages.tsx" theme={null}
    import React from "react";
    import { View, StyleSheet } from "react-native";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    interface MessagesProps {
      user?: CometChat.User;
      group?: CometChat.Group;
      onBack: () => void;
    }

    const Messages = ({ user, group, onBack }: MessagesProps) => {
      return (
        <View style={styles.container}>
          <CometChatMessageHeader
            user={user}
            group={group}
            onBack={onBack}
            showBackButton
          />
          <CometChatMessageList user={user} group={group} />
          <CometChatMessageComposer user={user} group={group} />
        </View>
      );
    };

    const styles = StyleSheet.create({
      container: {
        flex: 1,
      },
    });

    export default Messages;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="Messages.js" theme={null}
    import React from "react";
    import { View, StyleSheet } from "react-native";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
    } from "@cometchat/chat-uikit-react-native";

    const Messages = ({ user, group, onBack }) => {
      return (
        <View style={styles.container}>
          <CometChatMessageHeader
            user={user}
            group={group}
            onBack={onBack}
            showBackButton
          />
          <CometChatMessageList user={user} group={group} />
          <CometChatMessageComposer user={user} group={group} />
        </View>
      );
    };

    const styles = StyleSheet.create({
      container: {
        flex: 1,
      },
    });

    export default Messages;
    ```
  </Tab>
</Tabs>

Key points:

* `CometChatMessageHeader` shows the recipient's name, avatar, and back button
* `CometChatMessageList` displays the chat history with real-time updates
* `CometChatMessageComposer` provides the text input with media, emojis, and send button
* Pass either `user` or `group` to the components, never both

***

## Step 2 — Update App.tsx

Wire the conversation list and message components together:

<Tabs>
  <Tab title="TypeScript">
    ```tsx title="App.tsx" theme={null}
    import React, { useEffect, useState } from "react";
    import { ViewStyle } from "react-native";
    import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
    import { GestureHandlerRootView } from "react-native-gesture-handler";
    import {
      CometChatConversations,
      CometChatUIKit,
      CometChatUiKitConstants,
      UIKitSettings,
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import Messages from "./Messages";

    const APP_ID = "APP_ID";
    const AUTH_KEY = "AUTH_KEY";
    const REGION = "REGION";
    const UID = "cometchat-uid-1";

    const App = (): React.ReactElement => {
      const [loggedIn, setLoggedIn] = useState(false);
      const [messageUser, setMessageUser] = useState<CometChat.User>();
      const [messageGroup, setMessageGroup] = useState<CometChat.Group>();

      useEffect(() => {
        const init = async () => {
          const uiKitSettings: UIKitSettings = {
            appId: APP_ID,
            authKey: AUTH_KEY,
            region: REGION,
            subscriptionType: CometChat.AppSettings
              .SUBSCRIPTION_TYPE_ALL_USERS as UIKitSettings["subscriptionType"],
          };

          try {
            await CometChatUIKit.init(uiKitSettings);
            await CometChatUIKit.login({ uid: UID });
            setLoggedIn(true);
          } catch (err) {
            console.error("Init/login error:", err);
          }
        };

        init();
      }, []);

      const handleConversationPress = (conversation: CometChat.Conversation) => {
        const conversationType = conversation.getConversationType();
        
        if (conversationType === CometChatUiKitConstants.ConversationTypeConstants.user) {
          setMessageUser(conversation.getConversationWith() as CometChat.User);
          setMessageGroup(undefined);
        } else {
          setMessageUser(undefined);
          setMessageGroup(conversation.getConversationWith() as CometChat.Group);
        }
      };

      const handleBack = () => {
        setMessageUser(undefined);
        setMessageGroup(undefined);
      };

      return (
        <GestureHandlerRootView style={{ flex: 1 }}>
          <SafeAreaProvider>
            <CometChatI18nProvider>
              <SafeAreaView style={styles.fullScreen}>
                <CometChatThemeProvider>
                  {loggedIn && (
                    <>
                      {/* Conversation list (hidden when chat is open) */}
                      <CometChatConversations
                        style={{
                          containerStyle: {
                            display: messageUser || messageGroup ? "none" : "flex",
                          },
                        }}
                        onItemPress={handleConversationPress}
                      />

                      {/* Message view */}
                      {(messageUser || messageGroup) && (
                        <Messages
                          user={messageUser}
                          group={messageGroup}
                          onBack={handleBack}
                        />
                      )}
                    </>
                  )}
                </CometChatThemeProvider>
              </SafeAreaView>
            </CometChatI18nProvider>
          </SafeAreaProvider>
        </GestureHandlerRootView>
      );
    };

    const styles: { fullScreen: ViewStyle } = {
      fullScreen: { flex: 1 },
    };

    export default App;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="App.js" theme={null}
    import React, { useEffect, useState } from "react";
    import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
    import { GestureHandlerRootView } from "react-native-gesture-handler";
    import {
      CometChatConversations,
      CometChatUIKit,
      CometChatUiKitConstants,
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import Messages from "./Messages";

    const APP_ID = "APP_ID";
    const AUTH_KEY = "AUTH_KEY";
    const REGION = "REGION";
    const UID = "cometchat-uid-1";

    const App = () => {
      const [loggedIn, setLoggedIn] = useState(false);
      const [messageUser, setMessageUser] = useState();
      const [messageGroup, setMessageGroup] = useState();

      useEffect(() => {
        const init = async () => {
          const uiKitSettings = {
            appId: APP_ID,
            authKey: AUTH_KEY,
            region: REGION,
            subscriptionType: CometChat.AppSettings.SUBSCRIPTION_TYPE_ALL_USERS,
          };

          try {
            await CometChatUIKit.init(uiKitSettings);
            await CometChatUIKit.login({ uid: UID });
            setLoggedIn(true);
          } catch (err) {
            console.error("Init/login error:", err);
          }
        };

        init();
      }, []);

      const handleConversationPress = (conversation) => {
        const conversationType = conversation.getConversationType();
        
        if (conversationType === CometChatUiKitConstants.ConversationTypeConstants.user) {
          setMessageUser(conversation.getConversationWith());
          setMessageGroup(undefined);
        } else {
          setMessageUser(undefined);
          setMessageGroup(conversation.getConversationWith());
        }
      };

      const handleBack = () => {
        setMessageUser(undefined);
        setMessageGroup(undefined);
      };

      return (
        <GestureHandlerRootView style={{ flex: 1 }}>
          <SafeAreaProvider>
            <CometChatI18nProvider>
              <SafeAreaView style={{ flex: 1 }}>
                <CometChatThemeProvider>
                  {loggedIn && (
                    <>
                      {/* Conversation list (hidden when chat is open) */}
                      <CometChatConversations
                        style={{
                          containerStyle: {
                            display: messageUser || messageGroup ? "none" : "flex",
                          },
                        }}
                        onItemPress={handleConversationPress}
                      />

                      {/* Message view */}
                      {(messageUser || messageGroup) && (
                        <Messages
                          user={messageUser}
                          group={messageGroup}
                          onBack={handleBack}
                        />
                      )}
                    </>
                  )}
                </CometChatThemeProvider>
              </SafeAreaView>
            </CometChatI18nProvider>
          </SafeAreaProvider>
        </GestureHandlerRootView>
      );
    };

    export default App;
    ```
  </Tab>
</Tabs>

How it works:

* `CometChatConversations` renders the list of conversations
* `onItemPress` fires when a user taps a conversation, extracting the `User` or `Group`
* `messageUser` / `messageGroup` state drives which chat is displayed
* The conversation list is hidden (via `display: "none"`) when a chat is open
* `handleBack` clears the selection and returns to the conversation list

***

## Step 3 — Run the Project

<Tabs>
  <Tab title="iOS">
    ```bash theme={null}
    npx react-native run-ios
    ```
  </Tab>

  <Tab title="Android">
    ```bash theme={null}
    npx react-native run-android
    ```
  </Tab>
</Tabs>

You should see the conversation list. Tap any conversation to open the message view. Use the back button to return to the list.

***

## Next Steps

<CardGroup>
  <Card title="Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and styles to match your brand
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="React Native CLI Integration" icon="mobile" href="/ui-kit/react-native/react-native-cli-integration">
    Back to the main setup guide
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/react-native/core-features">
    Chat features included out of the box
  </Card>
</CardGroup>


# One-to-One / Group Chat
Source: https://www.cometchat.com/docs/ui-kit/react-native/react-native-one-to-one-chat

Build a focused one-to-one or group chat experience in React Native with CometChat UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                      |
  | ------------ | ---------------------------------------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react-native`                                                                       |
  | Framework    | React Native CLI                                                                                           |
  | Components   | `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`                               |
  | Layout       | Single chat window — no conversation list                                                                  |
  | Prerequisite | Complete [React Native CLI Integration](/docs/ui-kit/react-native/react-native-cli-integration) Steps 1–4 first |
  | Pattern      | Support chat, embedded widgets, focused messaging                                                          |
</Accordion>

This guide builds a single chat window — no conversation list. Users go directly into a one-to-one or group chat. Good for support chat, embedded widgets, or any focused messaging experience.

This assumes you've already completed [React Native CLI Integration](/docs/ui-kit/react-native/react-native-cli-integration) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three components stacked vertically:

1. **Chat header** — displays recipient name, avatar, online status, and optional call buttons
2. **Message list** — real-time chat history with scrolling
3. **Message composer** — text input with media, emojis, and send button

No additional files to create — everything goes in `App.tsx`.

***

## Step 1 — Update App.tsx

The app fetches a user (or group) on mount and renders the three message components.

<Tabs>
  <Tab title="TypeScript">
    ```tsx title="App.tsx" theme={null}
    import React, { useEffect, useState } from "react";
    import { View, Text, StyleSheet } from "react-native";
    import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
    import { GestureHandlerRootView } from "react-native-gesture-handler";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
      CometChatUIKit,
      UIKitSettings,
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    const APP_ID = "APP_ID";
    const AUTH_KEY = "AUTH_KEY";
    const REGION = "REGION";
    const LOGIN_UID = "cometchat-uid-1";

    // The user or group to chat with
    const CHAT_WITH_UID = "cometchat-uid-2"; // Replace with actual UID
    // const CHAT_WITH_GUID = "GUID"; // Uncomment for group chat

    const App = (): React.ReactElement => {
      const [loggedIn, setLoggedIn] = useState(false);
      const [selectedUser, setSelectedUser] = useState<CometChat.User>();
      const [selectedGroup, setSelectedGroup] = useState<CometChat.Group>();

      useEffect(() => {
        const init = async () => {
          const uiKitSettings: UIKitSettings = {
            appId: APP_ID,
            authKey: AUTH_KEY,
            region: REGION,
            subscriptionType: CometChat.AppSettings
              .SUBSCRIPTION_TYPE_ALL_USERS as UIKitSettings["subscriptionType"],
          };

          try {
            await CometChatUIKit.init(uiKitSettings);
            await CometChatUIKit.login({ uid: LOGIN_UID });
            setLoggedIn(true);

            // Fetch the user to chat with
            const user = await CometChat.getUser(CHAT_WITH_UID);
            setSelectedUser(user);

            // For group chat, uncomment below:
            // const group = await CometChat.getGroup(CHAT_WITH_GUID);
            // setSelectedGroup(group);
          } catch (err) {
            console.error("Init/login/fetch error:", err);
          }
        };

        init();
      }, []);

      return (
        <GestureHandlerRootView style={{ flex: 1 }}>
          <SafeAreaProvider>
            <CometChatI18nProvider>
              <SafeAreaView style={styles.fullScreen}>
                <CometChatThemeProvider>
                  {loggedIn && (selectedUser || selectedGroup) ? (
                    <View style={styles.messagesWrapper}>
                      <CometChatMessageHeader
                        user={selectedUser}
                        group={selectedGroup}
                      />
                      <CometChatMessageList
                        user={selectedUser}
                        group={selectedGroup}
                      />
                      <CometChatMessageComposer
                        user={selectedUser}
                        group={selectedGroup}
                      />
                    </View>
                  ) : (
                    <View style={styles.emptyState}>
                      <Text style={styles.emptyText}>
                        Set a user or group UID in App.tsx to start chatting
                      </Text>
                    </View>
                  )}
                </CometChatThemeProvider>
              </SafeAreaView>
            </CometChatI18nProvider>
          </SafeAreaProvider>
        </GestureHandlerRootView>
      );
    };

    const styles = StyleSheet.create({
      fullScreen: {
        flex: 1,
      },
      messagesWrapper: {
        flex: 1,
      },
      emptyState: {
        flex: 1,
        justifyContent: "center",
        alignItems: "center",
        backgroundColor: "#F5F5F5",
      },
      emptyText: {
        color: "#727272",
        fontSize: 14,
      },
    });

    export default App;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="App.js" theme={null}
    import React, { useEffect, useState } from "react";
    import { View, Text, StyleSheet } from "react-native";
    import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
    import { GestureHandlerRootView } from "react-native-gesture-handler";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
      CometChatUIKit,
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    const APP_ID = "APP_ID";
    const AUTH_KEY = "AUTH_KEY";
    const REGION = "REGION";
    const LOGIN_UID = "cometchat-uid-1";

    // The user or group to chat with
    const CHAT_WITH_UID = "cometchat-uid-2"; // Replace with actual UID
    // const CHAT_WITH_GUID = "GUID"; // Uncomment for group chat

    const App = () => {
      const [loggedIn, setLoggedIn] = useState(false);
      const [selectedUser, setSelectedUser] = useState();
      const [selectedGroup, setSelectedGroup] = useState();

      useEffect(() => {
        const init = async () => {
          const uiKitSettings = {
            appId: APP_ID,
            authKey: AUTH_KEY,
            region: REGION,
            subscriptionType: CometChat.AppSettings.SUBSCRIPTION_TYPE_ALL_USERS,
          };

          try {
            await CometChatUIKit.init(uiKitSettings);
            await CometChatUIKit.login({ uid: LOGIN_UID });
            setLoggedIn(true);

            // Fetch the user to chat with
            const user = await CometChat.getUser(CHAT_WITH_UID);
            setSelectedUser(user);

            // For group chat, uncomment below:
            // const group = await CometChat.getGroup(CHAT_WITH_GUID);
            // setSelectedGroup(group);
          } catch (err) {
            console.error("Init/login/fetch error:", err);
          }
        };

        init();
      }, []);

      return (
        <GestureHandlerRootView style={{ flex: 1 }}>
          <SafeAreaProvider>
            <CometChatI18nProvider>
              <SafeAreaView style={styles.fullScreen}>
                <CometChatThemeProvider>
                  {loggedIn && (selectedUser || selectedGroup) ? (
                    <View style={styles.messagesWrapper}>
                      <CometChatMessageHeader
                        user={selectedUser}
                        group={selectedGroup}
                      />
                      <CometChatMessageList
                        user={selectedUser}
                        group={selectedGroup}
                      />
                      <CometChatMessageComposer
                        user={selectedUser}
                        group={selectedGroup}
                      />
                    </View>
                  ) : (
                    <View style={styles.emptyState}>
                      <Text style={styles.emptyText}>
                        Set a user or group UID in App.tsx to start chatting
                      </Text>
                    </View>
                  )}
                </CometChatThemeProvider>
              </SafeAreaView>
            </CometChatI18nProvider>
          </SafeAreaProvider>
        </GestureHandlerRootView>
      );
    };

    const styles = StyleSheet.create({
      fullScreen: {
        flex: 1,
      },
      messagesWrapper: {
        flex: 1,
      },
      emptyState: {
        flex: 1,
        justifyContent: "center",
        alignItems: "center",
        backgroundColor: "#F5F5F5",
      },
      emptyText: {
        color: "#727272",
        fontSize: 14,
      },
    });

    export default App;
    ```
  </Tab>
</Tabs>

Key points:

* `CometChat.getUser(UID)` fetches the user object from the SDK — you need a real user object, not a manually constructed one
* Pass either `user` or `group` to the message components, never both
* The highlighted constants show where to set the UID or swap to group chat

***

## Switching Between User and Group Chat

To load a group chat instead of one-to-one, replace the `getUser` call with `getGroup`:

```tsx theme={null}
const CHAT_WITH_GUID = "GUID"; // Replace with your actual Group ID

const group = await CometChat.getGroup(CHAT_WITH_GUID);
setSelectedGroup(group);
```

You can also determine this dynamically — for example, based on a route parameter or a selection from another part of your app.

***

## Step 2 — Run the Project

<Tabs>
  <Tab title="iOS">
    ```bash theme={null}
    npx react-native run-ios
    ```
  </Tab>

  <Tab title="Android">
    ```bash theme={null}
    npx react-native run-android
    ```
  </Tab>
</Tabs>

You should see the chat window load with the conversation for the UID you set.

***

## Next Steps

<CardGroup>
  <Card title="Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and styles to match your brand
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="React Native CLI Integration" icon="mobile" href="/ui-kit/react-native/react-native-cli-integration">
    Back to the main setup guide
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/react-native/core-features">
    Chat features included out of the box
  </Card>
</CardGroup>


# Tab-Based Chat
Source: https://www.cometchat.com/docs/ui-kit/react-native/react-native-tab-based-chat

Build a tab-based messaging UI with Chats, Users, Groups, and Calls in React Native with CometChat UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                                                                            |
  | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package      | `@cometchat/chat-uikit-react-native`                                                                                                                             |
  | Framework    | React Native CLI                                                                                                                                                 |
  | Components   | `CometChatConversations`, `CometChatUsers`, `CometChatGroups`, `CometChatCallLogs`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Tabbed navigation (Chats, Users, Groups, Calls) + message view                                                                                                   |
  | Prerequisite | Complete [React Native CLI Integration](/docs/ui-kit/react-native/react-native-cli-integration) Steps 1–4 first                                                       |
  | Pattern      | Full-featured messaging app with multiple sections                                                                                                               |
</Accordion>

This guide builds a tabbed messaging UI — Chats, Users, Groups, and Calls tabs with bottom navigation, plus a message view when an item is selected. Good for full-featured apps that need more than just conversations.

This assumes you've already completed [React Native CLI Integration](/docs/ui-kit/react-native/react-native-cli-integration) (project created, UI Kit installed, init + login working).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three sections working together:

1. **Tab bar** — switches between Chats, Users, Groups, and Calls
2. **List screens** — renders the list for the active tab
3. **Message view** — header + messages + composer for the selected item

***

## Prerequisites

Install React Navigation dependencies:

```bash theme={null}
npm install @react-navigation/native @react-navigation/bottom-tabs @react-navigation/native-stack
npm install react-native-screens
```

For iOS, install pods:

```bash theme={null}
cd ios && pod install && cd ..
```

### Configure Gesture Handler

Add this import at the very top of your entry file (before any other imports):

```js title="index.js" theme={null}
import 'react-native-gesture-handler';
```

<Warning>
  This import must be at the top of your entry file. Failing to do so may cause crashes in production.
</Warning>

***

## Step 1 — Create the Tab Screens

Create individual screen components for each tab:

<Tabs>
  <Tab title="TypeScript">
    ```tsx title="screens/ConversationsScreen.tsx" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import {
      CometChatConversations,
      CometChatUiKitConstants,
    } from "@cometchat/chat-uikit-react-native";
    import { NativeStackNavigationProp } from "@react-navigation/native-stack";

    type Props = {
      navigation: NativeStackNavigationProp<any>;
    };

    export function ConversationsScreen({ navigation }: Props) {
      const handleItemPress = (conversation: CometChat.Conversation) => {
        const conversationType = conversation.getConversationType();

        if (conversationType === CometChatUiKitConstants.ConversationTypeConstants.user) {
          const user = conversation.getConversationWith() as CometChat.User;
          navigation.navigate("Messages", { user });
        } else {
          const group = conversation.getConversationWith() as CometChat.Group;
          navigation.navigate("Messages", { group });
        }
      };

      return (
        <View style={{ flex: 1 }}>
          <CometChatConversations onItemPress={handleItemPress} />
        </View>
      );
    }
    ```

    ```tsx title="screens/UsersScreen.tsx" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
    import { NativeStackNavigationProp } from "@react-navigation/native-stack";

    type Props = {
      navigation: NativeStackNavigationProp<any>;
    };

    export function UsersScreen({ navigation }: Props) {
      const handleItemPress = (user: CometChat.User) => {
        navigation.navigate("Messages", { user });
      };

      return (
        <View style={{ flex: 1 }}>
          <CometChatUsers onItemPress={handleItemPress} />
        </View>
      );
    }
    ```

    ```tsx title="screens/GroupsScreen.tsx" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
    import { NativeStackNavigationProp } from "@react-navigation/native-stack";

    type Props = {
      navigation: NativeStackNavigationProp<any>;
    };

    export function GroupsScreen({ navigation }: Props) {
      const handleItemPress = (group: CometChat.Group) => {
        navigation.navigate("Messages", { group });
      };

      return (
        <View style={{ flex: 1 }}>
          <CometChatGroups onItemPress={handleItemPress} />
        </View>
      );
    }
    ```

    ```tsx title="screens/CallLogsScreen.tsx" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

    export function CallLogsScreen() {
      return (
        <View style={{ flex: 1 }}>
          <CometChatCallLogs />
        </View>
      );
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="screens/ConversationsScreen.js" theme={null}
    import React from "react";
    import { View } from "react-native";
    import {
      CometChatConversations,
      CometChatUiKitConstants,
    } from "@cometchat/chat-uikit-react-native";

    export function ConversationsScreen({ navigation }) {
      const handleItemPress = (conversation) => {
        const conversationType = conversation.getConversationType();

        if (conversationType === CometChatUiKitConstants.ConversationTypeConstants.user) {
          const user = conversation.getConversationWith();
          navigation.navigate("Messages", { user });
        } else {
          const group = conversation.getConversationWith();
          navigation.navigate("Messages", { group });
        }
      };

      return (
        <View style={{ flex: 1 }}>
          <CometChatConversations onItemPress={handleItemPress} />
        </View>
      );
    }
    ```

    ```jsx title="screens/UsersScreen.js" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChatUsers } from "@cometchat/chat-uikit-react-native";

    export function UsersScreen({ navigation }) {
      const handleItemPress = (user) => {
        navigation.navigate("Messages", { user });
      };

      return (
        <View style={{ flex: 1 }}>
          <CometChatUsers onItemPress={handleItemPress} />
        </View>
      );
    }
    ```

    ```jsx title="screens/GroupsScreen.js" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChatGroups } from "@cometchat/chat-uikit-react-native";

    export function GroupsScreen({ navigation }) {
      const handleItemPress = (group) => {
        navigation.navigate("Messages", { group });
      };

      return (
        <View style={{ flex: 1 }}>
          <CometChatGroups onItemPress={handleItemPress} />
        </View>
      );
    }
    ```

    ```jsx title="screens/CallLogsScreen.js" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

    export function CallLogsScreen() {
      return (
        <View style={{ flex: 1 }}>
          <CometChatCallLogs />
        </View>
      );
    }
    ```
  </Tab>
</Tabs>

***

## Step 2 — Create the Messages Screen

<Tabs>
  <Tab title="TypeScript">
    ```tsx title="screens/MessagesScreen.tsx" theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
    } from "@cometchat/chat-uikit-react-native";
    import { RouteProp } from "@react-navigation/native";
    import { NativeStackNavigationProp } from "@react-navigation/native-stack";

    type MessagesRouteParams = {
      Messages: {
        user?: CometChat.User;
        group?: CometChat.Group;
      };
    };

    type Props = {
      route: RouteProp<MessagesRouteParams, "Messages">;
      navigation: NativeStackNavigationProp<any>;
    };

    export function MessagesScreen({ route, navigation }: Props) {
      const { user, group } = route.params;

      return (
        <View style={{ flex: 1 }}>
          <CometChatMessageHeader
            user={user}
            group={group}
            onBack={() => navigation.goBack()}
            showBackButton
          />
          <CometChatMessageList user={user} group={group} />
          <CometChatMessageComposer user={user} group={group} />
        </View>
      );
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="screens/MessagesScreen.js" theme={null}
    import React from "react";
    import { View } from "react-native";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
    } from "@cometchat/chat-uikit-react-native";

    export function MessagesScreen({ route, navigation }) {
      const { user, group } = route.params;

      return (
        <View style={{ flex: 1 }}>
          <CometChatMessageHeader
            user={user}
            group={group}
            onBack={() => navigation.goBack()}
            showBackButton
          />
          <CometChatMessageList user={user} group={group} />
          <CometChatMessageComposer user={user} group={group} />
        </View>
      );
    }
    ```
  </Tab>
</Tabs>

***

## Step 3 — Set Up Navigation

Configure React Navigation with bottom tabs and a stack navigator:

<Tabs>
  <Tab title="TypeScript">
    ```tsx title="App.tsx" theme={null}
    import React, { useEffect, useState } from "react";
    import { Image, StyleSheet } from "react-native";
    import { NavigationContainer } from "@react-navigation/native";
    import { createNativeStackNavigator } from "@react-navigation/native-stack";
    import { createBottomTabNavigator } from "@react-navigation/bottom-tabs";
    import { SafeAreaProvider } from "react-native-safe-area-context";
    import { GestureHandlerRootView } from "react-native-gesture-handler";
    import {
      CometChatUIKit,
      UIKitSettings,
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    import { ConversationsScreen } from "./screens/ConversationsScreen";
    import { UsersScreen } from "./screens/UsersScreen";
    import { GroupsScreen } from "./screens/GroupsScreen";
    import { CallLogsScreen } from "./screens/CallLogsScreen";
    import { MessagesScreen } from "./screens/MessagesScreen";

    const APP_ID = "APP_ID";
    const AUTH_KEY = "AUTH_KEY";
    const REGION = "REGION";
    const UID = "cometchat-uid-1";

    const Tab = createBottomTabNavigator();
    const Stack = createNativeStackNavigator();

    function TabNavigator() {
      return (
        <Tab.Navigator
          screenOptions={{
            tabBarActiveTintColor: "#6851D6",
            tabBarInactiveTintColor: "#808080",
            headerShown: false,
            tabBarStyle: styles.tabBar,
          }}
        >
          <Tab.Screen
            name="Chats"
            component={ConversationsScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/chats.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
          <Tab.Screen
            name="Users"
            component={UsersScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/users.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
          <Tab.Screen
            name="Groups"
            component={GroupsScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/groups.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
          <Tab.Screen
            name="Calls"
            component={CallLogsScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/calls.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
        </Tab.Navigator>
      );
    }

    export default function App() {
      const [loggedIn, setLoggedIn] = useState(false);

      useEffect(() => {
        const init = async () => {
          const uiKitSettings: UIKitSettings = {
            appId: APP_ID,
            authKey: AUTH_KEY,
            region: REGION,
            subscriptionType: CometChat.AppSettings
              .SUBSCRIPTION_TYPE_ALL_USERS as UIKitSettings["subscriptionType"],
          };

          try {
            await CometChatUIKit.init(uiKitSettings);
            await CometChatUIKit.login({ uid: UID });
            setLoggedIn(true);
          } catch (err) {
            console.error("Init/login error:", err);
          }
        };

        init();
      }, []);

      if (!loggedIn) return null;

      return (
        <GestureHandlerRootView style={{ flex: 1 }}>
          <SafeAreaProvider>
            <CometChatI18nProvider>
              <CometChatThemeProvider>
                <NavigationContainer>
                  <Stack.Navigator screenOptions={{ headerShown: false }}>
                    <Stack.Screen name="Home" component={TabNavigator} />
                    <Stack.Screen name="Messages" component={MessagesScreen} />
                  </Stack.Navigator>
                </NavigationContainer>
              </CometChatThemeProvider>
            </CometChatI18nProvider>
          </SafeAreaProvider>
        </GestureHandlerRootView>
      );
    }

    const styles = StyleSheet.create({
      tabBar: {
        backgroundColor: "#FFFFFF",
        borderTopWidth: 1,
        borderTopColor: "#E8E8E8",
        paddingBottom: 5,
        paddingTop: 5,
        height: 60,
      },
      tabIcon: {
        width: 24,
        height: 24,
      },
    });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="App.js" theme={null}
    import React, { useEffect, useState } from "react";
    import { Image, StyleSheet } from "react-native";
    import { NavigationContainer } from "@react-navigation/native";
    import { createNativeStackNavigator } from "@react-navigation/native-stack";
    import { createBottomTabNavigator } from "@react-navigation/bottom-tabs";
    import { SafeAreaProvider } from "react-native-safe-area-context";
    import { GestureHandlerRootView } from "react-native-gesture-handler";
    import {
      CometChatUIKit,
      CometChatThemeProvider,
      CometChatI18nProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";

    import { ConversationsScreen } from "./screens/ConversationsScreen";
    import { UsersScreen } from "./screens/UsersScreen";
    import { GroupsScreen } from "./screens/GroupsScreen";
    import { CallLogsScreen } from "./screens/CallLogsScreen";
    import { MessagesScreen } from "./screens/MessagesScreen";

    const APP_ID = "APP_ID";
    const AUTH_KEY = "AUTH_KEY";
    const REGION = "REGION";
    const UID = "cometchat-uid-1";

    const Tab = createBottomTabNavigator();
    const Stack = createNativeStackNavigator();

    function TabNavigator() {
      return (
        <Tab.Navigator
          screenOptions={{
            tabBarActiveTintColor: "#6851D6",
            tabBarInactiveTintColor: "#808080",
            headerShown: false,
            tabBarStyle: styles.tabBar,
          }}
        >
          <Tab.Screen
            name="Chats"
            component={ConversationsScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/chats.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
          <Tab.Screen
            name="Users"
            component={UsersScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/users.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
          <Tab.Screen
            name="Groups"
            component={GroupsScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/groups.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
          <Tab.Screen
            name="Calls"
            component={CallLogsScreen}
            options={{
              tabBarIcon: ({ color }) => (
                <Image
                  source={require("./assets/calls.png")}
                  style={[styles.tabIcon, { tintColor: color }]}
                />
              ),
            }}
          />
        </Tab.Navigator>
      );
    }

    export default function App() {
      const [loggedIn, setLoggedIn] = useState(false);

      useEffect(() => {
        const init = async () => {
          const uiKitSettings = {
            appId: APP_ID,
            authKey: AUTH_KEY,
            region: REGION,
            subscriptionType: CometChat.AppSettings.SUBSCRIPTION_TYPE_ALL_USERS,
          };

          try {
            await CometChatUIKit.init(uiKitSettings);
            await CometChatUIKit.login({ uid: UID });
            setLoggedIn(true);
          } catch (err) {
            console.error("Init/login error:", err);
          }
        };

        init();
      }, []);

      if (!loggedIn) return null;

      return (
        <GestureHandlerRootView style={{ flex: 1 }}>
          <SafeAreaProvider>
            <CometChatI18nProvider>
              <CometChatThemeProvider>
                <NavigationContainer>
                  <Stack.Navigator screenOptions={{ headerShown: false }}>
                    <Stack.Screen name="Home" component={TabNavigator} />
                    <Stack.Screen name="Messages" component={MessagesScreen} />
                  </Stack.Navigator>
                </NavigationContainer>
              </CometChatThemeProvider>
            </CometChatI18nProvider>
          </SafeAreaProvider>
        </GestureHandlerRootView>
      );
    }

    const styles = StyleSheet.create({
      tabBar: {
        backgroundColor: "#FFFFFF",
        borderTopWidth: 1,
        borderTopColor: "#E8E8E8",
        paddingBottom: 5,
        paddingTop: 5,
        height: 60,
      },
      tabIcon: {
        width: 24,
        height: 24,
      },
    });
    ```
  </Tab>
</Tabs>

<Note>
  Download tab icons from the [CometChat UI Kit assets folder on GitHub](https://github.com/cometchat/cometchat-uikit-react-native) and place them in your `assets/` folder.
</Note>

***

## Step 4 — Run the Project

<Tabs>
  <Tab title="iOS">
    ```bash theme={null}
    npx react-native run-ios
    ```
  </Tab>

  <Tab title="Android">
    ```bash theme={null}
    npx react-native run-android
    ```
  </Tab>
</Tabs>

You should see the tab bar at the bottom. Switch between Chats, Users, Groups, and Calls — tapping any item navigates to the message view.

***

## Next Steps

<CardGroup>
  <Card title="Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and styles to match your brand
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="React Native CLI Integration" icon="mobile" href="/ui-kit/react-native/react-native-cli-integration">
    Back to the main setup guide
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/react-native/core-features">
    Chat features included out of the box
  </Card>
</CardGroup>


# ShortCut Formatter
Source: https://www.cometchat.com/docs/ui-kit/react-native/shortcut-formatter-guide

Create custom text shortcuts for quick message composition by extending CometChatTextFormatter in React Native.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                                                               |
  | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package        | `@cometchat/chat-uikit-react-native`                                                                                                                                                                |
  | Key class      | `CometChatTextFormatter` (abstract base class for custom formatters)                                                                                                                                |
  | Required setup | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")`                                                                                                                             |
  | Purpose        | Create custom text shortcuts for quick message composition by extending CometChatTextFormatter                                                                                                      |
  | Extension      | Message Shortcuts extension must be enabled in [CometChat Dashboard](https://app.cometchat.com)                                                                                                     |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/sample)                                                                                                                  |
  | Related        | [Mentions Formatter](/docs/ui-kit/react-native/mentions-formatter-guide) · [Custom Text Formatter](/docs/ui-kit/react-native/custom-text-formatter-guide) · [All Guides](/docs/ui-kit/react-native/guide-overview) |
</Accordion>

## Overview

The `ShortCutFormatter` class extends the `CometChatTextFormatter` class to provide a mechanism for handling shortcuts within messages. This guide walks you through the process of using ShortCutFormatter to implement shortcut extensions in your CometChat application.

<Note>
  The Message Shortcuts extension must be enabled in your [CometChat Dashboard](https://app.cometchat.com) for this feature to work.
</Note>

***

## Setup

<Steps>
  <Step title="Create the ShortCutFormatter Class">
    Define the ShortCutFormatter class by extending the CometChatTextFormatter class:

    <Tabs>
      <Tab title="TypeScript">
        ```tsx theme={null}
        import { CometChat } from "@cometchat/chat-sdk-react-native";
        import {
          CometChatTextFormatter,
          SuggestionItem,
        } from "@cometchat/chat-uikit-react-native";

        export class ShortCutFormatter extends CometChatTextFormatter {
          constructor() {
            super();
            this.trackCharacter = "!"; // Character that triggers shortcut suggestions
          }
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx theme={null}
        import { CometChat } from "@cometchat/chat-sdk-react-native";
        import {
          CometChatTextFormatter,
          SuggestionItem,
        } from "@cometchat/chat-uikit-react-native";

        export class ShortCutFormatter extends CometChatTextFormatter {
          constructor() {
            super();
            this.trackCharacter = "!"; // Character that triggers shortcut suggestions
          }
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Override the search() Method">
    Override the `search()` method to fetch shortcuts based on the entered search text:

    <Tabs>
      <Tab title="TypeScript">
        ```tsx theme={null}
        search = (searchKey: string) => {
          CometChat.callExtension("message-shortcuts", "GET", "v1/fetch", undefined)
            .then((data: any) => {
              if (data && data?.shortcuts) {
                let suggestionData = Object.keys(data.shortcuts)
                  .filter((key) =>
                    searchKey
                      ? key.toLowerCase().includes(searchKey.toLowerCase())
                      : true
                  )
                  .map((key) => {
                    return new SuggestionItem({
                      id: key,
                      name: data.shortcuts[key],
                      promptText: data.shortcuts[key],
                      trackingCharacter: "!",
                      underlyingText: data.shortcuts[key],
                    });
                  });
                this.setSearchData(suggestionData);
              }
            })
            .catch((error) => {
              console.error("Error fetching shortcuts:", error);
            });
        };

        // Return null in fetchNext if there's no pagination
        fetchNext = () => {
          return null;
        };
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx theme={null}
        search = (searchKey) => {
          CometChat.callExtension("message-shortcuts", "GET", "v1/fetch", undefined)
            .then((data) => {
              if (data && data?.shortcuts) {
                let suggestionData = Object.keys(data.shortcuts)
                  .filter((key) =>
                    searchKey
                      ? key.toLowerCase().includes(searchKey.toLowerCase())
                      : true
                  )
                  .map((key) => {
                    return new SuggestionItem({
                      id: key,
                      name: data.shortcuts[key],
                      promptText: data.shortcuts[key],
                      trackingCharacter: "!",
                      underlyingText: data.shortcuts[key],
                    });
                  });
                this.setSearchData(suggestionData);
              }
            })
            .catch((error) => {
              console.error("Error fetching shortcuts:", error);
            });
        };

        // Return null in fetchNext if there's no pagination
        fetchNext = () => {
          return null;
        };
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

***

## Usage

Initialize an instance of `ShortCutFormatter` and pass it to the message composer via the `textFormatters` prop:

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import React from "react";
    import { View } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
    } from "@cometchat/chat-uikit-react-native";
    // Import your custom ShortCutFormatter class defined above
    import { ShortCutFormatter } from "./ShortCutFormatter";

    function ChatScreen(): React.JSX.Element {
      const [chatUser, setChatUser] = React.useState<CometChat.User | undefined>();

      React.useEffect(() => {
        CometChat.getUser("uid").then((user) => {
          setChatUser(user);
        });
      }, []);

      const shortcutFormatter = React.useMemo(() => new ShortCutFormatter(), []);

      return (
        <>
          {chatUser && (
            <View style={{ flex: 1 }}>
              <CometChatMessageHeader user={chatUser} />
              <CometChatMessageList user={chatUser} />
              <CometChatMessageComposer
                user={chatUser}
                textFormatters={[shortcutFormatter]}
              />
            </View>
          )}
        </>
      );
    }

    export default ChatScreen;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import React, { useState, useEffect, useMemo } from "react";
    import { View } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
    } from "@cometchat/chat-uikit-react-native";
    // Import your custom ShortCutFormatter class defined above
    import { ShortCutFormatter } from "./ShortCutFormatter";

    function ChatScreen() {
      const [chatUser, setChatUser] = useState();

      useEffect(() => {
        CometChat.getUser("uid").then((user) => {
          setChatUser(user);
        });
      }, []);

      const shortcutFormatter = useMemo(() => new ShortCutFormatter(), []);

      return (
        <>
          {chatUser && (
            <View style={{ flex: 1 }}>
              <CometChatMessageHeader user={chatUser} />
              <CometChatMessageList user={chatUser} />
              <CometChatMessageComposer
                user={chatUser}
                textFormatters={[shortcutFormatter]}
              />
            </View>
          )}
        </>
      );
    }

    export default ChatScreen;
    ```
  </Tab>
</Tabs>

***

## Result

When users type the trigger character (`!`), they'll see a list of available shortcuts to quickly insert predefined text.

<Frame>
  <img alt="ShortCut Formatter" />
</Frame>

***

## Next Steps

<CardGroup>
  <Card title="Mentions Formatter" icon="at" href="/ui-kit/react-native/mentions-formatter-guide">
    Format and style @mentions in chat messages
  </Card>

  <Card title="Message Composer" icon="pen" href="/ui-kit/react-native/message-composer">
    Customize the message input component
  </Card>

  <Card title="All Guides" icon="book" href="/ui-kit/react-native/guide-overview">
    Browse all feature and formatter guides
  </Card>

  <Card title="Message List" icon="list" href="/ui-kit/react-native/message-list">
    Customize how messages are displayed
  </Card>
</CardGroup>


# Sound Manager
Source: https://www.cometchat.com/docs/ui-kit/react-native/sound-manager

Manage and customize audio cues for incoming/outgoing calls and messages in CometChat React Native UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                            |
  | ---------------- | ------------------------------------------------------------------------------------------------ |
  | Goal             | Manage audio playback for incoming/outgoing calls and messages                                   |
  | Import           | `import { CometChatSoundManager } from "@cometchat/chat-uikit-react-native";`                    |
  | Play sound       | `CometChatSoundManager.play("incomingMessage")`                                                  |
  | Custom sound     | `CometChatSoundManager.play("outgoingMessage", "path/to/sound.mp3")`                             |
  | Pause sound      | `CometChatSoundManager.pause()`                                                                  |
  | Sound events     | `incomingMessage`, `incomingMessageFromOther`, `outgoingMessage`, `incomingCall`, `outgoingCall` |
  | Default behavior | Plays built-in sounds; pass custom path as second arg to override                                |
</Accordion>

`CometChatSoundManager` is a helper class for managing and playing audio cues in the UI Kit — incoming/outgoing calls and messages.

***

## Sound Events

| Event Key                  | When It Plays                                      |
| -------------------------- | -------------------------------------------------- |
| `incomingMessage`          | New message received from current conversation     |
| `incomingMessageFromOther` | New message received from a different conversation |
| `outgoingMessage`          | Message sent                                       |
| `incomingCall`             | Incoming call detected (loops)                     |
| `outgoingCall`             | Outgoing call initiated (loops)                    |

***

## Methods

### play

Plays the default or custom audio resource for a given sound event.

| Parameter     | Type      | Description                                                                                   |
| ------------- | --------- | --------------------------------------------------------------------------------------------- |
| `sound`       | `string`  | Sound event key: `"incomingMessage"`, `"outgoingMessage"`, `"incomingCall"`, `"outgoingCall"` |
| `customSound` | `string`  | Optional custom audio file path. Defaults to built-in sound.                                  |
| `isRequire`   | `boolean` | Optional. Set to `true` if using `require()` for local assets.                                |

```ts theme={null}
import { CometChatSoundManager } from "@cometchat/chat-uikit-react-native";

// Play default sound
CometChatSoundManager.play("incomingMessage");

// Play custom sound
CometChatSoundManager.play("outgoingMessage", "path/to/custom-sound.mp3");
```

### pause

Pauses the currently playing sound and resets playback position.

```ts theme={null}
CometChatSoundManager.pause();
```

***

## Usage

Here is how to use `CometChatSoundManager`:

```javascript theme={null}
// Play sound with default sound:
CometChatSoundManager.play("incomingMessage"); // To play default incoming message sound
CometChatSoundManager.play("outgoingMessage"); // To play default outgoing message sound

// Play sound with custom sound
CometChatSoundManager.play("outgoingMessage", "assetPath"); // To play custom message sound

// Pause Sound:
CometChatSoundManager.pause();
```

By using the `CometChatSoundManager`, you can enhance the user experience in your chat application by integrating audible cues for chat interactions.

***

## Next Steps

<CardGroup>
  <Card title="Localize" icon="globe" href="/ui-kit/react-native/localize">
    Add multi-language support with automatic device language detection
  </Card>

  <Card title="Introduction to Theming" icon="paintbrush" href="/ui-kit/react-native/theme">
    Learn how CometChatThemeProvider manages light and dark modes
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Explore all available UI Kit components
  </Card>

  <Card title="Getting Started" icon="rocket" href="/ui-kit/react-native/react-native-cli-integration">
    Set up CometChat UI Kit in your React Native app
  </Card>
</CardGroup>


# Customizing UI With Theming
Source: https://www.cometchat.com/docs/ui-kit/react-native/theme

Customize CometChat React Native UI Kit themes, including light and dark modes, colors, typography, and component styles.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                                                            |
  | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Goal             | Customize UI Kit appearance (colors, fonts, dark mode) via theme provider                                                                                        |
  | Provider         | `CometChatThemeProvider` — wrap your app to enable theming                                                                                                       |
  | Import           | `import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";`                                                                                   |
  | Set mode         | `<CometChatThemeProvider theme={{ mode: "light" }}>` or `"dark"`                                                                                                 |
  | Override colors  | `theme={{ light: { color: { primary: "#F76808" } } }}`                                                                                                           |
  | Component styles | `theme={{ light: { conversationStyles: { ... } } }}`                                                                                                             |
  | Key tokens       | `primary`, `textPrimary`, `background1`, `neutral50`, `extendedPrimary500`                                                                                       |
  | Constraints      | Colors must be hex values, theme merges with defaults (deep merge)                                                                                               |
  | Full token list  | [Colors](/docs/ui-kit/react-native/colors) \| [GitHub source](https://github.com/cometchat/cometchat-uikit-react-native/blob/v5/packages/ChatUiKit/src/theme/type.ts) |
</Accordion>

Theming controls the look and feel of the chat UI — colors, fonts, and component styles — through the `CometChatThemeProvider`.

<Warning>
  Prerequisites:

  1. Wrap your app with `CometChatThemeProvider` to enable theming
  2. Wrap with `SafeAreaProvider` and `GestureHandlerRootView` for proper layout
  3. Colors must be supplied as hex values (e.g., `#F76808`)
  4. Theme values are deeply merged with defaults — only override what you need
</Warning>

***

## Theming Contract

**Inputs**

* `CometChatThemeProvider` wrapper with optional `theme` prop
* Theme mode: `{ mode: "light" }` or `{ mode: "dark" }`
* Color overrides: `{ light: { color: { primary: "#F76808" } } }`
* Component-specific styles: `{ light: { conversationStyles: { ... } } }`

**Precedence**

1. Style prop on component (highest priority)
2. Custom theme via `CometChatThemeProvider`
3. Default theme (lowest priority)

**Outputs**

* Primary color changes buttons, outgoing bubbles, and active states
* Background tokens change panels and surfaces
* Typography tokens change fonts across the UI
* Component styles override specific component appearances

***

## Top Tokens (Quick Mapping)

For the complete list, see [Colors](/docs/ui-kit/react-native/colors).

| Token                                 | Common Usage                                                    |
| ------------------------------------- | --------------------------------------------------------------- |
| `primary`                             | Primary accent color (buttons, outgoing bubbles, active states) |
| `extendedPrimary500`                  | Mid primary shade (secondary accents/hover)                     |
| `extendedPrimary900`                  | Darker primary shade (outgoing bubble shade)                    |
| `neutral50`                           | White/dark surface (light: `#FFFFFF`, dark: `#141414`)          |
| `neutral300`                          | Neutral surface (incoming bubbles/panels)                       |
| `background1`                         | Main app background                                             |
| `background2`                         | Secondary/panel background                                      |
| `textPrimary`                         | Primary text color                                              |
| `textSecondary`                       | Secondary/caption text                                          |
| `info`, `warning`, `success`, `error` | Semantic state colors                                           |

***

## Using Theming in Your Project

By default, the theme is automatically selected based on the system settings, ensuring that your app aligns with the user's preferred light or dark mode unless you choose to override it with a custom theme.

The `CometChatThemeProvider` is used to apply a custom theme to your components. By setting the theme prop with a specific mode, such as `{ mode: 'dark' }`, you can override the default system theme and ensure that the UI is displayed in the desired light or dark mode. This allows you to provide a consistent visual experience based on the selected theme mode.

<Warning>
  To ensure the app dynamically adapts to the device's OS-level light or dark theme, it must be wrapped in the `CometChatThemeProvider`. Without this wrapper, system theme changes will not be reflected in the app's UI.
</Warning>

Here's an example of how to explicitly set the theme mode to `light`:

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { SafeAreaView } from "react-native-safe-area-context";
    import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

    return (
      <SafeAreaView style={{ flex: 1 }}>
        <CometChatThemeProvider theme={{ mode: "light" }}>
          {/* Component */}
        </CometChatThemeProvider>
      </SafeAreaView>
    );
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

## Customization

To customize the primary color in your app, you can override the primary color attribute in the theme. Here's how to override the primary color for the light theme:

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { SafeAreaView } from "react-native-safe-area-context";
    import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

    return (
      <SafeAreaView style={{ flex: 1 }}>
        <CometChatThemeProvider
          theme={{
            light: {
              color: {
                primary: "#F76808",
              },
            },
          }}
        >
          {/* Component */}
        </CometChatThemeProvider>
      </SafeAreaView>
    );
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

<Tip>
  All default icons are implemented as SVGs.

  For these icons, only the following imageStyle properties are supported:

  * tintColor
  * height
  * width

  Any extra properties provided in imageStyle will be ignored for default icons.

  For custom icons, you can provide either JSX components or an ImageSourcePropType. JSX Components: These are rendered as-is, and no additional styles are applied.

  ImageSourcePropType (e.g., PNG, JPEG): The entire imageStyle passed will be applied to the image as expected.
</Tip>

### Overriding the Theme for Specific Components by Customizing Style Properties

The following example shows how the light theme for the `CometChatConversations` component is overridden directly by setting custom theme properties within the `CometChatThemeProvider`. This ensures that `CometChatConversations` uses a specific light theme, independent of the global theme applied to the rest of the app. The light theme is customized further by defining specific styles, such as the background color for the conversation container. This approach allows you to customize the theme for specific components while keeping the global theme intact.

<Tabs>
  <Tab title="App.tsx">
    ```tsx theme={null}
    import {
      CometChatConversations,
      CometChatUIKit,
      CometChatUiKitConstants,
      UIKitSettings,
      useTheme,
    } from "@cometchat/chat-uikit-react-native";
    import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native/src/theme/provider";
    import { SafeAreaView } from "react-native-safe-area-context";
    import Messages from "./src/Messages";

    //other code

    const theme = useTheme();

    return (
      <SafeAreaView style={{ flex: 1 }}>
        <CometChatThemeProvider
          theme={{
            light: {
              conversationStyles: {
                containerStyle: {
                  backgroundColor: theme.color.extendedPrimary500,
                },
              },
            },
          }}
        >
          {loggedIn && (
            <>
              <CometChatConversations
                style={{
                  containerStyle: {
                    display: messageUser || messageGroup ? "none" : "flex",
                  },
                }}
                onItemPress={(item: CometChat.Conversation) => {
                  if (
                    item.getConversationType() ==
                    CometChatUiKitConstants.ConversationTypeConstants.user
                  ) {
                    setMessageUser(item.getConversationWith() as CometChat.User);
                    return;
                  }
                  setMessageGroup(item.getConversationWith() as CometChat.Group);
                }}
              ></CometChatConversations>
              {(messageUser || messageGroup) && (
                <Messages
                  user={messageUser}
                  group={messageGroup}
                  onBack={() => {
                    setMessageUser(undefined);
                    setMessageGroup(undefined);
                  }}
                />
              )}
            </>
          )}
        </CometChatThemeProvider>
      </SafeAreaView>
    );
    ```
  </Tab>
</Tabs>

### Supplying Custom Theme to Specific Components by wrapping them in a separate CometChatThemeProvider

The following example shows how the theme for the `CometChatConversations` component is specifically overridden by wrapping it in a separate `CometChatThemeProvider`. This allows `CometChatConversations` to use a dark mode theme, independent of the global theme applied to the rest of the app. Additionally, the dark theme is further customized for the component by defining specific styles, such as the background color for the conversation container. This approach enables you to tailor the theme for specific components while maintaining the overall consistency of the global theme.

<Tabs>
  <Tab title="App.tsx">
    ```tsx theme={null}
    import {
      CometChatConversations,
      CometChatUIKit,
      CometChatUiKitConstants,
      UIKitSettings,
      useTheme,
      CometChatThemeProvider,
    } from "@cometchat/chat-uikit-react-native";
    import { SafeAreaView } from "react-native-safe-area-context";
    import Messages from "./src/Messages";

    //other code

    const theme = useTheme();

    return (
      <SafeAreaView style={{ flex: 1 }}>
        <CometChatThemeProvider>
          {loggedIn && (
            <>
              <CometChatThemeProvider
                theme={{
                  mode: "dark",
                  dark: {
                    conversationStyles: {
                      containerStyle: {
                        backgroundColor: theme.color.extendedPrimary600,
                      },
                    },
                  },
                }}
              >
                <CometChatConversations
                  style={{
                    containerStyle: {
                      display: messageUser || messageGroup ? "none" : "flex",
                    },
                  }}
                  onItemPress={(item: CometChat.Conversation) => {
                    if (
                      item.getConversationType() ==
                      CometChatUiKitConstants.ConversationTypeConstants.user
                    ) {
                      setMessageUser(item.getConversationWith() as CometChat.User);
                      return;
                    }
                    setMessageGroup(item.getConversationWith() as CometChat.Group);
                  }}
                ></CometChatConversations>
              </CometChatThemeProvider>
              {(messageUser || messageGroup) && (
                <Messages
                  user={messageUser}
                  group={messageGroup}
                  onBack={() => {
                    setMessageUser(undefined);
                    setMessageGroup(undefined);
                  }}
                />
              )}
            </>
          )}
        </CometChatThemeProvider>
      </SafeAreaView>
    );
    ```
  </Tab>
</Tabs>

<Note>
  When customizing theme properties, whether by overriding specific properties or supplying a completely custom theme, the provided values will be deeply merged with the default theme. This means that only the specified properties will be overridden, while all other properties will retain their default values. Additionally, if a style is passed through props, it will take priority over the style provided via the theme. The deep merge occurs in the following order of priority:

  1. The style prop (highest priority)
  2. The custom theme
  3. The default theme (lowest priority)

  This ensures that customizations are prioritized and applied while preserving the integrity of the default theme.

  ```ts theme={null}
  // The custom theme is merged with the default theme (handled internally)
  const mergedTheme = internalDeepMergeImplementation(defaultTheme, customTheme);

  // The style prop is applied with higher priority, merging it with the previous result (handled internally)
  const finalConversationsStyle = internalDeepMergeImplementation(
    mergedTheme,
    conversationStyleProp
  );
  ```
</Note>

***

## Next Steps

<CardGroup>
  <Card title="Colors" icon="palette" href="/ui-kit/react-native/colors">
    Customize primary, neutral, alert, and other color tokens
  </Card>

  <Card title="Message Bubble Styling" icon="message" href="/ui-kit/react-native/message-bubble-styling">
    Style individual message bubbles and their content
  </Card>

  <Card title="Localize" icon="globe" href="/ui-kit/react-native/localize">
    Translate UI strings and support multiple languages
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react-native/components-overview">
    Explore all available UI Kit components
  </Card>
</CardGroup>


# Threaded Messages Header
Source: https://www.cometchat.com/docs/ui-kit/react-native/threaded-messages-header

Display the parent message and reply count for threaded conversations with CometChatThreadHeader component in React Native UI Kit.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatThreadHeader",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatThreadHeader } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Displays the parent message and number of replies in a thread.",
    "props": {
      "data": {
        "parentMessage": {
          "type": "CometChat.BaseMessage",
          "note": "The parent message for which replies are shown"
        },
        "template": {
          "type": "CometChatMessageTemplate",
          "note": "Custom template for the parent message bubble"
        }
      },
      "visibility": {
        "replyCountVisibility": { "type": "boolean", "default": true },
        "replyCountBarVisibility": { "type": "boolean", "default": true },
        "receiptsVisibility": { "type": "boolean", "default": true },
        "avatarVisibility": { "type": "boolean", "default": true }
      },
      "formatting": {
        "alignment": { "type": "MessageBubbleAlignmentType", "default": "left" },
        "datePattern": "(message: CometChat.BaseMessage) => string",
        "textFormatters": "Array<CometChatTextFormatter>"
      }
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatThreadHeader` is a [Component](/docs/ui-kit/react-native/components-overview#components) that displays the parent message and number of replies in a thread.

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import {
  CometChatMessageList,
  CometChatThreadHeader,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { useState } from "react";

function ThreadHeaderDemo() {
  const [parentMessage, setParentMessage] = useState<CometChat.BaseMessage | null>(null);

  return (
    <>
      {!parentMessage && (
        <CometChatMessageList
          group={group}
          onThreadRepliesPress={(message: CometChat.BaseMessage) => {
            setParentMessage(message);
          }}
        />
      )}
      {parentMessage && <CometChatThreadHeader parentMessage={parentMessage} />}
    </>
  );
}
```

***

## 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 `CometChatThreadHeader` component.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatThreadHeader } from "@cometchat/chat-uikit-react-native";

function StylingDemo() {
  return (
    <CometChatThreadHeader
      parentMessage={parentMessage}
      style={{
        containerStyle: {
          backgroundColor: "#FEEDE1",
        },
        messageBubbleContainerStyle: {
          backgroundColor: "#FEEDE1",
        },
        replyCountBarStyle: {
          backgroundColor: "#FBA46B",
        },
        replyCountTextStyle: {
          color: "#FFFFFF",
        },
        outgoingMessageBubbleStyles: {
          containerStyle: {
            backgroundColor: "#F76808",
          },
        },
      }}
    />
  );
}
```

### Visibility Props

| Property                  | Description                                  | Code                                     |
| ------------------------- | -------------------------------------------- | ---------------------------------------- |
| `replyCountVisibility`    | Toggle reply count visibility                | `replyCountVisibility?: boolean`         |
| `replyCountBarVisibility` | Toggle reply count bar visibility            | `replyCountBarVisibility?: boolean`      |
| `receiptsVisibility`      | Toggle receipts visibility                   | `receiptsVisibility?: boolean`           |
| `avatarVisibility`        | Toggle avatar visibility                     | `avatarVisibility?: boolean`             |
| `alignment`               | Alignment type for the parent message bubble | `alignment?: MessageBubbleAlignmentType` |

### Custom Template

The `template` property is used to configure and set a custom template for parent message bubble.

```tsx lines theme={null}
import { CometChat } from "@cometchat/chat-sdk-react-native";
import {
  CometChatThreadHeader,
  CometChatMessageTemplate,
  ChatConfigurator,
  MessageBubbleAlignmentType,
  useTheme,
} from "@cometchat/chat-uikit-react-native";
import { Text } from "react-native";

function CustomTemplateDemo() {
  const theme = useTheme();

  const getTemplate = () => {
    let templates: CometChatMessageTemplate[] =
      ChatConfigurator.getDataSource().getAllMessageTemplates(theme);
    const textTemplate = templates.find((template) => {
      if (template.type == "text") {
        template.ContentView = (
          messageObject: CometChat.BaseMessage,
          alignment: MessageBubbleAlignmentType
        ) => {
          const textMessage = messageObject as CometChat.TextMessage;
          return (
            <Text style={{ backgroundColor: "#fff5fd", padding: 10 }}>
              {textMessage.getText()}
            </Text>
          );
        };
        return template;
      }
    });
    return textTemplate;
  };

  return (
    <CometChatThreadHeader
      parentMessage={parentMessage}
      template={getTemplate()}
    />
  );
}
```

***

## Next Steps

<CardGroup>
  <Card title="Threaded Messages" icon="comments" href="/ui-kit/react-native/guide-threaded-messages">
    Display the complete threaded conversation view
  </Card>

  <Card title="Message List" icon="message" href="/ui-kit/react-native/message-list">
    Display the list of messages in a conversation
  </Card>

  <Card title="Message Template" icon="file-code" href="/ui-kit/react-native/message-header">
    Customize message bubble templates
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>


# Troubleshooting
Source: https://www.cometchat.com/docs/ui-kit/react-native/troubleshooting

Troubleshoot CometChat React Native UI Kit setup, initialization, login, theming, permissions, messaging, calling, and build issues.

<Accordion title="AI Integration Quick Reference">
  | Field             | Value                                                                                                                                                         |
  | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Page type         | Troubleshooting reference                                                                                                                                     |
  | Scope             | All CometChat React Native UI Kit v5 issues — initialization, rendering, theming, calling, extensions, AI features, localization, sound, events, native setup |
  | When to reference | When a component fails to render, data is missing, styling doesn't apply, a feature doesn't appear, or native build fails                                     |
</Accordion>

## Initialization and Login

| Symptom                                | Cause                                               | Fix                                                                                               |
| -------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `CometChatUIKit.init()` fails silently | Invalid App ID, Region, or Auth Key                 | Double-check credentials from the [CometChat Dashboard](https://app.cometchat.com/)               |
| Component doesn't render               | `init()` not called or not awaited before rendering | Ensure `init()` completes before mounting components. See [Methods](/docs/ui-kit/react-native/methods) |
| Component renders but shows no data    | User not logged in                                  | Call `CometChatUIKit.login({ uid })` after init                                                   |
| Login fails with "UID not found"       | UID doesn't exist in your CometChat app             | Create the user via Dashboard, SDK, or API first                                                  |
| Blank screen after login               | Component mounted before init/login completes       | Use state to conditionally render after login resolves                                            |
| `getLoggedinUser()` returns null       | User not logged in or session expired               | Call `login()` or `loginWithAuthToken()` first                                                    |
| `sendTextMessage()` fails              | User not logged in or invalid receiver              | Ensure login completes before sending messages                                                    |
| Auth Key exposed in production         | Using Auth Key instead of Auth Token                | Switch to [Auth Token](/docs/ui-kit/react-native/methods#login-using-auth-token) for production        |

***

## React Native CLI Setup

| Symptom                              | Cause                                                                          | Fix                                                                                                                                                                    |
| ------------------------------------ | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Android build fails with Maven error | Missing local Maven repository for `@react-native-async-storage/async-storage` | Add the Maven URL to `android/build.gradle`. See [Integration](/docs/ui-kit/react-native/react-native-cli-integration#android-add-local-maven-repository-for-async-storage) |
| iOS build fails                      | Pods not installed                                                             | Run `cd ios && pod install && cd ..`                                                                                                                                   |
| App crashes on launch                | `react-native-gesture-handler` not imported at top of entry file               | Add `import 'react-native-gesture-handler';` at the very top of `index.js` before any other imports                                                                    |
| Permission denied errors on Android  | Missing permissions in AndroidManifest.xml                                     | Add required permissions (INTERNET, CAMERA, RECORD\_AUDIO, etc.). See [Integration](/docs/ui-kit/react-native/react-native-cli-integration#add-permissions-for-android)     |
| Camera/microphone not working on iOS | Missing Info.plist entries                                                     | Add `NSCameraUsageDescription` and `NSMicrophoneUsageDescription` to Info.plist                                                                                        |

***

## Expo Setup

| Symptom                              | Cause                                  | Fix                                                                                                                                        |
| ------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| App crashes in Expo Go               | Expo Go doesn't support native modules | Use [development builds](https://docs.expo.dev/develop/development-builds/introduction/) instead of Expo Go                                |
| Build fails with native module error | Missing development build              | Run `npx expo run:ios` or `npx expo run:android` to create a development build                                                             |
| Permissions not working              | Missing app.json configuration         | Add iOS `infoPlist` and Android `permissions` to app.json. See [Expo Integration](/docs/ui-kit/react-native/expo-integration#configure-appjson) |

***

## Theming

| Symptom                                    | Cause                                       | Fix                                                                                              |
| ------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Theme not applied                          | Missing `CometChatThemeProvider` wrapper    | Wrap your app with `CometChatThemeProvider`. See [Theme](/docs/ui-kit/react-native/theme)             |
| Dark mode not working                      | `mode` not set in theme prop                | Set `theme={{ mode: "dark" }}` on `CometChatThemeProvider`                                       |
| System theme changes not reflected         | App not wrapped in `CometChatThemeProvider` | Wrap app in `CometChatThemeProvider` to enable automatic system theme detection                  |
| Custom colors not applying                 | Colors not in hex format                    | Ensure all color values are hex strings (e.g., `#F76808`)                                        |
| Component-level style override not working | Style prop not taking priority              | Style props have highest priority — check for typos in prop names                                |
| Primary color unchanged                    | Wrong token name                            | Use `primary` token under `color` object: `theme={{ light: { color: { primary: "#F76808" } } }}` |
| Icon styles not applying                   | Using unsupported imageStyle properties     | For default SVG icons, only `tintColor`, `height`, and `width` are supported                     |

***

## Components

| Symptom                      | Cause                                          | Fix                                                                             |
| ---------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------- |
| Callback not firing          | Wrong prop name or signature                   | Check the component documentation for exact prop name and parameter types       |
| Custom view not appearing    | Returning `null` or `undefined` from view prop | Ensure view function returns valid JSX                                          |
| Messages not loading         | Invalid user/group object passed               | Ensure you fetch the user/group via SDK before passing to components            |
| Gesture handling not working | Missing `GestureHandlerRootView` wrapper       | Wrap your app with `GestureHandlerRootView` from `react-native-gesture-handler` |
| Safe area issues             | Missing `SafeAreaProvider` wrapper             | Wrap your app with `SafeAreaProvider` from `react-native-safe-area-context`     |

***

## Calling

| Symptom                                      | Cause                                                               | Fix                                                                                                                                            |
| -------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Call buttons not appearing in Message Header | `@cometchat/calls-sdk-react-native` not installed                   | Run `npm install @cometchat/calls-sdk-react-native` — UI Kit auto-detects it                                                                   |
| Incoming call screen not showing             | `CometChatIncomingCall` not mounted or call listener not registered | Render `CometChatIncomingCall` at app root and register `CometChat.addCallListener()`. See [Call Features](/docs/ui-kit/react-native/call-features) |
| Call accepted but no audio/video             | Missing call session setup                                          | After `acceptCall()`, generate a token and render the call component                                                                           |
| `onIncomingCallReceived` not firing          | Call listener not registered or registered too late                 | Register `CometChat.addCallListener()` after login completes                                                                                   |
| Call fails on Android                        | Missing permissions or wrong SDK version                            | Ensure `minSdkVersion` is 24+, `compileSdkVersion` is 33+, and permissions are added                                                           |
| Call fails on iOS                            | Missing permissions or wrong deployment target                      | Set `IPHONEOS_DEPLOYMENT_TARGET` to 12.0+ and add camera/microphone permissions to Info.plist                                                  |
| WebRTC errors                                | Missing peer dependencies                                           | Install `react-native-webrtc`, `@react-native-community/netinfo`, `react-native-background-timer`                                              |

***

## Extensions

| Symptom                                         | Cause                                          | Fix                                                                                                                                                        |
| ----------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extension feature not appearing                 | Extension not activated in CometChat Dashboard | Enable the specific extension from your [Dashboard](/docs/fundamentals/extensions-overview)                                                                     |
| Stickers not showing in composer                | Sticker extension not enabled                  | Activate [Sticker Extension](/docs/fundamentals/stickers) in Dashboard                                                                                          |
| Polls option missing from action sheet          | Polls extension not enabled                    | Activate [Polls Extension](/docs/fundamentals/polls) in Dashboard                                                                                               |
| Link preview not rendering in messages          | Link Preview extension not enabled             | Activate [Link Preview Extension](/docs/fundamentals/link-preview) in Dashboard                                                                                 |
| Collaborative whiteboard/document not appearing | Extension not enabled                          | Activate [Collaborative Whiteboard](/docs/fundamentals/collaborative-whiteboard) or [Collaborative Document](/docs/fundamentals/collaborative-document) in Dashboard |

***

## AI Features

| Symptom                                 | Cause                                          | Fix                                                                                                         |
| --------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| AI features not appearing               | Feature not activated in CometChat Dashboard   | Enable the specific AI feature from your [Dashboard](/docs/fundamentals/ai-user-copilot/overview)                |
| Conversation Starter not showing        | Feature not enabled or no conversation context | Ensure [Conversation Starter](/docs/fundamentals/ai-user-copilot/conversation-starter) is activated in Dashboard |
| Smart Replies not appearing in composer | Feature not enabled in Dashboard               | Ensure [Smart Replies](/docs/fundamentals/ai-user-copilot/smart-replies) is activated in Dashboard               |

***

## Localization

| Symptom                                     | Cause                                      | Fix                                                                                                                       |
| ------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| UI text not translated                      | Language code not matching supported codes | Check the supported languages table in [Localize](/docs/ui-kit/react-native/localize) for exact codes (e.g., `en-US` not `en`) |
| Auto language detection not working         | Missing `react-native-localize` package    | Install `react-native-localize`: `npm install react-native-localize`                                                      |
| Custom translations not appearing           | `CometChatI18nProvider` not wrapping app   | Wrap app with `CometChatI18nProvider` inside `CometChatThemeProvider`                                                     |
| `useCometChatTranslation` returns undefined | Hook used outside provider                 | Ensure component is wrapped by `CometChatI18nProvider`                                                                    |
| Fallback language not working               | `fallbackLanguage` prop not set            | Set `fallbackLanguage` prop on `CometChatI18nProvider`                                                                    |

***

## Sound

| Symptom                    | Cause                                      | Fix                                                                                           |
| -------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------- |
| No sound plays             | Audio file not found or unsupported format | Ensure the path is correct and the file is a valid audio format (WAV/MP3)                     |
| Custom sound not playing   | Invalid file path                          | Verify the asset path is correct; use `isRequire: true` if using `require()` for local assets |
| Sound keeps playing        | `pause()` not called                       | Call `CometChatSoundManager.pause()` to stop playback                                         |
| Sound plays multiple times | Multiple sound triggers                    | Ensure you're not calling `play()` multiple times for the same event                          |

***

## Events

| Symptom                           | Cause                                             | Fix                                                                                         |
| --------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Event listener not firing         | Subscribed to wrong event name                    | Check the [Events](/docs/ui-kit/react-native/events) page for exact event names                  |
| Duplicate event triggers          | Multiple subscriptions without cleanup            | Remove listeners in `useEffect` cleanup or component unmount                                |
| Event fires but UI doesn't update | State not updated in event handler                | Ensure you call `setState` or equivalent in the handler                                     |
| Call events not received          | `CometChatUIEventHandler` listener not registered | Register both `CometChat.addCallListener()` and `CometChatUIEventHandler.addCallListener()` |

***

## Native Dependencies

| Symptom                                         | Cause                           | Fix                                                                                 |
| ----------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
| `react-native-video` not working                | Native module not linked        | For React Native CLI, run `cd ios && pod install`. For Expo, use development builds |
| `react-native-svg` icons not rendering          | Package not installed or linked | Install `react-native-svg` and run `pod install` for iOS                            |
| `@react-native-clipboard/clipboard` errors      | Package not installed           | Install `@react-native-clipboard/clipboard`                                         |
| `@react-native-community/datetimepicker` errors | Package not installed           | Install `@react-native-community/datetimepicker`                                    |
| `dayjs` date formatting issues                  | Package not installed           | Install `dayjs`                                                                     |


# Upgrading From V4 to V5
Source: https://www.cometchat.com/docs/ui-kit/react-native/upgrading-from-v4

Migrate from CometChat React Native UI Kit v4 to v5 with updated components, simplified theming, and modular architecture.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                             |
  | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
  | Package          | `@cometchat/chat-uikit-react-native`                                                                                              |
  | Key changes      | Composite components → modular components, `CometChatTheme` class → `CometChatThemeProvider`, nested styles → single `style` prop |
  | View renames     | `ListItemView` → `ItemView`, `TailView` → `TrailingView`, `EmptyStateView` → `EmptyView`                                          |
  | Property changes | [See below](#property-changes)                                                                                                    |
  | Sample app       | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp)                                    |
</Accordion>

## Introduction

The **CometChat v5 React Native UI Kit** streamlines the integration of in-app chat functionality into your applications. Packed with prebuilt, modular UI components, it supports essential messaging features for both one-to-one and group conversations. With built-in theming options, including light and dark modes, customizable fonts, colors, and extensive configuration possibilities, developers can create chat experiences tailored to their application’s needs.

<Frame>
  <img />
</Frame>

## Integration

In **v4**, integration was straightforward due to the availability of composite components like `CometChatConversationsWithMessages`. This single component provided end-to-end functionality, including listing conversations, handling conversation clicks, loading messages (message header, list, composer), displaying user or group details, and supporting threaded messages. Developers could achieve all these features with minimal setup. However, customization posed significant challenges. Customizing the UI or adding custom views required a deep understanding of the internal flow of the composite component. Additionally, configurations were a mix of custom view props, behavioural props, and style props, which often led to confusion. Styling deeply nested components also proved cumbersome, limiting the developer’s ability to make meaningful changes.

<Frame>
  <img />
</Frame>

With **v5**, composite components have been replaced with smaller, modular components, such as `Conversations`, `Message Header`, `Message List`, and `Message Composer`. This modular approach makes integration more flexible and easier to understand. Each component has a well-defined purpose, allowing developers to use them in ways that suit their specific requirements. The need for complex configurations has been eliminated, as developers can now customize behavior and styling directly via props and theme provider. Styling has been significantly simplified, with every component carefully assigned, enabling developers to customize styles globally or at the component level effortlessly.

To support the transition from v4 to v5, CometChat has built a [sample app](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp) that replicates the functionality of v4’s composite components. This sample app serves as a reference for developers looking to build additional features such as user/group details, call log details, threaded messages, and advanced messaging capabilities. By following this approach, developers can take full advantage of v5’s modular design while implementing complex functionality in an organized manner.

<Frame>
  <img />
</Frame>

<Note>
  Learn how to build a complete messaging UI using the **v5 UI Kit** by following the step-by-step guide [here](/docs/ui-kit/react-native/react-native-cli-integration).
</Note>

## Components

The **v4** UI Kit provided composite components like `CometChatConversationsWithMessages`, which offered end-to-end functionality. These components integrated features such as conversation lists, message views (header, list, composer), user/group details, and threaded messages into a single unit. However, customization of deeply nested components through configuration was challenging and resulted in a suboptimal developer experience.

| Components in v4 UI Kit:           |                            |                              |
| ---------------------------------- | -------------------------- | ---------------------------- |
| CometChatConversationsWithMessages | CometChatUsersWithMessages | CometChatGroupsWithMessages  |
| CometChatMessages                  | CometChatMessageHeader     | CometChatMessageList         |
| CometChatMessageComposer           | CometChatThreadedMessages  | CometChatConversations       |
| CometChatUsers                     | CometChatGroups            | CometChatContacts            |
| CometChatDetails                   | CometChatGroupMembers      | CometChatAddMembers          |
| CometChatBannedMembers             | CometChatTransferOwnership | CometChatMessageInformation  |
| CometChatIncomingCall              | CometChatOngoingCall       | CometChatOutgoingCall        |
| CometChatCallButtons               | CometChatCallLogs          | CometChatCallLogDetails      |
| CometChatCallLogHistory            | CometChatCallLogRecordings | CometChatCallLogParticipants |
| CometChatCallLogsWithDetails       | CometChatUserMemberWrapper |                              |

In **v5**, the composite approach is replaced with smaller, modular components like `Conversations`, `Message Header`, `Message List`, and `Message Composer`. Developers now need to stitch these components together to build the desired functionality. This change allows for greater flexibility and easier customization via props, significantly improving the developer experience while maintaining functionality.

| Components in v5 UI Kit: |                        |                       |
| ------------------------ | ---------------------- | --------------------- |
| CometChatConversations   | CometChatUsers         | CometChatGroups       |
| CometChatGroupMembers    | CometChatMessageHeader | CometChatMessageList  |
| CometChatMessageComposer | CometChatThreadHeader  | CometChatIncomingCall |
| CometChatOutgoingCall    | CometChatCallButtons   | CometChatCallLogs     |

## Theming

In **v4**, theming was managed using the CometChatTheme class, which included two key properties: Typography and Palette. The Palette property provided methods like `setAccent50()`, `setPrimary()`, and `setMode()` for configuring colors and themes. The theming system relied heavily on React’s Context API, utilizing CometChatThemeProvider and CometChatThemeContext to retrieve and update theme settings. While Context is a core concept in React, it wasn’t the most intuitive or efficient approach for theming.

The v4 approach required developers to instantiate theme objects and call multiple setter methods to achieve the desired styling. For example, switching between light and dark modes required calling `myTheme.palette.setMode("dark")` on the theme instance. While this approach provided granular control, it involved verbose configuration with multiple method calls for each theme property. Customizing themes required understanding the specific setter methods available for both Palette and Typography classes, making the theming process more complex and requiring more boilerplate code.

```tsx App.tsx (v4) theme={null}
import React from 'react';
import { View } from 'react-native';
import { CometChatTheme } from '@cometchat/chat-uikit-react-native';

const App = () => {
  // Initialize theme with setter methods
  let myTheme: CometChatTheme = new CometChatTheme({});
  
  // Configure colors using setter methods
  myTheme.palette.setPrimary({
    light: "#6851D6",
    dark: "#6851D6",
  });
  myTheme.palette.setAccent({
    light: "#f76808",
    dark: "#f76808",
  });
  
  // Set theme mode
  myTheme.palette.setMode("light");
  
  // Configure typography
  myTheme.typography.setName({ fontSize: 22, fontWeight: "800" });

  return (
    <View style={{ flex: 1 }}>
      {/* Your app components with theme applied */}
    </View>
  );
};

export default App;
```

In **v5**, theming has been simplified with the `CometChatThemeProvider` component that accepts a structured theme object. The complex theme class instantiation and setter methods have been replaced with direct theme object configuration. This approach allows developers to directly define theme properties without needing to understand internal theme class structures.

The new theming system provides better flexibility for component-level styling through theme overrides. Developers can create theme objects that target specific components and their styles, making customization more intuitive and straightforward. The `CometChatI18nProvider` has also been separated from theming concerns, providing cleaner separation of localization and theme management.

```tsx App.tsx (v5) theme={null}
import React from "react";
import { SafeAreaView } from "react-native-safe-area-context";
import { CometChatThemeProvider, CometChatI18nProvider } from "@cometchat/chat-uikit-react-native";

const customTheme = {
  light: {
    color: {
      primary: '#f76808',
      background1: '#ffffff',
      background2: '#feede1',
    },
    messageListStyles: {
      outgoingMessageBubbleStyles: {
        containerStyle: {
          backgroundColor: '#f76808',
        },
      },
    },
  },
  dark: {
    color: {
      primary: '#f76808',
      background1: '#1a1a1a',
      background2: '#2a2a2a',
    },
  },
};

const App = () => {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <CometChatThemeProvider theme={customTheme}>
        <CometChatI18nProvider>
          {/* Your app components */}
        </CometChatI18nProvider>
      </CometChatThemeProvider>
    </SafeAreaView>
  );
};

export default App;
```

<Note>
  For detailed guidance on theming and customizing colors in the CometChat React Native UI Kit, refer to the following resources:

  * **Theming Documentation:** [Guide to Theming](/docs/ui-kit/react-native/theme)
  * **Component Styling:** [Component Styling](/docs/ui-kit/react-native/component-styling)
</Note>

## Properties

In **v5**, the approach to component properties has been significantly refined to improve clarity and ease of use. All style-related properties have been streamlined to work seamlessly with the new theming system based on direct property access. This change ensures a more efficient and flexible styling process without the need for verbose or redundant configuration within the component properties.

Configuration properties, which were prominent in v4, have also been simplified. With v5's modular design, components are no longer deeply nested, making complex configurations unnecessary. Developers now have direct control over each component through clearly defined properties, reducing complexity and increasing flexibility in how components are used and styled.

Custom view properties have undergone a comprehensive overhaul to ensure consistency across all components. For example, components that are represented as list items now share a uniform set of customizable properties, enabling a standardized approach to customization. These properties include:

* `itemView` - Custom view for the entire item
* `leadingView` - Custom view for the leading section
* `trailingView` - Custom view for the trailing section
* `subtitleView` - Custom view for the subtitle
* `titleView` - Custom view for the title

This consistent naming convention makes it easier for developers to understand and apply customizations across various components, streamlining the development process.

For a comprehensive overview of newly added, renamed, and removed properties, refer to the [Property Changes](/docs/ui-kit/react-native/property-changes) Documentation.

***

## Next Steps

<CardGroup>
  <Card title="Property Changes" icon="list-check" href="/ui-kit/react-native/property-changes">
    Detailed reference of new, renamed, and removed props for each component
  </Card>

  <Card title="Getting Started" icon="rocket" href="/ui-kit/react-native/react-native-cli-integration">
    Set up the v5 UI Kit and send your first message
  </Card>

  <Card title="Theming" icon="palette" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and styles with the new theme system
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Style individual components using the simplified v5 approach
  </Card>
</CardGroup>

This consistent naming convention makes it easier for developers to understand and apply customizations across various components, streamlining the development process.

***

## Property Changes

In CometChat v5 UI Kit, several props and methods in components have been updated. Below is a detailed reference of renamed, added, and removed properties for each component.

### Conversations

#### New Properties

| Name                                 | Type                                                                                    | Description                                                                               |
| ------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `hideSubmitButton`                   | boolean                                                                                 | Hide the submit (selection) button.                                                       |
| `receiptsVisibility`                 | boolean                                                                                 | Toggles message receipts (single/double-tick) inside the subtitle.                        |
| `disableSoundForMessages`            | boolean                                                                                 | Toggle sound playback for received messages.                                              |
| `customSoundForMessages`             | string                                                                                  | Custom sound file path for received messages.                                             |
| `datePattern`                        | `(conversation: CometChat.Conversation) => string`                                      | Function to generate a custom date string for a conversation.                             |
| `ItemView`                           | `(item: CometChat.Conversation) => JSX.Element`                                         | Completely overrides the default rendering of each conversation item in the list.         |
| `AppBarOptions`                      | `() => JSX.Element`                                                                     | Functional component for rendering options in the app bar.                                |
| `hideBackButton`                     | boolean                                                                                 | Hide the back button.                                                                     |
| `selectionMode`                      | `'none' \| 'single' \| 'multiple'`                                                      | Selection mode: `'none'`, `'single'`, or `'multiple'`.                                    |
| `onSelection`                        | `(conversations: Array<CometChat.Conversation>) => void`                                | Callback when conversation selection is complete.                                         |
| `onSubmit`                           | `(conversations: Array<CometChat.Conversation>) => void`                                | Callback when submit selection button is pressed.                                         |
| `EmptyView`                          | `() => JSX.Element`                                                                     | Custom view for the empty state.                                                          |
| `ErrorView`                          | `() => JSX.Element`                                                                     | Custom view for the error state.                                                          |
| `LoadingView`                        | `() => JSX.Element`                                                                     | Custom view for the loading state.                                                        |
| `conversationsRequestBuilder`        | `CometChat.ConversationsRequestBuilder`                                                 | Request builder to fetch conversations.                                                   |
| `LeadingView`                        | `(conversation: CometChat.Conversation) => JSX.Element`                                 | Custom leading view for a conversation item.                                              |
| `TitleView`                          | `(conversation: CometChat.Conversation) => JSX.Element`                                 | Custom title view for a conversation item.                                                |
| `SubtitleView`                       | `(conversation: CometChat.Conversation) => JSX.Element`                                 | Custom subtitle view for a conversation item.                                             |
| `TrailingView`                       | `(conversation: CometChat.Conversation) => JSX.Element`                                 | Custom tail view for a conversation item.                                                 |
| `hideError`                          | boolean                                                                                 | Hide error view.                                                                          |
| `onItemPress`                        | `(item: CometChat.Conversation) => void`                                                | Callback for when a conversation item is pressed.                                         |
| `onItemLongPress`                    | `(item: CometChat.Conversation) => void`                                                | Callback for when a conversation item is long pressed.                                    |
| `onError`                            | `(e: CometChat.CometChatException) => void`                                             | Callback when an error occurs while fetching conversations.                               |
| `onBack`                             | `() => void`                                                                            | Callback for when the back action is triggered.                                           |
| `textFormatters`                     | `Array<CometChatMentionsFormatter \| CometChatUrlsFormatter \| CometChatTextFormatter>` | Array of text formatter classes.                                                          |
| `style`                              | `DeepPartial<ConversationStyle>`                                                        | Custom styles for the conversation view.                                                  |
| `hideHeader`                         | boolean                                                                                 | Hide the header of the conversation list.                                                 |
| `onEmpty`                            | `() => void`                                                                            | Callback triggered when the fetched list is empty.                                        |
| `onLoad`                             | `(list: CometChat.Conversation[]) => void`                                              | Callback triggered once the users have loaded and are not empty.                          |
| `options`                            | `(conversation: CometChat.Conversation) => MenuItemInterface[]`                         | A function to replace the default menu items entirely for a conversation.                 |
| `addOptions`                         | `(conversation: CometChat.Conversation) => MenuItemInterface[]`                         | A function to append more menu items on top of the default menu items for a conversation. |
| `usersStatusVisibility`              | boolean                                                                                 | Toggle user status visibility.                                                            |
| `groupTypeVisibility`                | boolean                                                                                 | Toggle group type visibility.                                                             |
| `deleteConversationOptionVisibility` | boolean                                                                                 | Toggle delete conversation option visibility.                                             |

#### Renamed Properties

| V4 Name                          | V5 Name                 | Type     | Description                                                                       |
| -------------------------------- | ----------------------- | -------- | --------------------------------------------------------------------------------- |
| `hideSubmitIcon`                 | `hideSubmitButton`      | boolean  | Hide the submit (selection) button.                                               |
| `disableUsersPresence`           | `usersStatusVisibility` | boolean  | Toggle user status visibility.                                                    |
| `hideReceipt` / `disableReceipt` | `receiptsVisibility`    | boolean  | Controls receipt visibility.                                                      |
| `tailView`                       | `TrailingView`          | function | Custom tail/trailing view for a conversation item.                                |
| `ListItemView`                   | `ItemView`              | function | Completely overrides the default rendering of each conversation item in the list. |
| `AppBarOption`                   | `AppBarOptions`         | function | Functional component for rendering options in the app bar.                        |
| `showBackButton`                 | `hideBackButton`        | boolean  | In v5, the prop is inverted (showBackButton=false → hideBackButton=true).         |
| `conversationsStyle`             | `style`                 | object   | Style object for conversations (renamed and type changed).                        |
| `EmptyStateView`                 | `EmptyView`             | function | Custom view for the empty state.                                                  |
| `ErrorStateView`                 | `ErrorView`             | function | Custom view for the error state.                                                  |
| `LoadingStateView`               | `LoadingView`           | function | Custom view for the loading state.                                                |

#### Removed Properties

| V4 Name                         | Type      | Description                                              |
| ------------------------------- | --------- | -------------------------------------------------------- |
| `protectedGroupIcon`            | ImageType | Custom icon for protected group.                         |
| `privateGroupIcon`              | ImageType | Custom icon for private group.                           |
| `readIcon`                      | ImageType | Custom icon for read message.                            |
| `deliveredIcon`                 | ImageType | Custom icon for delivered message.                       |
| `sentIcon`                      | ImageType | Custom icon for sent message.                            |
| `errorIcon`                     | ImageType | Custom icon for error message.                           |
| `waitingIcon`                   | ImageType | Custom icon for waiting message.                         |
| `options (swipe actions)`       | function  | Pass array of `CometChatOptions` type for swipe actions. |
| `hideSeparator`                 | boolean   | Toggle separator.                                        |
| `backButtonIcon`                | ImageType | Icon for back button.                                    |
| `title`                         | string    | Title to be shown, default `"Chats"`.                    |
| `emptyStateText`                | string    | Text to be displayed if no conversation found.           |
| `errorStateText`                | string    | Text to be displayed if there is an error.               |
| `conversationsStyle (old type)` | object    | (Renamed to `style`, but if old type, it's removed).     |
| `listItemStyle`                 | object    | Style object for list item.                              |
| `avatarStyle`                   | object    | Style object for avatar.                                 |
| `statusIndicatorStyle`          | object    | Style object for status indicator.                       |
| `dateStyle`                     | object    | Style object for date.                                   |
| `receiptStyle`                  | object    | Style object for receipt.                                |
| `badgeStyle`                    | object    | Style object for badge.                                  |
| `confirmDialogStyle`            | object    | Style object for confirm dialog.                         |
| `disableTyping`                 | boolean   | Toggle typing indicator.                                 |
| `disableMentions`               | boolean   | If true, mentions will be disabled.                      |

### Users

#### New Properties

| Name                     | Type                                            | Description                                                                       |
| ------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------- |
| `onSubmit`               | `(list: Array<CometChat.User>) => void`         | Callback when submit selection button is pressed.                                 |
| `style`                  | `DeepPartial<UserStyle>`                        | Custom styling for the users list.                                                |
| `TitleView`              | `(user: CometChat.User) => JSX.Element`         | Custom title view component.                                                      |
| `ItemView`               | `(user: CometChat.User) => JSX.Element`         | Function that returns a custom list item view.                                    |
| `EmptyView`              | `() => JSX.Element`                             | Custom component to display for the empty state.                                  |
| `ErrorView`              | `() => JSX.Element`                             | Custom component to display for the error state.                                  |
| `LoadingView`            | `() => JSX.Element`                             | Custom component to display for the loading state.                                |
| `LeadingView`            | `(user: CometChat.User) => JSX.Element`         | Custom leading view component.                                                    |
| `hideHeader`             | boolean                                         | Hide the header view.                                                             |
| `searchPlaceholderText`  | string                                          | Placeholder text for the search input.                                            |
| `usersStatusVisibility`  | boolean                                         | Hide the users status.                                                            |
| `searchKeyword`          | string                                          | Search keyword.                                                                   |
| `onError`                | `(e: CometChat.CometChatException) => void`     | Callback when an error occurs.                                                    |
| `hideLoadingState`       | boolean                                         | Hide the loading skeleton.                                                        |
| `title`                  | string                                          | Title for the header.                                                             |
| `addOptions`             | `(user: CometChat.User) => MenuItemInterface[]` | A function to append more menu items on top of the default menu items for a user. |
| `hideError`              | boolean                                         | Toggle error view visibility.                                                     |
| `showBackButton`         | boolean                                         | Toggle back button visibility.                                                    |
| `stickyHeaderVisibility` | boolean                                         | Toggle sticky header visibility.                                                  |

#### Renamed Properties

| V4 Name                | V5 Name                 | Type     | Description                                              |
| ---------------------- | ----------------------- | -------- | -------------------------------------------------------- |
| `usersStyle`           | `style`                 | object   | Custom styling for the users list.                       |
| `TailView`             | `TrailingView`          | function | Function that returns a custom trailing view for a user. |
| `disableUsersPresence` | `usersStatusVisibility` | boolean  | Toggle user status visibility                            |
| `ListItemView`         | `ItemView`              | function | Function that returns a custom list item view.           |

#### Removed Properties

| V4 Name       | Type | Description                          |
| ------------- | ---- | ------------------------------------ |
| `listItemKey` | any  | Key for list item *(removed in v5)*. |

### Groups

#### New Properties

| Name                    | Type                                              | Description                                                                        |
| ----------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `TitleView`             | `(group: CometChat.Group) => JSX.Element`         | Custom title view for a group item.                                                |
| `SubtitleView`          | `(group: CometChat.Group) => JSX.Element`         | Custom subtitle view for a group item.                                             |
| `TrailingView`          | `(group: CometChat.Group) => JSX.Element`         | Custom trailing view for a group item.                                             |
| `ItemView`              | `(group: CometChat.Group) => JSX.Element`         | Completely overrides the default rendering of each group item in the list.         |
| `AppBarOptions`         | `() => JSX.Element`                               | Functional component for rendering options in the app bar.                         |
| `hideSubmitButton`      | boolean                                           | Hide the submit (selection) button.                                                |
| `style`                 | `DeepPartial<GroupStyle>`                         | Custom styles for the groups view.                                                 |
| `searchPlaceholderText` | string                                            | Placeholder text for the search input.                                             |
| `selectionMode`         | `'none' \| 'single' \| 'multiple'`                | Selection mode: `'none'`, `'single'`, or `'multiple'`.                             |
| `onSelection`           | `(list: Array<CometChat.Group>) => void`          | Callback when group selection is complete.                                         |
| `onSubmit`              | `(list: Array<CometChat.Group>) => void`          | Callback when submit selection button is pressed.                                  |
| `hideSearch`            | boolean                                           | Hide the search box.                                                               |
| `EmptyView`             | `() => JSX.Element`                               | Custom view for the empty state.                                                   |
| `ErrorView`             | `() => JSX.Element`                               | Custom view for the error state.                                                   |
| `LoadingView`           | `() => JSX.Element`                               | Custom view for the loading state.                                                 |
| `groupsRequestBuilder`  | `CometChat.GroupsRequestBuilder`                  | Request builder to fetch groups.                                                   |
| `searchRequestBuilder`  | `CometChat.GroupsRequestBuilder`                  | Request builder for search functionality.                                          |
| `privateGroupIcon`      | `ImageSourcePropType`                             | Icon to be used for private groups.                                                |
| `passwordGroupIcon`     | `ImageSourcePropType`                             | Icon to be used for password-protected groups.                                     |
| `hideError`             | boolean                                           | Hide error view.                                                                   |
| `onItemPress`           | `(item: CometChat.Group) => void`                 | Callback for when a group item is pressed.                                         |
| `onItemLongPress`       | `(item: CometChat.Group) => void`                 | Callback for when a group item is long pressed.                                    |
| `onError`               | `(e: CometChat.CometChatException) => void`       | Callback when an error occurs while fetching groups.                               |
| `onBack`                | `() => void`                                      | Callback for when the back action is triggered.                                    |
| `hideHeader`            | boolean                                           | Hide the header of the group list.                                                 |
| `LeadingView`           | `(group: CometChat.Group) => JSX.Element`         | Custom leading view for a group item.                                              |
| `searchKeyword`         | string                                            | Search keyword.                                                                    |
| `onEmpty`               | `() => void`                                      | Callback triggered when the fetched list is empty.                                 |
| `onLoad`                | `(list: CometChat.GroupMember[]) => void`         | Callback triggered once the groups have loaded and are not empty.                  |
| `hideLoadingState`      | boolean                                           | Hide the loading skeleton.                                                         |
| `groupTypeVisibility`   | boolean                                           | Hide the group type *(public/private/password)*.                                   |
| `addOptions`            | `(group: CometChat.Group) => MenuItemInterface[]` | A function to append more menu items on top of the default menu items for a group. |
| `options`               | `(group: CometChat.Group) => MenuItemInterface[]` | A function to replace the default menu items entirely for a group.                 |

#### Renamed Properties

| V4 Name                 | V5 Name                 | Type                                | Description                                                                |
| ----------------------- | ----------------------- | ----------------------------------- | -------------------------------------------------------------------------- |
| `ListItemView`          | `ItemView`              | function                            | Completely overrides the default rendering of each group item in the list. |
| `AppBarOption`          | `AppBarOptions`         | function                            | Functional component for rendering options in the app bar.                 |
| `hideSubmitIcon`        | `hideSubmitButton`      | boolean                             | Hide the submit (selection) button.                                        |
| `groupsStyle`           | `style`                 | object                              | Style object for groups *(renamed and type changed)*.                      |
| `searchPlaceHolderText` | `searchPlaceholderText` | string                              | Placeholder text for the search input.                                     |
| `EmptyStateView`        | `EmptyView`             | function                            | Custom view for the empty state.                                           |
| `ErrorStateView`        | `ErrorView`             | function                            | Custom view for the error state.                                           |
| `LoadingStateView`      | `LoadingView`           | function                            | Custom view for the loading state.                                         |
| `privateGroupIcon`      | `privateGroupIcon`      | `ImageType` → `ImageSourcePropType` | Icon to be used for private groups *(type changed)*.                       |
| `passwordGroupIcon`     | `passwordGroupIcon`     | `ImageType` → `ImageSourcePropType` | Icon to be used for password-protected groups *(type changed)*.            |

#### Removed Properties

| V4 Name                | Type      | Description                                                               |
| ---------------------- | --------- | ------------------------------------------------------------------------- |
| `hideSeperator`        | boolean   | Toggle separator *(removed, not present in v5)*.                          |
| `listItemStyle`        | object    | Style object for list item *(removed, not present in v5)*.                |
| `avatarStyle`          | object    | Style object for avatar *(removed, not present in v5)*.                   |
| `statusIndicatorStyle` | object    | Style object for status indicator *(removed, not present in v5)*.         |
| `backButtonIcon`       | ImageType | Icon for back button *(removed, not present in v5)*.                      |
| `searchBoxIcon`        | ImageType | Icon for search box *(removed, not present in v5)*.                       |
| `title`                | string    | Title to be shown, default `"Groups"` *(removed, not present in v5)*.     |
| `emptyStateText`       | string    | Text to be displayed if no group found *(removed, not present in v5)*.    |
| `errorStateText`       | string    | Text to be displayed if there is an error *(removed, not present in v5)*. |

### Group Members

#### New Properties

| Name                        | Type                                                                             | Description                                                                         |
| --------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `SubtitleView`              | `(item: CometChat.GroupMember) => JSX.Element`                                   | Custom subtitle view for a group member item.                                       |
| `TitleView`                 | `(item: CometChat.GroupMember) => JSX.Element`                                   | Custom title view for a group member item.                                          |
| `TrailingView`              | `(item: CometChat.GroupMember) => JSX.Element`                                   | Custom trailing view for a group member item.                                       |
| `EmptyView`                 | `() => JSX.Element`                                                              | Custom view for the empty state.                                                    |
| `ErrorView`                 | `() => JSX.Element`                                                              | Custom view for the error state.                                                    |
| `LoadingView`               | `() => JSX.Element`                                                              | Custom view for the loading state.                                                  |
| `onItemPress`               | `(groupMember: CometChat.GroupMember) => void`                                   | Callback when a group member item is pressed.                                       |
| `onItemLongPress`           | `(groupMember: CometChat.GroupMember) => void`                                   | Callback when a group member item is long pressed.                                  |
| `onSelection`               | `(list: CometChat.GroupMember[]) => void`                                        | Callback when group member selection is complete.                                   |
| `onSubmit`                  | `(list: Array<CometChat.GroupMember>) => void`                                   | Callback when submit selection button is pressed.                                   |
| `searchRequestBuilder`      | `CometChat.GroupMembersRequestBuilder`                                           | Request builder for search functionality.                                           |
| `groupMemberRequestBuilder` | `CometChat.GroupMembersRequestBuilder`                                           | Request builder to fetch group members.                                             |
| `group`                     | `CometChat.Group`                                                                | The group object for which members are listed.                                      |
| `style`                     | `DeepPartial<GroupMemberStyle>`                                                  | Custom styles for the group member view.                                            |
| `ItemView`                  | `(item: CometChat.GroupMember) => JSX.Element`                                   | Completely overrides the default rendering of each group member item.               |
| `LeadingView`               | `(item: CometChat.GroupMember) => JSX.Element`                                   | Custom leading view for a group member item.                                        |
| `onEmpty`                   | `() => void`                                                                     | Callback triggered when the fetched list is empty.                                  |
| `onLoad`                    | `(list: CometChat.GroupMember[]) => void`                                        | Callback triggered once the group members have loaded and are not empty.            |
| `options`                   | `(member: CometChat.GroupMember, group: CometChat.Group) => MenuItemInterface[]` | Function to replace default menu items entirely for a group member.                 |
| `addOptions`                | `(member: CometChat.GroupMember, group: CometChat.Group) => MenuItemInterface[]` | Function to append more menu items on top of default menu items for a group member. |
| `hideKickMemberOption`      | `boolean`                                                                        | Hide the "Remove" (Kick) option from the default menu.                              |
| `hideBanMemberOption`       | `boolean`                                                                        | Hide the "Ban" option from the default menu.                                        |
| `hideScopeChangeOption`     | `boolean`                                                                        | Hide the "Change Scope" option from the default menu.                               |
| `hideLoadingState`          | `boolean`                                                                        | Hide the loading skeleton.                                                          |
| `usersStatusVisibility`     | `boolean`                                                                        | Toggle user status visibility.                                                      |
| `hideHeader`                | `boolean`                                                                        | Hide the header view.                                                               |
| `onError`                   | `() => void`                                                                     | Callback when an error occurs.                                                      |
| `searchKeyword`             | `string`                                                                         | Search keyword.                                                                     |
| `showBackButton`            | `boolean`                                                                        | Toggle back button visibility.                                                      |
| `excludeOwner`              | `boolean`                                                                        | Exclude owner from the list.                                                        |

#### Renamed Properties

| V4 Name                | V5 Name                 | Type     | Description                                                           |
| ---------------------- | ----------------------- | -------- | --------------------------------------------------------------------- |
| `TailView`             | `TrailingView`          | function | Custom trailing view for a group member item.                         |
| `groupMemberStyle`     | `style`                 | object   | Style object for group member (renamed and type changed).             |
| `disableUsersPresence` | `usersStatusVisibility` | boolean  | Toggle user status visibility                                         |
| `ListItemView`         | `ItemView`              | function | Completely overrides the default rendering of each group member item. |
| `EmptyStateView`       | `EmptyView`             | function | Custom view for the empty state.                                      |
| `ErrorStateView`       | `ErrorView`             | function | Custom view for the error state.                                      |
| `LoadingStateView`     | `LoadingView`           | function | Custom view for the loading state.                                    |

#### Removed Properties

| V4 Name                | Type             | Description                                                            |
| ---------------------- | ---------------- | ---------------------------------------------------------------------- |
| `listItemStyle`        | object           | Style object for list item *(removed in v5)*.                          |
| `avatarStyle`          | object           | Style object for avatar *(removed in v5)*.                             |
| `statusIndicatorStyle` | object           | Style object for status indicator *(removed in v5)*.                   |
| `groupScopeStyle`      | object           | Styling properties for group scope *(removed in v5)*.                  |
| `title`                | string           | Title for the list *(removed in v5)*.                                  |
| `errorStateText`       | string           | Text to be displayed when error occurs *(removed in v5)*.              |
| `emptyStateText`       | string           | Text to be displayed when the list is empty *(removed in v5)*.         |
| `theme`                | `CometChatTheme` | Theme configuration for the group members component *(removed in v5)*. |

### Message Header

#### New Properties

| Name                       | Type                                                                                   | Description                                                                          |
| -------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `ItemView`                 | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element` | Custom item view. Receives `{ user, group }`.                                        |
| `LeadingView`              | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element` | Custom leading view. Receives `{ user, group }`.                                     |
| `TitleView`                | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element` | Custom title view. Receives `{ user, group }`.                                       |
| `SubtitleView`             | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element` | Custom subtitle view. Receives `{ user, group }`.                                    |
| `TrailingView`             | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element` | Custom trailing view. Receives `{ user, group }`.                                    |
| `AuxiliaryButtonView`      | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element` | Custom auxiliary button view. Receives `{ user, group }`.                            |
| `user`                     | `CometChat.User`                                                                       | User object.                                                                         |
| `group`                    | `CometChat.Group`                                                                      | Group object.                                                                        |
| `showBackButton`           | `boolean`                                                                              | Toggle back button visibility.                                                       |
| `onBack`                   | `() => void`                                                                           | Callback when back button is pressed.                                                |
| `style`                    | `DeepPartial<MessageHeaderStyle>`                                                      | Custom styles.                                                                       |
| `onError`                  | `(error: CometChat.CometChatException) => void`                                        | Error callback.                                                                      |
| `hideVoiceCallButton`      | `boolean`                                                                              | Toggle visibility of voice call button.                                              |
| `hideVideoCallButton`      | `boolean`                                                                              | Toggle visibility of video call button.                                              |
| `usersStatusVisibility`    | `boolean`                                                                              | Toggle visibility of user status.                                                    |
| `hideNewChatButton`        | `boolean`                                                                              | Flag to hide the new chat button for AI agents (only applies to @agentic users).     |
| `hideChatHistoryButton`    | `boolean`                                                                              | Flag to hide the chat history button for AI agents (only applies to @agentic users). |
| `onNewChatButtonClick`     | `() => void`                                                                           | Callback when agent new chat button is clicked (only applies to @agentic users).     |
| `onChatHistoryButtonClick` | `() => void`                                                                           | Callback when agent chat history button is clicked (only applies to @agentic users). |

#### Renamed Properties

| V4 Name                | V5 Name                 | Type     | Description                                                             |
| ---------------------- | ----------------------- | -------- | ----------------------------------------------------------------------- |
| `ListItemView`         | `ItemView`              | function | Custom item view.                                                       |
| `AppBarOptions`        | `TrailingView`          | function | Custom trailing view.                                                   |
| `hideBackIcon`         | `showBackButton`        | boolean  | In v5, the prop is inverted (hideBackIcon=true → showBackButton=false). |
| `disableUsersPresence` | `usersStatusVisibility` | boolean  | Toggle user status visibility                                           |
| `style`                | `style`                 | object   | Style object for message header (renamed and type changed).             |

#### Removed Properties

| V4 Name                  | Type        | Description                                                               |
| ------------------------ | ----------- | ------------------------------------------------------------------------- |
| `protectedGroupIcon`     | `ImageType` | Custom icon for protected group *(removed in v5)*.                        |
| `privateGroupIcon`       | `ImageType` | Custom icon for private group *(removed in v5)*.                          |
| `backButtonIcon`         | `ImageType` | Icon for back button *(removed in v5)*.                                   |
| `disableTyping`          | `boolean`   | Controls typing indicator functionality *(removed in v5)*.                |
| `avatarStyle`            | `object`    | Style configuration for avatar *(removed in v5)*.                         |
| `statusIndicatorStyle`   | `object`    | Style configuration for status indicator *(removed in v5)*.               |
| `headViewContainerStyle` | `object`    | Custom styling for headViewContainer in list item *(removed in v5)*.      |
| `bodyViewContainerStyle` | `object`    | Custom styling for bodyViewContainerStyle in list item *(removed in v5)*. |
| `tailViewContainerStyle` | `object`    | Custom styling for tailViewContainerStyle in list item *(removed in v5)*. |
| `listItemStyle`          | `object`    | Custom styling for list item *(removed in v5)*.                           |

### Message List

#### New Properties

| Name                          | Type                                                                                                                                                       | Description                                                                              |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `parentMessageId`             | `string`                                                                                                                                                   | ID of the parent message when rendering threaded messages.                               |
| `user`                        | `CometChat.User`                                                                                                                                           | The user object associated with the message list.                                        |
| `group`                       | `CometChat.Group`                                                                                                                                          | The group object associated with the message list.                                       |
| `EmptyView`                   | `() => JSX.Element`                                                                                                                                        | A component to display when there are no messages.                                       |
| `ErrorView`                   | `() => JSX.Element`                                                                                                                                        | A component to display when an error occurs.                                             |
| `hideError`                   | `boolean`                                                                                                                                                  | Flag to hide the error view.                                                             |
| `LoadingView`                 | `() => JSX.Element`                                                                                                                                        | A component to display while messages are loading.                                       |
| `receiptsVisibility`          | `boolean`                                                                                                                                                  | Flag to hide read receipts.                                                              |
| `disableSoundForMessages`     | `boolean`                                                                                                                                                  | Flag to disable sound for incoming messages.                                             |
| `customSoundForMessages`      | `string`                                                                                                                                                   | Custom sound URL for messages.                                                           |
| `alignment`                   | `MessageListAlignmentType`                                                                                                                                 | Alignment type for the message list.                                                     |
| `avatarVisibility`            | `boolean`                                                                                                                                                  | Flag to show or hide the user's avatar.                                                  |
| `datePattern`                 | `(message: CometChat.BaseMessage) => string`                                                                                                               | Function that returns a custom string representation for a message's date.               |
| `dateSeparatorPattern`        | `(date: number) => string`                                                                                                                                 | Function that returns a custom date separator string based on a timestamp.               |
| `templates`                   | `Array<CometChatMessageTemplate>`                                                                                                                          | An array of message templates for rendering custom message types.                        |
| `addTemplates`                | `Array<CometChatMessageTemplate>`                                                                                                                          | An array of message templates for rendering custom message types.                        |
| `messageRequestBuilder`       | `CometChat.MessagesRequestBuilder`                                                                                                                         | Builder for constructing a request to fetch messages.                                    |
| `scrollToBottomOnNewMessages` | `boolean`                                                                                                                                                  | If true, the message list will scroll to the bottom when new messages arrive.            |
| `onThreadRepliesPress`        | `(messageObject: CometChat.BaseMessage, messageBubbleView: () => JSX.Element \| null) => void`                                                             | Callback invoked when the thread replies view is pressed.                                |
| `HeaderView`                  | `({ user, group, id }: { user?: CometChat.User; group?: CometChat.Group; id?: { uid?: string; guid?: string; parentMessageId?: string } }) => JSX.Element` | Custom header view component.                                                            |
| `FooterView`                  | `({ user, group, id }: { user?: CometChat.User; group?: CometChat.Group; id?: { uid?: string; guid?: string; parentMessageId?: string } }) => JSX.Element` | Custom footer view component.                                                            |
| `onError`                     | `(e: CometChat.CometChatException) => void`                                                                                                                | Callback to handle errors.                                                               |
| `onBack`                      | `() => void`                                                                                                                                               | Callback invoked on back navigation.                                                     |
| `textFormatters`              | `Array<CometChatMentionsFormatter \| CometChatUrlsFormatter \| CometChatTextFormatter>`                                                                    | Collection of text formatter classes to apply custom formatting.                         |
| `onReactionPress`             | `(reaction: CometChat.ReactionCount, messageObject: CometChat.BaseMessage) => void`                                                                        | Callback invoked when a reaction is pressed.                                             |
| `onReactionLongPress`         | `(reaction: CometChat.ReactionCount, messageObject: CometChat.BaseMessage) => void`                                                                        | Callback invoked when a reaction is long pressed.                                        |
| `onReactionListItemPress`     | `(messageReaction: CometChat.Reaction, messageObject: CometChat.BaseMessage) => void`                                                                      | Callback invoked when an item in the reaction list is pressed.                           |
| `style`                       | `DeepPartial<CometChatTheme["messageListStyles"]>`                                                                                                         | Custom styles for the message list component.                                            |
| `reactionsRequestBuilder`     | `CometChat.ReactionsRequestBuilder`                                                                                                                        | Builder for constructing a request to fetch reactions.                                   |
| `onAddReactionPress`          | `() => void`                                                                                                                                               | Callback invoked when the add reaction button is pressed.                                |
| `quickReactionList`           | `[string, string?, string?, string?, string?]`                                                                                                             | List of quick reactions.                                                                 |
| `onLoad`                      | `(messageList: CometChat.BaseMessage[]) => void`                                                                                                           | Callback to handle when the message list is loaded.                                      |
| `onEmpty`                     | `() => void`                                                                                                                                               | Callback to handle when the message list is empty.                                       |
| `hideReplyInThreadOption`     | `boolean`                                                                                                                                                  | Flag to hide the reply in thread option.                                                 |
| `hideShareMessageOption`      | `boolean`                                                                                                                                                  | Flag to hide the share message option.                                                   |
| `hideEditMessageOption`       | `boolean`                                                                                                                                                  | Flag to hide the edit message option.                                                    |
| `hideTranslateMessageOption`  | `boolean`                                                                                                                                                  | Flag to hide the translate message option.                                               |
| `hideDeleteMessageOption`     | `boolean`                                                                                                                                                  | Flag to hide the delete message option.                                                  |
| `hideReactionOption`          | `boolean`                                                                                                                                                  | Flag to hide the react to message option.                                                |
| `hideMessagePrivatelyOption`  | `boolean`                                                                                                                                                  | Flag to hide the message privately option.                                               |
| `hideCopyMessageOption`       | `boolean`                                                                                                                                                  | Flag to hide the copy message option.                                                    |
| `hideMessageInfoOption`       | `boolean`                                                                                                                                                  | Flag to hide the message info option.                                                    |
| `hideGroupActionMessages`     | `boolean`                                                                                                                                                  | Flag to hide group action messages.                                                      |
| `hideTimestamp`               | `boolean`                                                                                                                                                  | Flag to hide the timestamp on message bubbles.                                           |
| `suggestedMessages`           | `Array<string>`                                                                                                                                            | Array of suggested messages for AI agent empty view (only applies to @agentic users).    |
| `hideSuggestedMessages`       | `boolean`                                                                                                                                                  | Flag to hide suggested messages in AI agent empty view (only applies to @agentic users). |
| `emptyChatGreetingView`       | `React.ReactNode`                                                                                                                                          | Custom AI agent greeting view (only applies to @agentic users).                          |
| `emptyChatIntroMessageView`   | `React.ReactNode`                                                                                                                                          | Custom AI agent intro message view (only applies to @agentic users).                     |
| `emptyChatImageView`          | `React.ReactNode`                                                                                                                                          | Custom AI agent image/avatar view (only applies to @agentic users).                      |
| `onSuggestedMessageClick`     | `(suggestion: string) => void`                                                                                                                             | Callback when suggested message is clicked (only applies to @agentic users).             |
| `aiAssistantTools`            | `CometChatAIAssistantTools`                                                                                                                                | Custom AI assistant tools with action functions (only applies to @agentic users).        |
| `streamingSpeed`              | `number`                                                                                                                                                   | Controls the speed of AI message streaming (only applies to @agentic users).             |

#### Renamed Properties

| V4 Name                          | V5 Name                | Type                       | Description                                        |
| -------------------------------- | ---------------------- | -------------------------- | -------------------------------------------------- |
| `EmptyStateView`                 | `EmptyView`            | `() => JSX.Element`        | Custom component to display for the empty state.   |
| `ErrorStateView`                 | `ErrorView`            | `() => JSX.Element`        | Custom component to display for the error state.   |
| `LoadingStateView`               | `LoadingView`          | `() => JSX.Element`        | Custom component to display for the loading state. |
| `hideReceipt` / `disableReceipt` | `receiptsVisibility`   | `boolean`                  | Controls receipt visibility.                       |
| `showAvatar`                     | `avatarVisibility`     | `boolean`                  | Toggle visibility for avatar.                      |
| `dateSeparatorPattern`           | `dateSeparatorPattern` | `(date: number) => string` | Signature clarified with parameter name.           |

#### Removed Properties

| V4 Name                           | Type                                                | Description                                |
| --------------------------------- | --------------------------------------------------- | ------------------------------------------ |
| `emptyStateText`                  | `string`                                            | Text to be displayed if no message found.  |
| `errorStateText`                  | `string`                                            | Text to be displayed if there is an error. |
| `readIcon`                        | `ImageType`                                         | Custom icon for read message.              |
| `deliveredIcon`                   | `ImageType`                                         | Custom icon for delivered message.         |
| `sentIcon`                        | `ImageType`                                         | Custom icon for sent message.              |
| `waitIcon`                        | `ImageType`                                         | Custom icon for waiting message.           |
| `errorIcon`                       | `ImageType`                                         | Custom icon for error message.             |
| `wrapperMessageBubbleStyle`       | `MessageBubbleStyleInterface`                       | Style for message bubble wrapper.          |
| `avatarStyle`                     | `AvatarStyleInterface`                              | Style configuration for avatar.            |
| `dateSeperatorStyle`              | `DateStyleInterface`                                | Style for date separator.                  |
| `actionSheetStyle`                | `ActionSheetStylesInterface`                        | Style for action sheet.                    |
| `messageListStyle`                | `MessageListStyleInterface`                         | Style configuration for message list.      |
| `messageInformationConfiguration` | `CometChatMessageInformationConfigurationInterface` | Configuration for message information.     |
| `reactionsConfiguration`          | `ReactionsConfigurationInterface`                   | Message Reaction Configuration.            |
| `reactionListConfiguration`       | `ReactionListConfigurationInterface`                | Message Reaction List Configuration.       |
| `quickReactionConfiguration`      | `QuickReactionsConfigurationInterface`              | Quick Reaction Configuration.              |
| `emojiKeyboardStyle`              | `EmojiKeyboardStyle`                                | Emoji Keyboard style.                      |
| `disableReactions`                | `boolean`                                           | Disables the reactions functionality.      |
| `disableMentions`                 | `boolean`                                           | Disables mentions functionality.           |
| `timeStampAlignment`              | `MessageTimeAlignmentType`                          | Alignment for message timestamps.          |
| `newMessageIndicatorText`         | `string`                                            | Custom text for new message indicator.     |
| `hideActionSheetHeader`           | `boolean`                                           | Hide the header of the action sheet.       |

### Message Composer

#### New Properties

| Name                                | Type                                                                                                                                                | Description                                                                                |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `id`                                | `string \| number`                                                                                                                                  | Message composer identifier.                                                               |
| `user`                              | `CometChat.User`                                                                                                                                    | CometChat SDK's user object.                                                               |
| `group`                             | `CometChat.Group`                                                                                                                                   | CometChat SDK's group object.                                                              |
| `disableSoundForOutgoingMessages`   | `boolean`                                                                                                                                           | Flag to turn off sound for outgoing messages.                                              |
| `customSoundForOutgoingMessage`     | `any`                                                                                                                                               | Custom audio sound to be played while sending messages.                                    |
| `disableTypingEvents`               | `boolean`                                                                                                                                           | Flag to disable typing events.                                                             |
| `initialComposertext`               | `string`                                                                                                                                            | Initial text to be displayed in the composer.                                              |
| `HeaderView`                        | `({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => JSX.Element`                                                              | Renders a preview section at the top of the composer.                                      |
| `onTextChange`                      | `(text: string) => void`                                                                                                                            | Callback triggered when the input text changes.                                            |
| `attachmentOptions`                 | `({ user, group, composerId }: { user?: CometChat.User; group?: CometChat.Group; composerId: Map<any, any>; }) => CometChatMessageComposerAction[]` | Returns the attachment options for the composer.                                           |
| `AuxiliaryButtonView`               | `({ user, group, composerId }: { user?: CometChat.User; group?: CometChat.Group; composerId: string \| number; }) => JSX.Element`                   | Replaces the default Auxiliary Button.                                                     |
| `SendButtonView`                    | `({ user, group, composerId }: { user?: CometChat.User; group?: CometChat.Group; composerId: string \| number; }) => JSX.Element`                   | Replaces the default Send Button.                                                          |
| `parentMessageId`                   | `string \| number`                                                                                                                                  | Message id required for threaded messages.                                                 |
| `style`                             | `DeepPartial<CometChatTheme["messageComposerStyles"]>`                                                                                              | Custom styles for the message composer component.                                          |
| `hideVoiceRecordingButton`          | `boolean`                                                                                                                                           | Flag to hide the voice recording button.                                                   |
| `onSendButtonPress`                 | `(message: CometChat.BaseMessage) => void`                                                                                                          | Callback triggered when the send button is pressed.                                        |
| `onError`                           | `(error: CometChat.CometChatException) => void`                                                                                                     | Callback triggered when an error occurs.                                                   |
| `keyboardAvoidingViewProps`         | `KeyboardAvoidingViewProps`                                                                                                                         | Override properties for the KeyboardAvoidingView.                                          |
| `textFormatters`                    | `Array<CometChatMentionsFormatter \| CometChatUrlsFormatter \| CometChatTextFormatter>`                                                             | Collection of text formatter classes to apply custom formatting.                           |
| `disableMentions`                   | `boolean`                                                                                                                                           | Flag to disable mention functionality.                                                     |
| `imageQuality`                      | `IntRange<1, 100>`                                                                                                                                  | Controls image quality when taking pictures from the camera.                               |
| `hideCameraOption`                  | `boolean`                                                                                                                                           | If true, hides the camera option from the attachment options.                              |
| `hideImageAttachmentOption`         | `boolean`                                                                                                                                           | If true, hides the image attachment option from the attachment options.                    |
| `hideVideoAttachmentOption`         | `boolean`                                                                                                                                           | If true, hides the video attachment option from the attachment options.                    |
| `hideAudioAttachmentOption`         | `boolean`                                                                                                                                           | If true, hides the audio attachment option from the attachment options.                    |
| `hideFileAttachmentOption`          | `boolean`                                                                                                                                           | If true, hides the file/document attachment option from the attachment options.            |
| `hidePollsAttachmentOption`         | `boolean`                                                                                                                                           | If true, hides the polls option from the attachment options.                               |
| `hideCollaborativeDocumentOption`   | `boolean`                                                                                                                                           | If true, hides the collaborative document option.                                          |
| `hideCollaborativeWhiteboardOption` | `boolean`                                                                                                                                           | If true, hides the collaborative whiteboard option.                                        |
| `hideAttachmentButton`              | `boolean`                                                                                                                                           | If true, hides the entire attachment button from the composer.                             |
| `hideStickersButton`                | `boolean`                                                                                                                                           | If true, hides the stickers button from the composer.                                      |
| `hideSendButton`                    | `boolean`                                                                                                                                           | If true, hides the send button from the composer.                                          |
| `hideAuxiliaryButtons`              | `boolean`                                                                                                                                           | If true, hides all auxiliary buttons (such as voice input, GIFs, or other plugin buttons). |
| `addAttachmentOptions`              | `({ user, group, composerId }: { user?: CometChat.User; group?: CometChat.Group; composerId: Map<any, any>; }) => CometChatMessageComposerAction[]` | Returns additional attachment options for the composer.                                    |
| `auxiliaryButtonsAlignment`         | `"left" \| "right"`                                                                                                                                 | Determines the alignment of auxiliary buttons.                                             |

#### Renamed Properties

| V4 Name                   | V5 Name                           | Type                       | Description                             |
| ------------------------- | --------------------------------- | -------------------------- | --------------------------------------- |
| `disableSoundForMessages` | `disableSoundForOutgoingMessages` | `boolean`                  | Renamed for clarity.                    |
| `customSoundForMessage`   | `customSoundForOutgoingMessage`   | `any`                      | Renamed for clarity.                    |
| `text`                    | `initialComposertext`             | `string`                   | Renamed for clarity.                    |
| `onChangeText`            | `onTextChange`                    | `(text: string) => void`   | Renamed for clarity.                    |
| `hideVoiceRecording`      | `hideVoiceRecordingButton`        | `boolean`                  | Renamed for clarity.                    |
| `attachmentOptions`       | `attachmentOptions`               | function signature changed | Function signature updated.             |
| `SecondaryButtonView`     | `AuxiliaryButtonView`             | function signature changed | Function signature updated and renamed. |

#### Removed Properties

| V4 Name                 | Type                            | Description                                                 |
| ----------------------- | ------------------------------- | ----------------------------------------------------------- |
| `FooterView`            | `React.FC`                      | Preview section at the bottom of the composer.              |
| `placeHolderText`       | `string`                        | Text shown in the composer when the input message is empty. |
| `maxHeight`             | `number`                        | Threshold value for input expansion.                        |
| `attachmentIcon`        | `ImageType`                     | Attachment icon.                                            |
| `messageComposerStyle`  | `MessageComposerStyleInterface` | Message Composer Styles.                                    |
| `hideLiveReaction`      | `boolean`                       | Hide the live reaction button.                              |
| `liveReactionIcon`      | `ImageType`                     | Live reaction icon.                                         |
| `voiceRecordingIconURL` | `string \| ImageType`           | Image URL for the voice recording icon.                     |
| `mediaRecorderStyle`    | `MediaRecorderStyle`            | Voice Recording Styles.                                     |
| `pauseIconUrl`          | `ImageType`                     | Pause icon.                                                 |
| `playIconUrl`           | `ImageType`                     | Play icon.                                                  |
| `recordIconUrl`         | `ImageType`                     | Record icon.                                                |
| `deleteIconUrl`         | `ImageType`                     | Delete icon.                                                |
| `stopIconUrl`           | `ImageType`                     | Stop icon.                                                  |
| `submitIconUrl`         | `ImageType`                     | Submit icon.                                                |
| `AIIconURL`             | `string`                        | AI Icon URL.                                                |
| `aiOptionsStyle`        | `AIOptionsStyle`                | AI Options Style.                                           |

### Incoming Call

#### New Properties

| Name                   | Type                                                               | Description                                                       |
| ---------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------- |
| `call`                 | `CometChat.Call \| CometChat.CustomMessage \| any`                 | The incoming call object, which can be a Call or a CustomMessage. |
| `ItemView`             | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the entire call item.                             |
| `TitleView`            | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the title section of the call item.               |
| `SubtitleView`         | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the subtitle section of the call item.            |
| `LeadingView`          | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the leading section of the call item.             |
| `TrailingView`         | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the trailing section of the call item.            |
| `disableSoundForCalls` | `boolean`                                                          | Flag to disable sound for incoming calls.                         |
| `customSoundForCalls`  | `string`                                                           | Path or identifier for a custom sound to play for incoming calls. |
| `onAccept`             | `(message: CometChat.BaseMessage) => void`                         | Callback fired when the call is accepted.                         |
| `onDecline`            | `(message: CometChat.BaseMessage) => void`                         | Callback fired when the call is declined.                         |
| `onError`              | `(e: CometChat.CometChatException) => void`                        | Callback fired when an error occurs.                              |
| `callSettingsBuilder`  | `typeof CometChatCalls.CallSettingsBuilder`                        | Optional custom call settings builder.                            |
| `style`                | `DeepPartial<IncomingCallStyle>`                                   | Custom style overrides for the incoming call component.           |

#### Renamed Properties

| V4 Name             | V5 Name        | Type                                                            | Description                                                |
| ------------------- | -------------- | --------------------------------------------------------------- | ---------------------------------------------------------- |
| `SubtitleView`      | `SubtitleView` | function signature changed                                      | Function signature updated.                                |
| `incomingCallStyle` | `style`        | `IncomingCallStyleInterface` → `DeepPartial<IncomingCallStyle>` | Style object for incoming call (renamed and type changed). |
| `onAccept`          | `onAccept`     | function signature changed                                      | Function signature updated.                                |
| `onDecline`         | `onDecline`    | function signature changed                                      | Function signature updated.                                |

#### Removed Properties

| V4 Name                  | Type                        | Description                     |
| ------------------------ | --------------------------- | ------------------------------- |
| `title`                  | `string`                    | Custom title text.              |
| `acceptButtonText`       | `string`                    | Accept button text.             |
| `declineButtonText`      | `string`                    | Decline button text.            |
| `avatarStyle`            | `AvatarStyleInterface`      | Style configuration for avatar. |
| `ongoingCallScreenStyle` | `OngoingCallStyleInterface` | Style for ongoing call screen.  |

### Outgoing Call

#### New Properties

| Name                     | Type                                                               | Description                                         |
| ------------------------ | ------------------------------------------------------------------ | --------------------------------------------------- |
| `onEndCallButtonPressed` | `(call: CometChat.Call) => void`                                   | Callback for when the end/cancel button is pressed. |
| `EndCallView`            | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the end call button.                |
| `TitleView`              | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the title section.                  |
| `SubtitleView`           | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the subtitle section.               |
| `AvatarView`             | `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Custom view for the avatar section.                 |

#### Renamed Properties

| V4 Name                  | V5 Name                  | Type                                                                             | Description                             |
| ------------------------ | ------------------------ | -------------------------------------------------------------------------------- | --------------------------------------- |
| `onDeclineButtonPressed` | `onEndCallButtonPressed` | `(call: CometChat.Call) => void`                                                 | Renamed for clarity and consistency.    |
| `declineButtonIcon`      | `EndCallView`            | `ImageType` → `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element` | Changed from icon/image to custom view. |
| `declineButtonText`      | `EndCallView`            | `string` → `(call: CometChat.Call \| CometChat.CustomMessage) => JSX.Element`    | Changed from text to custom view.       |
| `outgoingCallStyle`      | `style`                  | `OutgoingCallStyleInterface` → `DeepPartial<OutgoingCallStyle>`                  | Style object renamed and type changed.  |

#### Removed Properties

| V4 Name                    | Type                                        | Description                                           |
| -------------------------- | ------------------------------------------- | ----------------------------------------------------- |
| `buttonStyle`              | `ButtonStyleInterface`                      | Style object for button (removed, not present in v5). |
| `avatarStyle`              | `AvatarStyleInterface`                      | Style object for avatar (removed, not present in v5). |
| `declineButtonText`        | `string`                                    | Decline button text (replaced by `EndCallView`).      |
| `declineButtonIcon`        | `ImageType`                                 | Decline button icon (replaced by `EndCallView`).      |
| `onDeclineButtonPressed`   | `(call: CometChat.Call) => void`            | Callback (renamed to `onEndCallButtonPressed`).       |
| `outgoingCallStyle`        | `OutgoingCallStyleInterface`                | Style object (renamed to `style`).                    |
| `callSettingsBuilder`      | `typeof CometChatCalls.CallSettingsBuilder` | (Moved to new properties, type clarified).            |
| `theme`                    | `CometChatTheme`                            | Theme configuration (removed, not present in v5).     |
| `cardStyle`                | `CardStyleInterface`                        | Card style (removed, not present in v5).              |
| `ongoingCallConfiguration` | `OngoingCallConfigurationInterface`         | Ongoing call config (removed, not present in v5).     |

### Call Buttons

#### New Properties

| Name                        | Type                                                                                                                   | Description                                              |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `callSettingsBuilder`       | `(user?: CometChat.User, group?: CometChat.Group, isAudioOnly?: boolean) => typeof CometChatCalls.CallSettingsBuilder` | Function to build call settings for call initialization. |
| `outgoingCallConfiguration` | `OutgoingCallConfiguration`                                                                                            | Configuration for outgoing calls.                        |
| `style`                     | `DeepPartial<CallButtonStyle>`                                                                                         | Custom style overrides for the call button.              |

#### Renamed Properties

| V4 Name           | V5 Name               | Type                                                        | Description                            |
| ----------------- | --------------------- | ----------------------------------------------------------- | -------------------------------------- |
| `hideVoiceCall`   | `hideVoiceCallButton` | `boolean`                                                   | Renamed for clarity.                   |
| `hideVideoCall`   | `hideVideoCallButton` | `boolean`                                                   | Renamed for clarity.                   |
| `callButtonStyle` | `style`               | `CallButtonStyleInterface` → `DeepPartial<CallButtonStyle>` | Style object renamed and type changed. |

#### Removed Properties

| V4 Name              | Type                                                                   | Description                         |
| -------------------- | ---------------------------------------------------------------------- | ----------------------------------- |
| `voiceCallIconImage` | `ImageType`                                                            | Image icon for voice calls.         |
| `voiceCallIconText`  | `string`                                                               | Text label for the voice call icon. |
| `videoCallIconImage` | `ImageType`                                                            | Image icon for video calls.         |
| `videoCallIconText`  | `string`                                                               | Text label for the video call icon. |
| `onVoiceCallPress`   | `(params: { user?: CometChat.User, group?: CometChat.Group }) => void` | Callback for voice call icon click. |
| `onVideoCallPress`   | `(params: { user?: CometChat.User, group?: CometChat.Group }) => void` | Callback for video call icon click. |
| `callButtonStyle`    | `CallButtonStyleInterface`                                             | Style object (renamed to `style`).  |

### Call Logs

#### New Properties

| Name                        | Type                                               | Description                                                             |
| --------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------- |
| `LeadingView`               | `(call?: any) => JSX.Element`                      | Custom component for the leading view of each call log item.            |
| `TitleView`                 | `(call?: any) => JSX.Element`                      | Custom component for the title view of each call log item.              |
| `SubtitleView`              | `(call?: any) => JSX.Element`                      | Custom component for the subtitle view of each call log item.           |
| `ItemView`                  | `(call?: any) => JSX.Element`                      | Custom component for the entire call log item.                          |
| `TrailingView`              | `(call?: any) => JSX.Element`                      | Custom component for the trailing view of each call log item.           |
| `AppBarOptions`             | `() => JSX.Element`                                | Custom options to render in the AppBar.                                 |
| `callLogRequestBuilder`     | `any`                                              | Builder for custom call log requests.                                   |
| `datePattern`               | `ValueOf<typeof DateHelper.patterns>`              | Date format pattern for call logs.                                      |
| `showBackButton`            | `boolean`                                          | Flag to show the back button in the header.                             |
| `EmptyView`                 | `() => JSX.Element`                                | Custom component to render when the call log list is empty.             |
| `ErrorView`                 | `(e: CometChat.CometChatException) => JSX.Element` | Custom component to render in case of an error.                         |
| `LoadingView`               | `() => JSX.Element`                                | Custom component to render while loading call logs.                     |
| `hideError`                 | `boolean`                                          | Flag to hide the error view.                                            |
| `onCallIconPress`           | `(item: any) => void`                              | Callback when the call icon is pressed.                                 |
| `onError`                   | `(e: CometChat.CometChatException) => void`        | Callback for handling errors.                                           |
| `onBack`                    | `() => void`                                       | Callback for when the back button is pressed.                           |
| `onItemPress`               | `(call: any) => void`                              | Callback for when a call log item is pressed.                           |
| `style`                     | `DeepPartial<CometChatTheme["callLogsStyles"]>`    | Custom style overrides for the call logs.                               |
| `outgoingCallConfiguration` | `CometChatOutgoingCallInterface`                   | Configuration for outgoing calls.                                       |
| `onLoad`                    | `(list: any[]) => void`                            | Callback when the list is fetched and loaded.                           |
| `onEmpty`                   | `() => void`                                       | Callback when the list is empty (no items).                             |
| `onItemLongPress`           | `(prop: { call: any }) => void`                    | Called on a long press of the default list item view.                   |
| `hideHeader`                | `boolean`                                          | Hide the toolbar header.                                                |
| `hideLoadingState`          | `boolean`                                          | Hide the loading state.                                                 |
| `addOptions`                | `(call: any) => MenuItemInterface[]`               | Append more menu items on top of the default menu items for a call log. |
| `options`                   | `(call: any) => MenuItemInterface[]`               | Replace the default menu items entirely for a call log.                 |

#### Renamed Properties

| V4 Name            | V5 Name        | Type                                                                       | Description                                               |
| ------------------ | -------------- | -------------------------------------------------------------------------- | --------------------------------------------------------- |
| `TailView`         | `TrailingView` | `(param: { call?: any }) => JSX.Element` → `(call?: any) => JSX.Element`   | Signature and name updated for trailing view.             |
| `ListItemView`     | `ItemView`     | `(param: { call?: any }) => JSX.Element` → `(call?: any) => JSX.Element`   | Signature and name updated for item view.                 |
| `EmptyStateView`   | `EmptyView`    | `() => JSX.Element`                                                        | Custom component for empty state.                         |
| `ErrorStateView`   | `ErrorView`    | `() => JSX.Element` → `(e: CometChat.CometChatException) => JSX.Element`   | Signature and name updated for error view.                |
| `LoadingStateView` | `LoadingView`  | `() => JSX.Element`                                                        | Custom component for loading state.                       |
| `callLogsStyle`    | `style`        | `CallLogsStyleInterface` → `DeepPartial<CometChatTheme["callLogsStyles"]>` | Style object renamed and type changed.                    |
| `options`          | `options`      | Function signature updated                                                 | Now receives `(call: any)` instead of `{ message: any }`. |
| `datePattern`      | `datePattern`  | Type updated                                                               | Now uses `ValueOf<typeof DateHelper.patterns>`.           |

#### Removed Properties

| V4 Name                    | Type                            | Description                                      |
| -------------------------- | ------------------------------- | ------------------------------------------------ |
| `title`                    | `string`                        | Title of the call log list component.            |
| `emptyStateText`           | `string`                        | Text to be displayed when the state is empty.    |
| `errorStateText`           | `string`                        | Text to be displayed when error occurs.          |
| `loadingIcon`              | `ImageType`                     | Icon to be displayed when loading.               |
| `avatarStyle`              | `AvatarStyleInterface`          | Style configuration for avatar.                  |
| `listItemStyle`            | `ListItemStyleInterface`        | Style configuration for individual list items.   |
| `headViewContainerStyle`   | `StyleProp<ViewStyle>`          | Custom styling for headViewContainer.            |
| `bodyViewContainerStyle`   | `StyleProp<ViewStyle>`          | Custom styling for bodyViewContainer.            |
| `tailViewContainerStyle`   | `StyleProp<ViewStyle>`          | Custom styling for tailViewContainer.            |
| `missedAudioCallIconUrl`   | `string`                        | Custom missed audio call icon URL.               |
| `missedVideoCallIconUrl`   | `string`                        | Custom missed video call icon URL.               |
| `incomingAudioCallIconUrl` | `string`                        | Custom incoming audio call icon URL.             |
| `incomingVideoCallIconUrl` | `string`                        | Custom incoming video call icon URL.             |
| `outgoingAudioCallIconUrl` | `string`                        | Custom outgoing audio call icon URL.             |
| `outgoingVideoCallIconUrl` | `string`                        | Custom outgoing video call icon URL.             |
| `BackButton`               | `JSX.Element`                   | Custom back button element.                      |
| `onInfoIconPress`          | `(prop: { call: any }) => void` | Callback for info icon press.                    |
| `infoIcon`                 | `ImageType`                     | Info icon image.                                 |
| `theme`                    | `CometChatTheme`                | Theme configuration for the call logs component. |
| `hideSeperator`            | `boolean`                       | Toggle visibility of separator.                  |

***

## Next Steps

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/ui-kit/react-native/react-native-cli-integration">
    Set up the v5 UI Kit and send your first message
  </Card>

  <Card title="Theming" icon="palette" href="/ui-kit/react-native/theme">
    Customize colors, fonts, and styles with the new theme system
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Style individual components using the simplified v5 approach
  </Card>

  <Card title="Components Overview" icon="grid" href="/ui-kit/react-native/components-overview">
    Explore all v5 prebuilt UI components
  </Card>
</CardGroup>


# URL Formatter
Source: https://www.cometchat.com/docs/ui-kit/react-native/url-formatter-guide

Detect and style plain URLs, emails, and phone numbers as clickable links in CometChat React Native UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                                                               |
  | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package        | `@cometchat/chat-uikit-react-native`                                                                                                                                                                |
  | Key class      | `CometChatUrlsFormatter` (extends `CometChatTextFormatter`)                                                                                                                                         |
  | Required setup | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")`                                                                                                                             |
  | Purpose        | Auto-detects URLs, emails, and phone numbers in text messages and converts them to clickable links                                                                                                  |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/sample)                                                                                                                  |
  | Related        | [Custom Text Formatter](/docs/ui-kit/react-native/custom-text-formatter-guide) · [Mentions Formatter](/docs/ui-kit/react-native/mentions-formatter-guide) · [All Guides](/docs/ui-kit/react-native/guide-overview) |
</Accordion>

`CometChatUrlsFormatter` extends [CometChatTextFormatter](/docs/ui-kit/react-native/custom-text-formatter-guide) to detect URLs, email addresses, and phone numbers in text messages and render them as clickable links using React Native's `Linking` API.

***

## Features

| Feature         | Description                                         |
| --------------- | --------------------------------------------------- |
| URL detection   | Automatically detects HTTP/HTTPS URLs               |
| Email detection | Detects email addresses and opens mail client       |
| Phone detection | Detects phone numbers and opens dialer              |
| Custom styling  | Customize link text color and font                  |
| Native linking  | Uses React Native `Linking` API for native behavior |

***

## Usage

The `CometChatUrlsFormatter` is included by default in the UI Kit. You can also create a custom instance with custom styling:

<Tabs>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import React, { useState, useEffect, useMemo } from "react";
    import { View, SafeAreaView } from "react-native";
    import { CometChat } from "@cometchat/chat-sdk-react-native";
    import {
      CometChatMessageHeader,
      CometChatMessageList,
      CometChatMessageComposer,
      CometChatUrlsFormatter,
    } from "@cometchat/chat-uikit-react-native";

    function ChatScreen(): React.JSX.Element {
      const [chatUser, setChatUser] = useState<CometChat.User | undefined>();

      useEffect(() => {
        CometChat.getUser("uid").then((user) => {
          setChatUser(user);
        });
      }, []);

      const urlFormatter = useMemo(() => {
        const formatter = new CometChatUrlsFormatter();
        formatter.setStyle({
          linkTextColor: "#1a0dab",
          linkTextFont: {
            fontSize: 16,
            fontWeight: "500",
          },
        });
        return formatter;
      }, []);

      return (
        <SafeAreaView style={{ flex: 1 }}>
          {chatUser && (
            <View style={{ flex: 1 }}>
              <CometChatMessageHeader user={chatUser} />
              <CometChatMessageList
                user={chatUser}
                textFormatters={[urlFormatter]}
              />
              <CometChatMessageComposer user={chatUser} />
            </View>
          )}
        </SafeAreaView>
      );
    }

    export default ChatScreen;
    ```
  </Tab>
</Tabs>

***

## Customization

### Styling Links

Use the `setStyle` method to customize link appearance:

```tsx theme={null}
import { CometChatUrlsFormatter } from "@cometchat/chat-uikit-react-native";

const urlFormatter = new CometChatUrlsFormatter();

urlFormatter.setStyle({
  linkTextColor: "#007AFF",  // iOS blue
  linkTextFont: {
    fontSize: 16,
    fontWeight: "600",
  },
});
```

### Style Properties

| Property        | Type         | Description                                             |
| --------------- | ------------ | ------------------------------------------------------- |
| `linkTextColor` | `ColorValue` | Color of the link text                                  |
| `linkTextFont`  | `TextStyle`  | Font styling for link text (fontSize, fontWeight, etc.) |

***

## How It Works

The `CometChatUrlsFormatter` uses regex patterns to detect:

1. **URLs**: HTTP and HTTPS links
2. **Emails**: Email addresses (opens `mailto:` link)
3. **Phone numbers**: Phone numbers (opens `tel:` link)

When a link is tapped, it uses React Native's `Linking` API to open the appropriate handler:

```tsx theme={null}
// Internal implementation
const handlePress = async () => {
  let finalUrl = url;
  if (!url.match(/^(https?|mailto|tel):/i)) {
    finalUrl = `http://${url}`;
  }
  
  const canOpen = await Linking.canOpenURL(finalUrl);
  if (canOpen) {
    Linking.openURL(finalUrl);
  }
};
```

***

## Combining with Other Formatters

You can use multiple formatters together. The order matters — formatters are applied in sequence:

```tsx theme={null}
import {
  CometChatUrlsFormatter,
  CometChatMentionsFormatter,
} from "@cometchat/chat-uikit-react-native";

const urlFormatter = new CometChatUrlsFormatter();
const mentionsFormatter = new CometChatMentionsFormatter();

// Apply mentions first, then URLs
const textFormatters = [mentionsFormatter, urlFormatter];

<CometChatMessageList
  user={chatUser}
  textFormatters={textFormatters}
/>
```

***

## Next Steps

<CardGroup>
  <Card title="Custom Text Formatter" href="/ui-kit/react-native/custom-text-formatter-guide">
    Build custom inline text patterns.
  </Card>

  <Card title="Mentions Formatter" href="/ui-kit/react-native/mentions-formatter-guide">
    Add @mentions with styled tokens.
  </Card>

  <Card title="All Guides" href="/ui-kit/react-native/guide-overview">
    Browse all feature and formatter guides.
  </Card>

  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/sample">
    Full working sample application on GitHub.
  </Card>
</CardGroup>


# Users
Source: https://www.cometchat.com/docs/ui-kit/react-native/users

Display CometChat React Native UI Kit users with avatars, online status, search, filtering, selection callbacks, and chat navigation.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatUsers",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatUsers } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Searchable, scrollable list of all available users with avatar, name, and online/offline status.",
    "primaryOutput": {
      "prop": "onItemPress",
      "type": "(user: CometChat.User) => void"
    },
    "props": {
      "data": {
        "usersRequestBuilder": {
          "type": "CometChat.UsersRequestBuilder",
          "default": "SDK default (30 per page)",
          "note": "Pass the builder, not the result of .build()"
        },
        "searchRequestBuilder": {
          "type": "CometChat.UsersRequestBuilder",
          "default": "undefined"
        },
        "searchKeyword": {
          "type": "string",
          "default": "\"\""
        }
      },
      "callbacks": {
        "onItemPress": "(user: CometChat.User) => void",
        "onItemLongPress": "(user: CometChat.User) => void",
        "onBack": "() => void",
        "onSelection": "(list: CometChat.User[]) => void",
        "onError": "(error: CometChat.CometChatException) => void",
        "onEmpty": "() => void",
        "onLoad": "(list: CometChat.User[]) => void",
        "onSubmit": "(list: Array<CometChat.User>) => void"
      },
      "visibility": {
        "hideHeader": { "type": "boolean", "default": false },
        "showBackButton": { "type": "boolean", "default": false },
        "hideSearch": { "type": "boolean", "default": false },
        "hideError": { "type": "boolean", "default": false },
        "stickyHeaderVisibility": { "type": "boolean", "default": true },
        "hideSubmitButton": { "type": "boolean", "default": true },
        "hideLoadingState": { "type": "boolean", "default": false },
        "usersStatusVisibility": { "type": "boolean", "default": true },
        "title": { "type": "string", "default": "\"Users\"" }
      },
      "selection": {
        "selectionMode": {
          "type": "SelectionMode",
          "values": ["single", "multiple", "none"],
          "default": "none"
        }
      },
      "viewSlots": {
        "ItemView": "(user: CometChat.User) => JSX.Element",
        "LeadingView": "(user: CometChat.User) => JSX.Element",
        "TitleView": "(user: CometChat.User) => JSX.Element",
        "SubtitleView": "(user: CometChat.User) => JSX.Element",
        "TrailingView": "(user: CometChat.User) => JSX.Element",
        "LoadingView": "() => JSX.Element",
        "EmptyView": "() => JSX.Element",
        "ErrorView": "() => JSX.Element",
        "AppBarOptions": "() => JSX.Element"
      },
      "menu": {
        "options": "(user: CometChat.User) => MenuItemInterface[]",
        "addOptions": "(user: CometChat.User) => MenuItemInterface[]"
      },
      "search": {
        "searchPlaceholderText": { "type": "string", "default": "\"Search\"" }
      }
    },
    "events": [
      {
        "name": "ccUserBlocked",
        "payload": "CometChat.User",
        "description": "Triggered when logged-in user blocks another user"
      },
      {
        "name": "ccUserUnblocked",
        "payload": "CometChat.User",
        "description": "Triggered when logged-in user unblocks another user"
      }
    ],
    "sdkListeners": [
      "onUserOnline",
      "onUserOffline"
    ],
    "compositionExample": {
      "description": "User list wired to message view",
      "components": [
        "CometChatUsers",
        "CometChatMessageHeader",
        "CometChatMessageList",
        "CometChatMessageComposer"
      ],
      "flow": "onItemPress emits CometChat.User -> pass to MessageHeader, MessageList, MessageComposer"
    },
    "types": {
      "SelectionMode": {
        "single": "Select one user at a time",
        "multiple": "Select multiple users",
        "none": "No selection mode"
      }
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatUsers` is a contact list component. It renders all available users and emits the selected `CometChat.User` via `onItemPress`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a standard two-panel chat layout.

```tsx lines theme={null}
import { useState } from "react";
import { View, Text, StyleSheet } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { SafeAreaProvider } from "react-native-safe-area-context";
import {
  CometChatUsers,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function ChatApp() {
  const [selectedUser, setSelectedUser] = useState<CometChat.User>();

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <SafeAreaProvider>
        <CometChatThemeProvider>
          <View style={styles.container}>
            <View style={styles.sidebar}>
              <CometChatUsers onItemPress={(user) => setSelectedUser(user)} />
            </View>
            {selectedUser ? (
              <View style={styles.chatArea}>
                <CometChatMessageHeader user={selectedUser} />
                <CometChatMessageList user={selectedUser} />
                <CometChatMessageComposer user={selectedUser} />
              </View>
            ) : (
              <View style={styles.placeholder}>
                <Text>Select a user</Text>
              </View>
            )}
          </View>
        </CometChatThemeProvider>
      </SafeAreaProvider>
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, flexDirection: "row" },
  sidebar: { width: 350 },
  chatArea: { flex: 1 },
  placeholder: { flex: 1, justifyContent: "center", alignItems: "center" },
});
```

<Frame>
  <img />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";

function UsersDemo() {
  return <CometChatUsers />;
}

export default UsersDemo;
```

***

## Filtering Users

Pass a `CometChat.UsersRequestBuilder` to `usersRequestBuilder`. Pass the builder instance — not the result of `.build()`.

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function FilteredUsers() {
  return (
    <CometChatUsers
      usersRequestBuilder={
        new CometChat.UsersRequestBuilder().friendsOnly(true).setLimit(15)
      }
    />
  );
}
```

### Filter Recipes

| Recipe               | Code                                                                   |
| -------------------- | ---------------------------------------------------------------------- |
| Friends only         | `new CometChat.UsersRequestBuilder().friendsOnly(true)`                |
| Online users only    | `new CometChat.UsersRequestBuilder().setStatus("online")`              |
| Limit to 15 per page | `new CometChat.UsersRequestBuilder().setLimit(15)`                     |
| Search by keyword    | `new CometChat.UsersRequestBuilder().setSearchKeyword("alice")`        |
| Hide blocked users   | `new CometChat.UsersRequestBuilder().hideBlockedUsers(true)`           |
| Filter by roles      | `new CometChat.UsersRequestBuilder().setRoles(["admin", "moderator"])` |
| Filter by tags       | `new CometChat.UsersRequestBuilder().setTags(["vip"])`                 |
| Specific UIDs        | `new CometChat.UsersRequestBuilder().setUIDs(["uid1", "uid2"])`        |

Default page size is 30. The component uses infinite scroll — the next page loads as the user scrolls to the bottom.

A separate `searchRequestBuilder` can be passed to filter the search list independently from the main list.

Refer to [UsersRequestBuilder](/docs/sdk/react-native/retrieve-users) for the full builder API.

***

## Actions and Events

### Callback Props

#### onItemPress

Fires when a user row is tapped. Primary navigation hook — set the active user and render the message view.

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function UsersWithPress() {
  const handleItemPress = (user: CometChat.User) => {
    console.log("Selected:", user.getName());
  };

  return <CometChatUsers onItemPress={handleItemPress} />;
}
```

#### onItemLongPress

Fires when a user item is long-pressed, allowing additional actions like block or report.

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function UsersWithLongPress() {
  const handleLongPress = (user: CometChat.User) => {
    console.log("Long pressed:", user.getName());
  };

  return <CometChatUsers onItemLongPress={handleLongPress} />;
}
```

#### onSelection

Fires when users are selected/deselected in selection mode. Requires `selectionMode` to be set.

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function UsersWithSelection() {
  const handleSelection = (list: CometChat.User[]) => {
    console.log("Selected:", list.length);
  };

  return (
    <CometChatUsers
      selectionMode="multiple"
      onSelection={handleSelection}
    />
  );
}
```

#### onEmpty

Fires when the user list fetch returns zero results.

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";

function UsersWithEmptyHandler() {
  return (
    <CometChatUsers onEmpty={() => console.log("No users available")} />
  );
}
```

#### onError

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

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function UsersWithErrorHandler() {
  return (
    <CometChatUsers
      onError={(error: CometChat.CometChatException) => {
        console.error("CometChatUsers error:", error);
      }}
    />
  );
}
```

#### onLoad

Fires when the list is successfully fetched and loaded.

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function UsersWithLoadHandler() {
  const handleLoad = (list: CometChat.User[]) => {
    console.log("Users loaded:", list.length);
  };

  return <CometChatUsers onLoad={handleLoad} />;
}
```

### Global UI Events

`CometChatUIEventHandler` emits events subscribable from anywhere in the application. Subscribe in a `useEffect` and unsubscribe on cleanup.

| Event             | Fires when                               | Payload          |
| ----------------- | ---------------------------------------- | ---------------- |
| `ccUserBlocked`   | The logged-in user blocks another user   | `CometChat.User` |
| `ccUserUnblocked` | The logged-in user unblocks another user | `CometChat.User` |

```tsx lines theme={null}
import { useEffect } from "react";
import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function useUserEvents() {
  useEffect(() => {
    const listenerId = "USER_EVENTS_" + Date.now();
    
    CometChatUIEventHandler.addUserListener(listenerId, {
      ccUserBlocked: (user: CometChat.User) => {
        console.log("Blocked:", user.getName());
      },
      ccUserUnblocked: (user: CometChat.User) => {
        console.log("Unblocked:", user.getName());
      },
    });

    return () => {
      CometChatUIEventHandler.removeUserListener(listenerId);
    };
  }, []);
}
```

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual attachment needed unless additional side effects are required.

| SDK Listener    | Internal behavior                        |
| --------------- | ---------------------------------------- |
| `onUserOnline`  | Updates the user's status dot to online  |
| `onUserOffline` | Updates the user's status dot to offline |

***

## Custom View Slots

Each slot replaces a section of the default UI. Slots that accept a user parameter receive the `CometChat.User` object for that row.

| Slot            | Signature                               | Replaces              |
| --------------- | --------------------------------------- | --------------------- |
| `ItemView`      | `(user: CometChat.User) => JSX.Element` | Entire list item row  |
| `LeadingView`   | `(user: CometChat.User) => JSX.Element` | Avatar / left section |
| `TitleView`     | `(user: CometChat.User) => JSX.Element` | Name / title text     |
| `SubtitleView`  | `(user: CometChat.User) => JSX.Element` | Subtitle text         |
| `TrailingView`  | `(user: CometChat.User) => JSX.Element` | Right section         |
| `LoadingView`   | `() => JSX.Element`                     | Loading spinner       |
| `EmptyView`     | `() => JSX.Element`                     | Empty state           |
| `ErrorView`     | `() => JSX.Element`                     | Error state           |
| `AppBarOptions` | `() => JSX.Element`                     | Header bar options    |

### ItemView

Replace the entire list item row.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import {
  CometChatUsers,
  CometChatAvatar,
  useTheme,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function CustomItemViewUsers() {
  const theme = useTheme();

  const getItemView = (user: CometChat.User) => {
    return (
      <View
        style={{
          flexDirection: "row",
          flex: 1,
          paddingHorizontal: 16,
          paddingVertical: 12,
          alignItems: "center",
          borderWidth: 1,
          borderColor: theme.color.borderLight,
        }}>
        <CometChatAvatar
          name={user.getName()}
          image={{ uri: user.getAvatar() }}
          style={{
            containerStyle: { borderRadius: 8 },
            imageStyle: { borderRadius: 8 },
          }}
        />
        <Text
          style={{
            flex: 1,
            color: theme.color.textPrimary,
            fontSize: 16,
            marginLeft: 12,
            fontWeight: "500",
          }}
          numberOfLines={1}
          ellipsizeMode="tail">
          {user.getName()}
        </Text>
      </View>
    );
  };

  return <CometChatUsers ItemView={getItemView} />;
}
```

### LeadingView

Replace the avatar / left section.

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function LeadingViewUsers() {
  const getLeadingView = (user: CometChat.User) => {
    return (
      <View
        style={{
          width: 40,
          height: 40,
          borderRadius: 20,
          backgroundColor: "#6852D6",
          justifyContent: "center",
          alignItems: "center",
        }}>
        <Text style={{ color: "white", fontWeight: "bold" }}>
          {user.getName().charAt(0)}
        </Text>
      </View>
    );
  };

  return <CometChatUsers LeadingView={getLeadingView} />;
}
```

### SubtitleView

Replace the subtitle text.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { Text } from "react-native";

function SubtitleViewUsers() {
  const getSubtitleView = (user: CometChat.User) => {
    return (
      <Text style={{ fontSize: 12, color: "#727272" }}>
        {user.getStatus() === "online" ? "Online" : "Offline"}
      </Text>
    );
  };

  return <CometChatUsers SubtitleView={getSubtitleView} />;
}
```

### TrailingView

Replace the right section.

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { TouchableOpacity, Text } from "react-native";

function TrailingViewUsers() {
  const getTrailingView = (user: CometChat.User) => {
    return (
      <TouchableOpacity onPress={() => console.log("Follow:", user.getName())}>
        <Text style={{ color: "#6852D6", fontWeight: "500" }}>Follow</Text>
      </TouchableOpacity>
    );
  };

  return <CometChatUsers TrailingView={getTrailingView} />;
}
```

### AppBarOptions

Custom view for the header bar options.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { TouchableOpacity, Text } from "react-native";

function AppBarOptionsUsers() {
  return (
    <CometChatUsers
      AppBarOptions={() => (
        <TouchableOpacity onPress={() => console.log("Settings pressed")}>
          <Text style={{ color: "#6852D6", fontWeight: "500" }}>Settings</Text>
        </TouchableOpacity>
      )}
    />
  );
}
```

### options

Custom context menu actions for each user item.

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function OptionsUsers() {
  const getOptions = (user: CometChat.User) => [
    {
      text: "Block",
      onPress: () => console.log("Block:", user.getName()),
    },
    {
      text: "Report",
      onPress: () => console.log("Report:", user.getName()),
    },
  ];

  return <CometChatUsers options={getOptions} />;
}
```

***

## Common Patterns

### Custom empty state with CTA

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { View, Text, TouchableOpacity } from "react-native";

function EmptyStateUsers() {
  return (
    <CometChatUsers
      EmptyView={() => (
        <View style={{ flex: 1, justifyContent: "center", alignItems: "center", padding: 40 }}>
          <Text style={{ fontSize: 16, marginBottom: 16 }}>No users found</Text>
          <TouchableOpacity
            style={{ backgroundColor: "#6852D6", paddingHorizontal: 20, paddingVertical: 10, borderRadius: 8 }}
            onPress={() => console.log("Invite users")}>
            <Text style={{ color: "white" }}>Invite users</Text>
          </TouchableOpacity>
        </View>
      )}
    />
  );
}
```

### Friends-only list

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function FriendsOnlyUsers() {
  return (
    <CometChatUsers
      usersRequestBuilder={
        new CometChat.UsersRequestBuilder().friendsOnly(true).setLimit(15)
      }
    />
  );
}
```

### Multi-select with submit

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

function MultiSelectUsers() {
  const handleSubmit = (users: Array<CometChat.User>) => {
    console.log("Selected users:", users.length);
  };

  return (
    <CometChatUsers
      selectionMode="multiple"
      hideSubmitButton={false}
      onSubmit={handleSubmit}
    />
  );
}
```

### Hide all chrome — minimal list

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";

function MinimalUsers() {
  return (
    <CometChatUsers
      hideSearch={true}
      usersStatusVisibility={false}
      stickyHeaderVisibility={false}
      hideHeader={true}
    />
  );
}
```

***

## Styling

The component uses the theme system from `CometChatThemeProvider`. Pass a `style` prop to customize the appearance.

<Frame>
  <img />
</Frame>

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";

function StyledUsers() {
  return (
    <CometChatUsers
      style={{
        titleStyle: {
          color: "#FBAA75",
        },
        titleSeparatorStyle: {
          borderBottomColor: "#FBAA75",
        },
        itemStyle: {
          avatarStyle: {
            containerStyle: {
              borderRadius: 8,
              backgroundColor: "#FBAA75",
            },
            imageStyle: {
              borderRadius: 8,
            },
          },
        },
      }}
    />
  );
}
```

### Style Properties

| Property              | Type        | Description                                                                  |
| --------------------- | ----------- | ---------------------------------------------------------------------------- |
| `containerStyle`      | `ViewStyle` | Style for the root container                                                 |
| `headerStyle`         | `ViewStyle` | Style for the header section                                                 |
| `titleStyle`          | `TextStyle` | Style for the header title                                                   |
| `titleSeparatorStyle` | `ViewStyle` | Style for section header separators                                          |
| `itemStyle`           | `object`    | Style for list items (includes `avatarStyle`, `titleStyle`, `subtitleStyle`) |
| `searchStyle`         | `object`    | Style for the search bar                                                     |

***

## Props

All props are optional unless noted.

### EmptyView

Custom component displayed when there are no users.

|         |                      |
| ------- | -------------------- |
| Type    | `() => JSX.Element`  |
| Default | Built-in empty state |

***

### ErrorView

Custom component displayed when an error occurs.

|         |                      |
| ------- | -------------------- |
| Type    | `() => JSX.Element`  |
| Default | Built-in error state |

***

### hideError

Hides the error state view.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideHeader

Hides the entire header bar.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideLoadingState

Hides the loading state while fetching users.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideSearch

Hides the search bar.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideSubmitButton

Hides the submit button when selection mode is enabled.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### ItemView

Custom renderer for the entire list item row.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `(user: CometChat.User) => JSX.Element` |
| Default | Built-in list item                      |

***

### LeadingView

Custom renderer for the avatar / left section.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `(user: CometChat.User) => JSX.Element` |
| Default | Built-in avatar                         |

***

### LoadingView

Custom component displayed during the loading state.

|         |                            |
| ------- | -------------------------- |
| Type    | `() => JSX.Element`        |
| Default | Built-in loading indicator |

***

### onBack

Callback fired when the back button is pressed.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onEmpty

Callback fired when the user list is empty.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onError

Callback fired when the component encounters an error.

|         |                                                 |
| ------- | ----------------------------------------------- |
| Type    | `(error: CometChat.CometChatException) => void` |
| Default | `undefined`                                     |

***

### onItemLongPress

Callback fired when a user row is long-pressed.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `(user: CometChat.User) => void` |
| Default | `undefined`                      |

***

### onItemPress

Callback fired when a user row is tapped.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `(user: CometChat.User) => void` |
| Default | `undefined`                      |

***

### onLoad

Callback fired when users are loaded.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `(list: CometChat.User[]) => void` |
| Default | `undefined`                        |

***

### onSelection

Callback fired when users are selected/deselected. Requires `selectionMode` to be set.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `(list: CometChat.User[]) => void` |
| Default | `undefined`                        |

***

### onSubmit

Callback fired when the submit button is pressed. Requires `selectionMode` to be set.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `(list: Array<CometChat.User>) => void` |
| Default | `undefined`                             |

***

### searchKeyword

Pre-fills the search and filters the user list.

|         |          |
| ------- | -------- |
| Type    | `string` |
| Default | `""`     |

***

### searchRequestBuilder

Request builder with search parameters to fetch users.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `CometChat.UsersRequestBuilder` |
| Default | `undefined`                     |

***

### selectionMode

Enables single or multi-select mode on list items.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `"single" \| "multiple" \| "none"` |
| Default | `"none"`                           |

***

### showBackButton

Shows the back button in the header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### stickyHeaderVisibility

Shows/hides alphabetical section headers (A, B, C…).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### SubtitleView

Custom renderer for the subtitle text.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `(user: CometChat.User) => JSX.Element` |
| Default | `undefined`                             |

***

### TitleView

Custom renderer for the name / title text.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `(user: CometChat.User) => JSX.Element` |
| Default | Built-in title                          |

***

### TrailingView

Custom renderer for the right section.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `(user: CometChat.User) => JSX.Element` |
| Default | Built-in trailing view                  |

***

### usersRequestBuilder

Controls which users load and in what order.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `CometChat.UsersRequestBuilder` |
| Default | SDK default (30 per page)       |

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

***

### usersStatusVisibility

Shows/hides the online/offline status indicator.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### title

Custom title for the header.

|         |           |
| ------- | --------- |
| Type    | `string`  |
| Default | `"Users"` |

***

### AppBarOptions

Custom component for the header bar options.

|         |                     |
| ------- | ------------------- |
| Type    | `() => JSX.Element` |
| Default | `undefined`         |

***

### addOptions

Function to append additional menu items to the default context menu.

|         |                                                 |
| ------- | ----------------------------------------------- |
| Type    | `(user: CometChat.User) => MenuItemInterface[]` |
| Default | `undefined`                                     |

***

### options

Function to replace the default context menu items entirely.

|         |                                                 |
| ------- | ----------------------------------------------- |
| Type    | `(user: CometChat.User) => MenuItemInterface[]` |
| Default | `undefined`                                     |

***

### searchPlaceholderText

Placeholder text for the search input.

|         |            |
| ------- | ---------- |
| Type    | `string`   |
| Default | `"Search"` |

***

## Next Steps

<CardGroup>
  <Card title="Conversations" icon="comments" href="/ui-kit/react-native/conversations">
    Display and manage the list of recent chats
  </Card>

  <Card title="Groups" icon="user-group" href="/ui-kit/react-native/groups">
    Display and manage group conversations
  </Card>

  <Card title="Message List" icon="message" href="/ui-kit/react-native/message-list">
    Display the full chat interface after selecting a user
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>


# AI Features
Source: https://www.cometchat.com/docs/ui-kit/ios/ai-features

Complete guide to AI-powered chat features in iOS apps - conversation starters, smart replies, and summaries

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "category": "ai",
    "features": [
      {"name": "aiAgentChat", "description": "Chat with AI-powered assistants", "component": "CometChatMessages", "enabledByDefault": false},
      {"name": "chatHistory", "description": "Browse and resume previous AI sessions", "component": "CometChatAIAssistanceChatHistory", "enabledByDefault": false},
      {"name": "streamingResponses", "description": "Real-time AI message streaming", "component": "CometChatMessageList", "enabledByDefault": false},
      {"name": "suggestedMessages", "description": "AI-powered conversation starters and smart replies", "component": "CometChatMessageComposer", "enabledByDefault": false}
    ],
    "dashboardSetup": {
      "location": "CometChat Dashboard → AI",
      "features": ["Conversation Starter", "Smart Replies", "Conversation Summary"]
    },
    "relatedComponents": ["CometChatMessages", "CometChatAIAssistanceChatHistory", "CometChatMessageList", "CometChatMessageComposer"]
  }
  ```
</Accordion>

## Overview

CometChat AI features enhance your chat experience with intelligent suggestions and summaries. Once enabled in your dashboard, they integrate automatically into the UI Kit components.

<Frame>
  <img />
</Frame>

| Feature               | What It Does                            | Where It Appears                   |
| --------------------- | --------------------------------------- | ---------------------------------- |
| Conversation Starters | Suggests opening messages for new chats | `CometChatMessageList`             |
| Smart Replies         | Suggests responses based on context     | `CometChatMessageComposer`         |
| Conversation Summary  | Summarizes long conversations           | `CometChatMessageComposer`         |
| AI Assistant          | Chat with AI bot                        | `CometChatAIAssistanceChatHistory` |

***

## Enable AI Features

<Steps>
  <Step title="Open CometChat Dashboard">
    Go to [app.cometchat.com](https://app.cometchat.com) and select your app.
  </Step>

  <Step title="Navigate to AI Features">
    Click **AI** in the sidebar, then enable the features you want:

    * ✅ Conversation Starter
    * ✅ Smart Replies
    * ✅ Conversation Summary
  </Step>

  <Step title="Configure (Optional)">
    Customize AI behavior, response style, and triggers in the dashboard settings.
  </Step>
</Steps>

**That's it!** AI features now work automatically in your app.

***

## Conversation Starters

When a user opens a new chat with no message history, AI suggests conversation openers.

<Frame>
  <img />
</Frame>

### How It Works

1. User opens chat with someone they haven't messaged before
2. AI analyzes user profiles and context
3. Suggested messages appear in the message list
4. User taps a suggestion to send it

### Implementation

Conversation starters appear automatically in `CometChatMessages`:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK

    class ChatViewController: UIViewController {
        
        func openChatWithUser(uid: String) {
            CometChat.getUser(UID: uid) { [weak self] user in
                DispatchQueue.main.async {
                    let messagesVC = CometChatMessages()
                    messagesVC.user = user
                    
                    // Conversation starters appear automatically
                    // if enabled in dashboard and no previous messages exist
                    
                    self?.navigationController?.pushViewController(messagesVC, animated: true)
                }
            } onError: { error in
                print("Error: \(error?.errorDescription ?? "")")
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Smart Replies

AI suggests contextual responses based on the conversation.

<Frame>
  <img />
</Frame>

### How It Works

1. User receives a message
2. AI analyzes the message and conversation context
3. Smart reply suggestions appear in the composer action sheet
4. User taps a suggestion to insert it

### Implementation

Smart replies appear automatically in `CometChatMessageComposer`:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK

    class ChatViewController: UIViewController {
        
        func openChat(with user: CometChat.User) {
            let messagesVC = CometChatMessages()
            messagesVC.user = user
            
            // Smart replies appear automatically in the composer
            // when enabled in dashboard
            
            navigationController?.pushViewController(messagesVC, animated: true)
        }
    }
    ```
  </Tab>
</Tabs>

***

## Conversation Summary

AI generates summaries of long conversations so users can catch up quickly.

<Frame>
  <img />
</Frame>

### How It Works

1. User opens a conversation with many messages
2. User taps the summary option in composer action sheet
3. AI processes the conversation
4. Summary of key points is displayed

### Implementation

Conversation summary is available automatically:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK

    class ChatViewController: UIViewController {
        
        func openChat(with user: CometChat.User) {
            let messagesVC = CometChatMessages()
            messagesVC.user = user
            
            // Conversation summary option appears in composer action sheet
            // when enabled in dashboard and sufficient messages exist
            
            navigationController?.pushViewController(messagesVC, animated: true)
        }
    }
    ```
  </Tab>
</Tabs>

***

## AI Assistant Chat History

View and continue conversations with AI assistants.

### Basic Implementation

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK

    class AIAssistantViewController: UIViewController {
        
        var user: CometChat.User!
        
        func showAIChatHistory() {
            let chatHistory = CometChatAIAssistanceChatHistory()
            chatHistory.user = user  // Required
            
            navigationController?.pushViewController(chatHistory, animated: true)
        }
    }
    ```
  </Tab>
</Tabs>

### Full Implementation with Callbacks

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK

    class AIAssistantViewController: UIViewController {
        
        var user: CometChat.User!
        
        func showAIChatHistory() {
            let chatHistory = CometChatAIAssistanceChatHistory()
            chatHistory.user = user
            
            // Handle new chat button
            chatHistory.onNewChatButtonClicked = { [weak self] in
                self?.startNewAIChat()
            }
            
            // Handle message tap
            chatHistory.onMessageClicked = { message in
                print("Tapped message: \(message.text ?? "")")
            }
            
            // Handle load success
            chatHistory.set(onLoad: { messages in
                print("Loaded \(messages.count) AI messages")
            })
            
            // Handle empty state
            chatHistory.set(onEmpty: {
                print("No AI chat history")
            })
            
            // Handle errors
            chatHistory.set(onError: { [weak self] error in
                self?.showError(error.localizedDescription)
            })
            
            navigationController?.pushViewController(chatHistory, animated: true)
        }
        
        private func startNewAIChat() {
            // Navigate to new AI chat
            print("Starting new AI conversation")
        }
        
        private func showError(_ message: String) {
            let alert = UIAlertController(title: "Error", message: message, preferredStyle: .alert)
            alert.addAction(UIAlertAction(title: "OK", style: .default))
            present(alert, animated: true)
        }
    }
    ```
  </Tab>
</Tabs>

### Customize AI Chat History Styling

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift

    class AIAssistantViewController: UIViewController {
        
        var user: CometChat.User!
        
        func showStyledAIChatHistory() {
            let chatHistory = CometChatAIAssistanceChatHistory()
            chatHistory.user = user
            
            // Custom styling
            let style = AiAssistantChatHistoryStyle()
            style.backgroundColor = .systemBackground
            style.itemTextFont = UIFont.systemFont(ofSize: 16, weight: .medium)
            style.itemTextColor = .label
            style.newChatTitleFont = UIFont.systemFont(ofSize: 18, weight: .bold)
            style.newChatTitleColor = .systemBlue
            chatHistory.style = style
            
            // Custom empty state
            chatHistory.emptyStateText = "No AI conversations yet"
            chatHistory.emptyStateSubtitleText = "Tap 'New Chat' to start"
            
            // Custom date formatting
            chatHistory.dateTimeFormatter.today = { timestamp in
                let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
                let formatter = DateFormatter()
                formatter.timeStyle = .short
                return "Today at \(formatter.string(from: date))"
            }
            
            navigationController?.pushViewController(chatHistory, animated: true)
        }
    }
    ```
  </Tab>
</Tabs>


# Calling Features
Source: https://www.cometchat.com/docs/ui-kit/ios/call-features

Complete guide to adding voice and video calling to iOS apps with CometChat UI Kit - production-ready code included

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "category": "calling",
    "features": [
      {"name": "voiceCalling", "description": "One-on-one and group audio calls", "component": "CometChatCallButtons", "enabledByDefault": true},
      {"name": "videoCalling", "description": "One-on-one and group video calls", "component": "CometChatCallButtons", "enabledByDefault": true},
      {"name": "callLogs", "description": "View call history with metadata", "component": "CometChatCallLogs", "enabledByDefault": true},
      {"name": "incomingCall", "description": "Handle incoming call UI with accept/reject", "component": "CometChatIncomingCall", "enabledByDefault": true},
      {"name": "outgoingCall", "description": "Display outgoing call screen while connecting", "component": "CometChatOutgoingCall", "enabledByDefault": true},
      {"name": "ongoingCall", "description": "Active call interface with controls", "component": "CometChatOngoingCall", "enabledByDefault": true}
    ],
    "sdkDependencies": {
      "required": "CometChatCallsSDK 4.2.2",
      "permissions": ["NSCameraUsageDescription", "NSMicrophoneUsageDescription"]
    },
    "relatedComponents": ["CometChatCallButtons", "CometChatCallLogs", "CometChatIncomingCall", "CometChatOutgoingCall", "CometChatOngoingCall"]
  }
  ```
</Accordion>

## Overview

Add one-on-one and group audio/video calling to your iOS app. Once integrated, call buttons automatically appear in chat headers, and incoming/outgoing call screens are handled for you.

<Frame>
  <img />
</Frame>

***

## Quick Setup

<Steps>
  <Step title="Add Dependencies">
    Add to your `Podfile`:

    ```ruby theme={null}
    platform :ios, '13.0'
    use_frameworks!

    target 'YourApp' do
      pod 'CometChatUIKitSwift', '5.1.9'
      pod 'CometChatCallsSDK', '4.2.2'
    end
    ```

    Run:

    ```bash theme={null}
    pod install
    ```
  </Step>

  <Step title="Add Permissions">
    Add to `Info.plist`:

    ```xml theme={null}
    <key>NSCameraUsageDescription</key>
    <string>Camera access required for video calls</string>

    <key>NSMicrophoneUsageDescription</key>
    <string>Microphone access required for voice and video calls</string>
    ```
  </Step>

  <Step title="Initialize CometChat">
    In `SceneDelegate.swift`:

    ```swift lines theme={null}
    import CometChatUIKitSwift

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = (scene as? UIWindowScene) else { return }
        
        let uikitSettings = UIKitSettings()
            .set(appID: "YOUR_APP_ID")
            .set(authKey: "YOUR_AUTH_KEY")
            .set(region: "YOUR_REGION")  // "us", "eu", or "in"
            .build()
        
        CometChatUIKit.init(uiKitSettings: uikitSettings) { result in
            switch result {
            case .success:
                CometChatUIKit.login(uid: "cometchat-uid-1") { loginResult in
                    switch loginResult {
                    case .success:
                        // Calling is now enabled automatically
                        print("✅ Ready for calls")
                    case .onError(let error):
                        print("❌ Login failed: \(error.description)")
                    @unknown default:
                        break
                    }
                }
            case .failure(let error):
                print("❌ Init failed: \(error.localizedDescription)")
            }
        }
    }
    ```
  </Step>
</Steps>

**That's it!** Call buttons now appear in `CometChatMessages` header automatically.

***

## Production-Ready Implementation

Complete app with calling, chat, and call history:

<Tabs>
  <Tab title="SceneDelegate.swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK

    class SceneDelegate: UIResponder, UIWindowSceneDelegate {
        
        var window: UIWindow?
        
        func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
            guard let windowScene = (scene as? UIWindowScene) else { return }
            
            // Initialize CometChat
            let uikitSettings = UIKitSettings()
                .set(appID: "YOUR_APP_ID")
                .set(authKey: "YOUR_AUTH_KEY")
                .set(region: "YOUR_REGION")
                .subscribePresenceForAllUsers()
                .build()
            
            CometChatUIKit.init(uiKitSettings: uikitSettings) { [weak self] result in
                switch result {
                case .success:
                    print("✅ CometChat initialized")
                    self?.loginAndSetupUI(windowScene: windowScene)
                    
                case .failure(let error):
                    print("❌ Init failed: \(error.localizedDescription)")
                }
            }
        }
        
        private func loginAndSetupUI(windowScene: UIWindowScene) {
            CometChatUIKit.login(uid: "cometchat-uid-1") { [weak self] result in
                switch result {
                case .success:
                    print("✅ Logged in")
                    DispatchQueue.main.async {
                        self?.setupMainInterface(windowScene: windowScene)
                    }
                    
                case .onError(let error):
                    print("❌ Login failed: \(error.description)")
                    
                @unknown default:
                    break
                }
            }
        }
        
        private func setupMainInterface(windowScene: UIWindowScene) {
            let tabBar = MainTabBarController()
            
            window = UIWindow(windowScene: windowScene)
            window?.rootViewController = tabBar
            window?.makeKeyAndVisible()
        }
    }
    ```
  </Tab>

  <Tab title="MainTabBarController.swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift

    class MainTabBarController: UITabBarController {
        
        override func viewDidLoad() {
            super.viewDidLoad()
            setupTabs()
            setupAppearance()
        }
        
        private func setupTabs() {
            // Chats Tab - with calling enabled
            let chatsVC = CometChatConversationsWithMessages()
            let chatsNav = UINavigationController(rootViewController: chatsVC)
            chatsNav.tabBarItem = UITabBarItem(
                title: "Chats",
                image: UIImage(systemName: "message"),
                selectedImage: UIImage(systemName: "message.fill")
            )
            
            // Calls Tab - call history
            let callsVC = CometChatCallLogs()
            callsVC.set(onItemClick: { [weak self] callLog in
                self?.handleCallLogTap(callLog)
            })
            let callsNav = UINavigationController(rootViewController: callsVC)
            callsNav.tabBarItem = UITabBarItem(
                title: "Calls",
                image: UIImage(systemName: "phone"),
                selectedImage: UIImage(systemName: "phone.fill")
            )
            
            // Users Tab
            let usersVC = CometChatUsersWithMessages()
            let usersNav = UINavigationController(rootViewController: usersVC)
            usersNav.tabBarItem = UITabBarItem(
                title: "Users",
                image: UIImage(systemName: "person.2"),
                selectedImage: UIImage(systemName: "person.2.fill")
            )
            
            // Groups Tab
            let groupsVC = CometChatGroupsWithMessages()
            let groupsNav = UINavigationController(rootViewController: groupsVC)
            groupsNav.tabBarItem = UITabBarItem(
                title: "Groups",
                image: UIImage(systemName: "person.3"),
                selectedImage: UIImage(systemName: "person.3.fill")
            )
            
            viewControllers = [chatsNav, callsNav, usersNav, groupsNav]
        }
        
        private func setupAppearance() {
            tabBar.tintColor = .systemBlue
            tabBar.backgroundColor = .systemBackground
        }
        
        private func handleCallLogTap(_ callLog: CallLog) {
            // Get the other user from call log
            let loggedInUser = CometChat.getLoggedInUser()
            var otherUserUID: String?
            
            if let initiator = callLog.initiator as? CallUser,
               initiator.uid != loggedInUser?.uid {
                otherUserUID = initiator.uid
            } else if let receiver = callLog.receiver as? CallUser {
                otherUserUID = receiver.uid
            }
            
            guard let uid = otherUserUID else { return }
            
            // Fetch user and open chat
            CometChat.getUser(UID: uid) { [weak self] user in
                DispatchQueue.main.async {
                    let messagesVC = CometChatMessages()
                    messagesVC.user = user
                    
                    if let nav = self?.selectedViewController as? UINavigationController {
                        nav.pushViewController(messagesVC, animated: true)
                    }
                }
            } onError: { error in
                print("Error: \(error?.errorDescription ?? "")")
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Initiate Calls Programmatically

### Voice Call to User

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatSDK

    func startVoiceCall(to userUID: String) {
        let call = CometChat.Call(
            receiverId: userUID,
            callType: .audio,
            receiverType: .user
        )
        
        CometChat.initiateCall(call: call) { call in
            print("✅ Voice call started: \(call?.sessionId ?? "")")
        } onError: { error in
            print("❌ Call failed: \(error?.errorDescription ?? "")")
        }
    }

    // Usage
    startVoiceCall(to: "cometchat-uid-2")
    ```
  </Tab>
</Tabs>

### Video Call to User

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatSDK

    func startVideoCall(to userUID: String) {
        let call = CometChat.Call(
            receiverId: userUID,
            callType: .video,
            receiverType: .user
        )
        
        CometChat.initiateCall(call: call) { call in
            print("✅ Video call started: \(call?.sessionId ?? "")")
        } onError: { error in
            print("❌ Call failed: \(error?.errorDescription ?? "")")
        }
    }

    // Usage
    startVideoCall(to: "cometchat-uid-2")
    ```
  </Tab>
</Tabs>

### Group Call

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatSDK

    func startGroupCall(to groupGUID: String, type: CometChat.CallType) {
        let call = CometChat.Call(
            receiverId: groupGUID,
            callType: type,
            receiverType: .group
        )
        
        CometChat.initiateCall(call: call) { call in
            print("✅ Group call started: \(call?.sessionId ?? "")")
        } onError: { error in
            print("❌ Call failed: \(error?.errorDescription ?? "")")
        }
    }

    // Usage
    startGroupCall(to: "group-guid", type: .video)
    ```
  </Tab>
</Tabs>

***

## Custom Call Buttons

Add call buttons anywhere in your app:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK

    class UserProfileViewController: UIViewController {
        
        var user: CometChat.User!
        
        private let voiceCallButton: UIButton = {
            let button = UIButton(type: .system)
            button.setImage(UIImage(systemName: "phone.fill"), for: .normal)
            button.setTitle(" Voice Call", for: .normal)
            button.backgroundColor = .systemGreen
            button.tintColor = .white
            button.layer.cornerRadius = 12
            button.translatesAutoresizingMaskIntoConstraints = false
            return button
        }()
        
        private let videoCallButton: UIButton = {
            let button = UIButton(type: .system)
            button.setImage(UIImage(systemName: "video.fill"), for: .normal)
            button.setTitle(" Video Call", for: .normal)
            button.backgroundColor = .systemBlue
            button.tintColor = .white
            button.layer.cornerRadius = 12
            button.translatesAutoresizingMaskIntoConstraints = false
            return button
        }()
        
        override func viewDidLoad() {
            super.viewDidLoad()
            setupUI()
        }
        
        private func setupUI() {
            view.backgroundColor = .systemBackground
            
            let stackView = UIStackView(arrangedSubviews: [voiceCallButton, videoCallButton])
            stackView.axis = .horizontal
            stackView.spacing = 16
            stackView.distribution = .fillEqually
            stackView.translatesAutoresizingMaskIntoConstraints = false
            
            view.addSubview(stackView)
            
            NSLayoutConstraint.activate([
                stackView.centerXAnchor.constraint(equalTo: view.centerXAnchor),
                stackView.centerYAnchor.constraint(equalTo: view.centerYAnchor),
                stackView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 32),
                stackView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -32),
                
                voiceCallButton.heightAnchor.constraint(equalToConstant: 50),
                videoCallButton.heightAnchor.constraint(equalToConstant: 50)
            ])
            
            voiceCallButton.addTarget(self, action: #selector(voiceCallTapped), for: .touchUpInside)
            videoCallButton.addTarget(self, action: #selector(videoCallTapped), for: .touchUpInside)
        }
        
        @objc private func voiceCallTapped() {
            initiateCall(type: .audio)
        }
        
        @objc private func videoCallTapped() {
            initiateCall(type: .video)
        }
        
        private func initiateCall(type: CometChat.CallType) {
            guard let uid = user.uid else { return }
            
            let call = CometChat.Call(
                receiverId: uid,
                callType: type,
                receiverType: .user
            )
            
            CometChat.initiateCall(call: call) { [weak self] call in
                print("✅ Call initiated")
            } onError: { [weak self] error in
                self?.showError(error?.errorDescription ?? "Call failed")
            }
        }
        
        private func showError(_ message: String) {
            let alert = UIAlertController(title: "Error", message: message, preferredStyle: .alert)
            alert.addAction(UIAlertAction(title: "OK", style: .default))
            present(alert, animated: true)
        }
    }
    ```
  </Tab>
</Tabs>

***

## Using CometChatCallButtons Component

The built-in call buttons component:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK

    class ChatHeaderViewController: UIViewController {
        
        var user: CometChat.User!
        
        override func viewDidLoad() {
            super.viewDidLoad()
            setupCallButtons()
        }
        
        private func setupCallButtons() {
            let callButtons = CometChatCallButtons()
            callButtons.user = user
            
            // Customize actions
            callButtons.set(onVoiceCallClick: { user, group in
                print("Voice call to: \(user?.name ?? group?.name ?? "")")
            })
            
            callButtons.set(onVideoCallClick: { user, group in
                print("Video call to: \(user?.name ?? group?.name ?? "")")
            })
            
            callButtons.set(onError: { error in
                print("Error: \(error.errorDescription)")
            })
            
            // Add to navigation bar
            let hostingController = UIHostingController(rootView: callButtons)
            addChild(hostingController)
            
            navigationItem.rightBarButtonItem = UIBarButtonItem(customView: hostingController.view)
        }
    }
    ```
  </Tab>
</Tabs>

***

## Handle Incoming Calls

Incoming calls are handled automatically. For custom handling:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatSDK

    class CallHandler: NSObject, CometChatCallDelegate {
        
        static let shared = CallHandler()
        
        func registerForCalls() {
            CometChat.calldelegate = self
        }
        
        // Called when receiving an incoming call
        func onIncomingCallReceived(incomingCall: CometChat.Call?, error: CometChat.CometChatException?) {
            guard let call = incomingCall else { return }
            
            print("📞 Incoming call from: \(call.sender?.name ?? "")")
            print("Call type: \(call.callType == .audio ? "Audio" : "Video")")
            
            // The UI Kit automatically shows the incoming call screen
            // Add custom logic here if needed
        }
        
        // Called when an outgoing call is accepted
        func onOutgoingCallAccepted(acceptedCall: CometChat.Call?, error: CometChat.CometChatException?) {
            guard let call = acceptedCall else { return }
            print("✅ Call accepted: \(call.sessionId ?? "")")
        }
        
        // Called when an outgoing call is rejected
        func onOutgoingCallRejected(rejectedCall: CometChat.Call?, error: CometChat.CometChatException?) {
            guard let call = rejectedCall else { return }
            print("❌ Call rejected: \(call.sessionId ?? "")")
        }
        
        // Called when an incoming call is cancelled
        func onIncomingCallCancelled(canceledCall: CometChat.Call?, error: CometChat.CometChatException?) {
            guard let call = canceledCall else { return }
            print("📵 Call cancelled: \(call.sessionId ?? "")")
        }
        
        // Called when a call ends
        func onCallEnded(endedCall: CometChat.Call?, error: CometChat.CometChatException?) {
            guard let call = endedCall else { return }
            print("📴 Call ended: \(call.sessionId ?? "")")
        }
    }

    // Register in AppDelegate or SceneDelegate
    // CallHandler.shared.registerForCalls()
    ```
  </Tab>
</Tabs>

***

## Calling Components Reference

### CometChatCallButtons

Renders voice and video call buttons.

```swift lines theme={null}
let callButtons = CometChatCallButtons()
callButtons.user = user  // or callButtons.group = group

// Callbacks
callButtons.set(onVoiceCallClick: { user, group in })
callButtons.set(onVideoCallClick: { user, group in })
callButtons.set(onError: { error in })
```

### CometChatIncomingCall

Displays incoming call screen with accept/reject options.

```swift lines theme={null}
let incomingCall = CometChatIncomingCall()
incomingCall.set(call: call)

incomingCall.set(onAcceptClick: { call in })
incomingCall.set(onDeclineClick: { call in })
```

### CometChatOutgoingCall

Displays outgoing call screen while waiting for answer.

```swift lines theme={null}
let outgoingCall = CometChatOutgoingCall()
outgoingCall.set(call: call)

outgoingCall.set(onCancelClick: { call in })
```

### CometChatCallLogs

Displays call history. See [Call Logs](/docs/ui-kit/ios/call-logs) for full documentation.

```swift lines theme={null}
let callLogs = CometChatCallLogs()
callLogs.set(onItemClick: { callLog in })
```

***

## Related

* [Call Logs](/docs/ui-kit/ios/call-logs) - Display call history
* [Call Buttons](/docs/ui-kit/ios/call-buttons) - Call button component
* [Incoming Call](/docs/ui-kit/ios/incoming-call) - Incoming call screen
* [Outgoing Call](/docs/ui-kit/ios/outgoing-call) - Outgoing call screen
* [Ongoing Call](/docs/ui-kit/ios/ongoing-call) - Active call screen


# Calling Integration
Source: https://www.cometchat.com/docs/ui-kit/ios/calling-integration

Add voice and video calling to CometChat iOS UI Kit with Calls SDK installation, CocoaPods or Swift Package Manager, and verification.

## Overview

This guide walks you through adding voice and video calling capabilities to your iOS application using the CometChat UI Kit.

<Info>
  Make sure you've completed the [Getting Started](/docs/ui-kit/ios/getting-started) guide before proceeding.
</Info>

## Add the Calls SDK

You can install the CometChat Calls SDK using either CocoaPods or Swift Package Manager.

<Note>
  * CometChatCallsSDK supports iOS 13 and above
  * CometChatCallsSDK supports Swift 5.0+
</Note>

### Option 1: CocoaPods

Open a terminal window, navigate to your project directory, and create a Podfile:

```ruby theme={null}
$ pod init
```

Add the following lines to the Podfile:

```ruby theme={null}
platform :ios, '13.0'
use_frameworks!

target 'YourApp' do
  pod 'CometChatUIKitSwift', '4.3.15'
  pod 'CometChatCallsSDK', '4.0.6'
end
```

Install the dependencies:

```ruby theme={null}
$ pod install
```

If you encounter issues, try:

```ruby theme={null}
$ pod install --repo-update
```

To update to the latest version:

```ruby theme={null}
$ pod update CometChatCallsSDK
```

<Tip>
  Always open the `.xcworkspace` file after adding the dependencies.
</Tip>

### Option 2: Swift Package Manager

1. Go to File → Add Packages in Xcode
2. Add the CometChat Calls SDK repository:

```
https://github.com/cometchat/calls-sdk-ios.git
```

3. Select Version Rules, enter the version (e.g., 4.0.5), and click Next

<Info>
  Make sure you have completed the Chat UI Kit integration before adding the Calls SDK.
</Info>

## Verify Integration

After adding the dependency, the iOS UI Kit will automatically detect it and activate calling features. You will see [CallButtons](/docs/ui-kit/ios/call-buttons) rendered in the [MessageHeader](/docs/ui-kit/ios/message-header) component.

<Frame>
  <img />
</Frame>


# Campaigns
Source: https://www.cometchat.com/docs/ui-kit/ios/campaigns

Deliver targeted, rich notifications to users via an in-app notification feed powered by the CometChat Cards renderer.

CometChat Campaigns enables you to send rich, interactive notifications to users through an in-app notification feed. Each notification is rendered as a native card using the CometChat Cards library — supporting images, text, buttons, layouts, and interactive actions.

<Note>
  Before proceeding, ensure you have completed the [UI Kit integration](/docs/ui-kit/ios/getting-started) and the [Dashboard Setup](/docs/campaigns#setup-flow) for Campaigns.
</Note>

***

## Overview

Campaigns delivers notifications as Card Schema JSON — a structured format that defines the visual layout of each notification card. The system consists of three layers:

* **CometChat Chat SDK** — Fetches feed items, manages read/delivered state, provides real-time listeners, handles push notification tracking
* **CometChat Cards Library** — Renders Card Schema JSON into native UIKit views
* **CometChat UI Kit** — Provides the ready-to-use `CometChatNotificationFeed` component that wires everything together

***

## Sending Campaigns

Before integrating the frontend, you need to set up channels, categories, templates, and campaigns in the CometChat Dashboard. Follow the [Dashboard Setup Guide](/docs/campaigns#setup-flow) for step-by-step instructions with screenshots.

***

## How Cards Work

Each `NotificationFeedItem` from the SDK contains a `content` field — a `[String: Any]` dictionary holding the Card Schema JSON. This JSON is passed directly to the CometChat Cards renderer which produces a native UIKit view.

The Cards library is a pure renderer:

* **Input:** Card Schema JSON string + theme mode + optional action callback
* **Output:** Native UIKit view hierarchy

It does not execute actions, manage message state, or call any SDK methods. When users tap interactive elements (buttons, links), the library emits the action to your callback. You decide what happens — open a URL, navigate to a chat, make an API call, etc.

***

## Card Schema JSON Example

```json theme={null}
{
  "version": "1.0",
  "body": [
    { "type": "image", "id": "img_1", "url": "https://cdn.example.com/sale.jpg", "height": 180, "fit": "cover", "borderRadius": 8 },
    { "type": "text", "id": "txt_1", "content": "🎉 Flash Sale — 40% Off!", "variant": "heading2" },
    { "type": "text", "id": "txt_2", "content": "Limited time offer on all premium plans.", "variant": "body" },
    { "type": "button", "id": "btn_1", "label": "Claim Offer", "action": { "type": "openUrl", "url": "https://example.com/offer" }, "fullWidth": true }
  ],
  "style": { "background": {"light": "#FFFFFF", "dark": "#1E1E1E"}, "borderRadius": 12, "padding": 16 },
  "fallbackText": "Flash Sale — 40% Off! Claim your offer: https://example.com/offer"
}
```

The schema supports 20 element types (text, image, icon, avatar, badge, divider, spacer, chip, progressBar, codeBlock, markdown, row, column, grid, accordion, tabs, button, iconButton, link, table) and 9 action types (openUrl, chatWithUser, chatWithGroup, sendMessage, copyToClipboard, downloadFile, initiateCall, apiCall, customCallback).

***

## Notification Feed Component

The `CometChatNotificationFeed` component renders campaign notifications as a full-screen scrollable feed. It handles fetching, card rendering, pagination, filtering, real-time updates, and engagement reporting automatically.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let notificationFeed = CometChatNotificationFeed()
    let navController = UINavigationController(rootViewController: notificationFeed)
    self.present(navController, animated: true)
    ```
  </Tab>
</Tabs>

See the full [CometChatNotificationFeed](/docs/ui-kit/ios/notification-feed) documentation for all configuration options, actions, filtering, and customization.

***

## Setting Up Notification Service Extension

To track push notification delivery for campaigns, you need a Notification Service Extension. This runs when a push arrives on the device (even if the app is in the background).

### Step 1: Create the Extension

1. In Xcode, go to **File → New → Target**.
2. Select **Notification Service Extension**.
3. Name it (e.g., `NotificationService`).
4. Click **Finish**.

### Step 2: Configure App Groups

Both your main app and the extension need to share data via an App Group:

1. Select your **main app target** → Signing & Capabilities → **+ Capability** → **App Groups**.
2. Add a group (e.g., `group.com.yourapp.cometchat`).
3. Select your **extension target** → repeat the same steps with the same group ID.

### Step 3: Add CometChatSDK to the Extension

Add `CometChatSDK` as a dependency to the extension target (via SPM or CocoaPods).

### Step 4: Implement the Extension

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    import UserNotifications
    import CometChatSDK

    class NotificationService: UNNotificationServiceExtension {
        override func didReceive(_ request: UNNotificationRequest,
                                 withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
            let bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)!

            // Share auth state via App Group
            CometChat.setExtensionGroupID(id: "group.com.yourapp.cometchat")

            let userInfo = bestAttemptContent.userInfo
            if let cometchat = userInfo["cometchat"] as? [String: Any],
               let type = cometchat["type"] as? String,
               type == "business_messaging" {
                let push = PushNotification.fromPayload(cometchat)
                CometChat.markPushNotificationDelivered(push, onSuccess: {}, onError: { _ in })
            }

            contentHandler(bestAttemptContent)
        }
    }
    ```
  </Tab>
</Tabs>

***

## Handling Push Notification Clicks

When the user taps a campaign push notification, report the click and navigate to the feed:

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    func userNotificationCenter(_ center: UNUserNotificationCenter,
                                didReceive response: UNNotificationResponse,
                                withCompletionHandler completionHandler: @escaping () -> Void) {
        let userInfo = response.notification.request.content.userInfo

        if let cometchat = userInfo["cometchat"] as? [String: Any],
           let type = cometchat["type"] as? String,
           type == "business_messaging" {
            let push = PushNotification.fromPayload(cometchat)
            CometChat.markPushNotificationClicked(push, onSuccess: {}, onError: { _ in })

            // Navigate to notification feed
            let notificationFeed = CometChatNotificationFeed()
            let navController = UINavigationController(rootViewController: notificationFeed)
            window?.rootViewController?.present(navController, animated: true)

            completionHandler()
            return
        }

        completionHandler()
    }
    ```
  </Tab>
</Tabs>

See the [SDK Campaigns documentation](/docs/sdk/ios/campaigns) for the complete push notification tracking API.

***

## Managing Campaigns

Campaigns are created and managed from the CometChat Dashboard or via the REST API. The SDK and UI Kit are consumer-side — they display and interact with campaigns, not create them.

* **Dashboard:** Navigate to Campaigns → follow the flow above (Channel → Category → Template → Bubble Builder → Send).
* **REST API:** Use the Campaigns API to programmatically create and schedule campaigns.


# Color Resources
Source: https://www.cometchat.com/docs/ui-kit/ios/color-resources

Customize CometChat iOS UI Kit color resources with brand colors, backgrounds, text, alerts, dark mode, and theme timing.

<Accordion title="AI Integration Quick Reference">
  | Field             | Value                                                              |
  | ----------------- | ------------------------------------------------------------------ |
  | Platform          | iOS UI Kit                                                         |
  | Theme Class       | `CometChatTheme`                                                   |
  | Primary Color     | `CometChatTheme.primaryColor` — Main brand color (#6852D6 default) |
  | Background Colors | `backgroundColor01`, `backgroundColor02`, `backgroundColor03`      |
  | Text Colors       | `textColorPrimary`, `textColorSecondary`, `textColorTertiary`      |
  | Alert Colors      | `successColor`, `errorColor`, `warningColor`, `infoColor`          |
  | Dark Mode         | Use `UIColor { traitCollection in }` for dynamic colors            |
  | Apply Timing      | Set theme before `CometChatUIKit.init()`                           |
</Accordion>

## Overview

CometChat UI Kit uses `CometChatTheme` to manage colors across all components. Colors automatically adapt to Light and Dark mode, ensuring a consistent experience.

<Tabs>
  <Tab title="Light Mode">
    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="Dark Mode">
    <Frame>
      <img />
    </Frame>
  </Tab>
</Tabs>

***

## Color Categories

| Category       | Purpose                          | Examples                                     |
| -------------- | -------------------------------- | -------------------------------------------- |
| **Primary**    | Main brand color, buttons, links | `primaryColor`                               |
| **Background** | Screen and component backgrounds | `backgroundColor01`, `backgroundColor02`     |
| **Text**       | Typography colors                | `textColorPrimary`, `textColorSecondary`     |
| **Border**     | Dividers and outlines            | `borderColorLight`, `borderColorDark`        |
| **Alert**      | Status indicators                | `successColor`, `errorColor`, `warningColor` |
| **Icon**       | Icon tints                       | `iconColorPrimary`, `iconColorSecondary`     |

***

## Quick Start

### Access Default Colors

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Primary brand color
    let primary = CometChatTheme.primaryColor  // #6852D6

    // Background colors
    let background = CometChatTheme.backgroundColor01  // White (light) / #141414 (dark)
    let secondaryBg = CometChatTheme.backgroundColor02

    // Text colors
    let primaryText = CometChatTheme.textColorPrimary
    let secondaryText = CometChatTheme.textColorSecondary

    // Alert colors
    let success = CometChatTheme.successColor  // Green
    let error = CometChatTheme.errorColor      // Red
    let warning = CometChatTheme.warningColor  // Orange

    // Icon colors
    let iconPrimary = CometChatTheme.iconColorPrimary
    let iconSecondary = CometChatTheme.iconColorSecondary
    ```
  </Tab>
</Tabs>

***

## Customize Theme Colors

### Change Primary Color (Brand Color)

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Set your brand color globally
    CometChatTheme.primaryColor = UIColor(hex: "#FF5722")  // Orange brand

    // All components will now use this color for:
    // - Buttons
    // - Links
    // - Selected states
    // - Accent elements
    ```
  </Tab>
</Tabs>

### Complete Theme Customization

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    class ThemeManager {
        
        static func applyCustomTheme() {
            // Brand colors
            CometChatTheme.primaryColor = UIColor(hex: "#6200EE")  // Purple
            
            // Background colors
            CometChatTheme.backgroundColor01 = UIColor(hex: "#FFFFFF")
            CometChatTheme.backgroundColor02 = UIColor(hex: "#F5F5F5")
            CometChatTheme.backgroundColor03 = UIColor(hex: "#EEEEEE")
            
            // Text colors
            CometChatTheme.textColorPrimary = UIColor(hex: "#212121")
            CometChatTheme.textColorSecondary = UIColor(hex: "#757575")
            CometChatTheme.textColorTertiary = UIColor(hex: "#9E9E9E")
            
            // Border colors
            CometChatTheme.borderColorLight = UIColor(hex: "#E0E0E0")
            CometChatTheme.borderColorDark = UIColor(hex: "#BDBDBD")
            
            // Alert colors
            CometChatTheme.successColor = UIColor(hex: "#4CAF50")
            CometChatTheme.errorColor = UIColor(hex: "#F44336")
            CometChatTheme.warningColor = UIColor(hex: "#FF9800")
            CometChatTheme.infoColor = UIColor(hex: "#2196F3")
            
            // Icon colors
            CometChatTheme.iconColorPrimary = UIColor(hex: "#212121")
            CometChatTheme.iconColorSecondary = UIColor(hex: "#757575")
        }
    }

    // Apply in AppDelegate or SceneDelegate
    ThemeManager.applyCustomTheme()
    ```
  </Tab>
</Tabs>

***

## Dark Mode Support

CometChat automatically adapts to system appearance. You can also customize dark mode colors:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift
    import UIKit

    class ThemeManager {
        
        static func applyTheme() {
            // Create dynamic colors that adapt to light/dark mode
            CometChatTheme.primaryColor = UIColor { traitCollection in
                return traitCollection.userInterfaceStyle == .dark
                    ? UIColor(hex: "#BB86FC")  // Light purple for dark mode
                    : UIColor(hex: "#6200EE")  // Purple for light mode
            }
            
            CometChatTheme.backgroundColor01 = UIColor { traitCollection in
                return traitCollection.userInterfaceStyle == .dark
                    ? UIColor(hex: "#121212")  // Dark background
                    : UIColor(hex: "#FFFFFF")  // White background
            }
            
            CometChatTheme.textColorPrimary = UIColor { traitCollection in
                return traitCollection.userInterfaceStyle == .dark
                    ? UIColor(hex: "#FFFFFF")  // White text
                    : UIColor(hex: "#212121")  // Dark text
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Color Reference

### Primary Colors

| Property       | Light Mode | Dark Mode | Usage                   |
| -------------- | ---------- | --------- | ----------------------- |
| `primaryColor` | `#6852D6`  | `#6852D6` | Buttons, links, accents |

### Background Colors

| Property            | Light Mode | Dark Mode | Usage                |
| ------------------- | ---------- | --------- | -------------------- |
| `backgroundColor01` | `#FFFFFF`  | `#141414` | Main background      |
| `backgroundColor02` | `#F5F5F5`  | `#1E1E1E` | Secondary background |
| `backgroundColor03` | `#EEEEEE`  | `#2C2C2C` | Tertiary background  |

### Text Colors

| Property             | Light Mode | Dark Mode | Usage               |
| -------------------- | ---------- | --------- | ------------------- |
| `textColorPrimary`   | `#141414`  | `#FFFFFF` | Main text           |
| `textColorSecondary` | `#727272`  | `#A0A0A0` | Secondary text      |
| `textColorTertiary`  | `#A0A0A0`  | `#727272` | Hints, placeholders |

### Alert Colors

| Property       | Color     | Usage                |
| -------------- | --------- | -------------------- |
| `successColor` | `#09C26F` | Success states       |
| `errorColor`   | `#F44649` | Errors, missed calls |
| `warningColor` | `#FFAB00` | Warnings             |
| `infoColor`    | `#2196F3` | Information          |

### Border Colors

| Property           | Light Mode | Dark Mode | Usage             |
| ------------------ | ---------- | --------- | ----------------- |
| `borderColorLight` | `#E8E8E8`  | `#2C2C2C` | Subtle borders    |
| `borderColorDark`  | `#CCCCCC`  | `#404040` | Prominent borders |

***

## Production Example

Complete app with custom branding:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift

    @main
    class AppDelegate: UIResponder, UIApplicationDelegate {
        
        func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
            
            // Apply custom theme before initializing CometChat
            applyBrandTheme()
            
            return true
        }
        
        private func applyBrandTheme() {
            // Your brand colors
            let brandPrimary = UIColor(hex: "#1E88E5")      // Blue
            let brandSecondary = UIColor(hex: "#FFC107")   // Amber
            
            // Apply to CometChat theme
            CometChatTheme.primaryColor = brandPrimary
            
            // Customize backgrounds
            CometChatTheme.backgroundColor01 = UIColor { trait in
                trait.userInterfaceStyle == .dark
                    ? UIColor(hex: "#0D1117")
                    : UIColor(hex: "#FFFFFF")
            }
            
            CometChatTheme.backgroundColor02 = UIColor { trait in
                trait.userInterfaceStyle == .dark
                    ? UIColor(hex: "#161B22")
                    : UIColor(hex: "#F6F8FA")
            }
            
            // Customize text
            CometChatTheme.textColorPrimary = UIColor { trait in
                trait.userInterfaceStyle == .dark
                    ? UIColor(hex: "#C9D1D9")
                    : UIColor(hex: "#24292F")
            }
            
            CometChatTheme.textColorSecondary = UIColor { trait in
                trait.userInterfaceStyle == .dark
                    ? UIColor(hex: "#8B949E")
                    : UIColor(hex: "#57606A")
            }
            
            // Alert colors
            CometChatTheme.successColor = UIColor(hex: "#238636")
            CometChatTheme.errorColor = UIColor(hex: "#DA3633")
            CometChatTheme.warningColor = brandSecondary
        }
    }

    // UIColor extension for hex support
    extension UIColor {
        convenience init(hex: String) {
            var hexSanitized = hex.trimmingCharacters(in: .whitespacesAndNewlines)
            hexSanitized = hexSanitized.replacingOccurrences(of: "#", with: "")
            
            var rgb: UInt64 = 0
            Scanner(string: hexSanitized).scanHexInt64(&rgb)
            
            let r = CGFloat((rgb & 0xFF0000) >> 16) / 255.0
            let g = CGFloat((rgb & 0x00FF00) >> 8) / 255.0
            let b = CGFloat(rgb & 0x0000FF) / 255.0
            
            self.init(red: r, green: g, blue: b, alpha: 1.0)
        }
    }
    ```
  </Tab>
</Tabs>

***

## Related

<CardGroup>
  <Card title="Component Styling" href="/ui-kit/ios/component-styling">
    Style individual components
  </Card>

  <Card title="Theme Introduction" href="/ui-kit/ios/theme-introduction">
    Complete theming guide
  </Card>

  <Card title="Getting Started" href="/ui-kit/ios/getting-started">
    Initial setup
  </Card>
</CardGroup>


# Component Styling
Source: https://www.cometchat.com/docs/ui-kit/ios/component-styling

Style CometChat iOS UI Kit components globally or per instance with style classes, base styles, colors, fonts, and custom appearances.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                       |
  | ---------------- | --------------------------------------------------------------------------- |
  | Platform         | iOS UI Kit                                                                  |
  | Global Styling   | `CometChatConversations.style.titleColor = UIColor`                         |
  | Instance Styling | `let style = ConversationsStyle(); conversations.style = style`             |
  | Style Classes    | `ConversationsStyle`, `UsersStyle`, `GroupsStyle`, `MessageListStyle`, etc. |
  | Base Styles      | `AvatarStyle`, `BadgeStyle`, `StatusIndicatorStyle`, `ReceiptStyle`         |
  | Apply Timing     | Global styles before `CometChatUIKit.init()`                                |
  | Precedence       | Instance styles override global styles                                      |
</Accordion>

## Overview

Every CometChat component can be styled to match your app's design. You can apply styles globally (affects all instances) or per-instance (affects one component).

***

## Styling Methods

### Global Styling

Apply once, affects all instances of a component:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Set before using any components (e.g., in AppDelegate)
    CometChatConversations.style.titleColor = UIColor(hex: "#6200EE")
    CometChatConversations.style.titleFont = UIFont.systemFont(ofSize: 28, weight: .bold)
    CometChatConversations.style.backgroundColor = .systemBackground
    ```
  </Tab>
</Tabs>

### Instance Styling

Apply to a specific component instance:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let style = ConversationsStyle()
    style.titleColor = UIColor(hex: "#6200EE")
    style.titleFont = UIFont.systemFont(ofSize: 28, weight: .bold)
    style.backgroundColor = .systemBackground

    let conversations = CometChatConversations()
    conversations.style = style
    ```
  </Tab>
</Tabs>

***

## Component Styles

### Conversations

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Create custom styles
    let avatarStyle = AvatarStyle()
    avatarStyle.backgroundColor = UIColor(hex: "#FBAA75")
    avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)

    let badgeStyle = BadgeStyle()
    badgeStyle.backgroundColor = UIColor(hex: "#F76808")
    badgeStyle.textColor = .white
    badgeStyle.textFont = UIFont.systemFont(ofSize: 12, weight: .bold)

    let receiptStyle = ReceiptStyle()
    receiptStyle.readIconTint = UIColor(hex: "#6200EE")
    receiptStyle.deliveredIconTint = UIColor(hex: "#9E9E9E")

    // Apply to conversations
    let conversations = CometChatConversations()
    conversations.avatarStyle = avatarStyle
    conversations.badgeStyle = badgeStyle
    conversations.receiptStyle = receiptStyle

    // Style the list
    conversations.style.titleColor = UIColor(hex: "#212121")
    conversations.style.titleFont = UIFont.systemFont(ofSize: 17, weight: .semibold)
    conversations.style.subtitleColor = UIColor(hex: "#757575")
    conversations.style.subtitleFont = UIFont.systemFont(ofSize: 14)
    conversations.style.backgroundColor = .systemBackground
    conversations.style.listItemBackground = .systemBackground
    ```
  </Tab>
</Tabs>

[View all ConversationsStyle properties →](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Conversations/ConversationsStyle.swift)

***

### Users

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Avatar style
    let avatarStyle = AvatarStyle()
    avatarStyle.backgroundColor = UIColor(hex: "#FBAA75")
    avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)

    // Status indicator style
    let statusStyle = StatusIndicatorStyle()
    statusStyle.backgroundColor = .systemGreen
    statusStyle.borderColor = .white
    statusStyle.borderWidth = 2

    // Apply styles
    let users = CometChatUsers()
    users.avatarStyle = avatarStyle
    users.statusIndicatorStyle = statusStyle

    // List styling
    users.style.titleColor = UIColor(hex: "#F76808")
    users.style.titleFont = UIFont(name: "Helvetica-Bold", size: 28)
    users.style.listItemTitleColor = UIColor(hex: "#212121")
    users.style.listItemTitleFont = UIFont.systemFont(ofSize: 16, weight: .medium)
    users.style.backgroundColor = .systemBackground
    ```
  </Tab>
</Tabs>

[View all UsersStyle properties →](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Users/UsersStyle.swift)

***

### Groups

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Avatar style for group icons
    let avatarStyle = AvatarStyle()
    avatarStyle.backgroundColor = UIColor(hex: "#FBAA75")
    avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)

    // Apply styles
    let groups = CometChatGroups()
    groups.avatarStyle = avatarStyle

    // List styling
    groups.style.titleColor = UIColor(hex: "#F76808")
    groups.style.titleFont = UIFont(name: "Helvetica-Bold", size: 28)
    groups.style.listItemTitleColor = UIColor(hex: "#212121")
    groups.style.listItemSubtitleColor = UIColor(hex: "#757575")
    groups.style.backgroundColor = .systemBackground
    ```
  </Tab>
</Tabs>

[View all GroupsStyle properties →](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Groups/GroupsStyle.swift)

***

### Message Header

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Avatar style
    let avatarStyle = AvatarStyle()
    avatarStyle.backgroundColor = UIColor(hex: "#FBAA75")
    avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 20)

    // Apply to message header
    CometChatMessageHeader.style.titleTextColor = UIColor(hex: "#F76808")
    CometChatMessageHeader.style.titleTextFont = UIFont(name: "Helvetica-Bold", size: 18)
    CometChatMessageHeader.style.subtitleTextColor = UIColor(hex: "#757575")
    CometChatMessageHeader.style.backgroundColor = .systemBackground
    CometChatMessageHeader.avatarStyle = avatarStyle
    ```
  </Tab>
</Tabs>

[View all MessageHeaderStyle properties →](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Message%20Header/MessageHeaderStyle.swift)

***

### Message List

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Background color
    CometChatMessageList.style.backgroundColor = UIColor(hex: "#FBAA75")

    // Outgoing message bubbles (your messages)
    CometChatMessageBubble.style.outgoing.backgroundColor = UIColor(hex: "#F76808")
    CometChatMessageBubble.style.outgoing.textBubbleStyle.textColor = .white
    CometChatMessageBubble.style.outgoing.textBubbleStyle.textFont = UIFont.systemFont(ofSize: 15)

    // Incoming message bubbles (other's messages)
    CometChatMessageBubble.style.incoming.backgroundColor = UIColor(hex: "#E8E8E8")
    CometChatMessageBubble.style.incoming.textBubbleStyle.textColor = UIColor(hex: "#212121")
    CometChatMessageBubble.style.incoming.textBubbleStyle.textFont = UIFont.systemFont(ofSize: 15)

    // Timestamp style
    CometChatMessageList.style.timestampTextColor = UIColor(hex: "#9E9E9E")
    CometChatMessageList.style.timestampTextFont = UIFont.systemFont(ofSize: 11)
    ```
  </Tab>
</Tabs>

[View all MessageListStyle properties →](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Message%20List/MessageListStyle.swift)

***

### Message Composer

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Send button
    CometChatMessageComposer.style.activeSendButtonImageBackgroundColor = UIColor(hex: "#F76808")
    CometChatMessageComposer.style.sendButtonImageTint = .white

    // Action icons
    CometChatMessageComposer.style.attachmentImageTint = UIColor(hex: "#F76808")
    CometChatMessageComposer.style.voiceRecordingImageTint = UIColor(hex: "#F76808")
    CometChatMessageComposer.style.stickerTint = UIColor(hex: "#F76808")
    CometChatMessageComposer.style.aiImageTint = UIColor(hex: "#F76808")

    // Input field
    CometChatMessageComposer.style.inputBackgroundColor = UIColor(hex: "#F5F5F5")
    CometChatMessageComposer.style.inputTextColor = UIColor(hex: "#212121")
    CometChatMessageComposer.style.inputTextFont = UIFont.systemFont(ofSize: 16)
    CometChatMessageComposer.style.placeholderTextColor = UIColor(hex: "#9E9E9E")

    // Background
    CometChatMessageComposer.style.backgroundColor = .systemBackground
    CometChatMessageComposer.style.borderColor = UIColor(hex: "#E8E8E8")
    ```
  </Tab>
</Tabs>

[View all MessageComposerStyle properties →](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Message%20Composer/MessageComposerStyle.swift)

***

### Call Logs

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Avatar style
    let avatarStyle = AvatarStyle()
    avatarStyle.backgroundColor = UIColor(hex: "#FBAA75")
    avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)

    // Apply styles
    CometChatCallLogs.style.titleColor = UIColor(hex: "#F76808")
    CometChatCallLogs.style.titleFont = UIFont(name: "Helvetica-Bold", size: 24)
    CometChatCallLogs.style.listItemTitleTextColor = UIColor(hex: "#212121")
    CometChatCallLogs.style.listItemSubTitleTextColor = UIColor(hex: "#757575")
    CometChatCallLogs.style.backgroundColor = .systemBackground

    // Call type icons
    CometChatCallLogs.style.incomingCallIconTint = .systemRed
    CometChatCallLogs.style.outgoingCallIconTint = .systemGreen
    CometChatCallLogs.style.missedCallTitleColor = .systemRed

    CometChatCallLogs.avatarStyle = avatarStyle
    ```
  </Tab>
</Tabs>

[View all CallLogStyle properties →](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Calls/Call%20Log/Call%20Logs/CallLogStyle.swift)

***

### Search

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Instance styling
    let style = SearchStyle()
    style.backgroundColor = UIColor(hex: "#EDEAFA")
    style.listItemBackground = UIColor(hex: "#EDEAFA")
    style.listItemTitleFont = UIFont(name: "Helvetica", size: 16)
    style.titleFont = UIFont(name: "Helvetica-Bold", size: 12)
    style.searchBarPlaceholderTextFont = UIFont(name: "Helvetica", size: 12)
    style.searchBarBackgroundColor = .white
    style.searchBarTextColor = UIColor(hex: "#212121")

    let searchVC = CometChatSearch()
    searchVC.style = style

    // Or global styling
    CometChatSearch.style.backgroundColor = UIColor(hex: "#EDEAFA")
    CometChatSearch.style.listItemBackground = UIColor(hex: "#EDEAFA")
    ```
  </Tab>
</Tabs>

***

### AI Assistant Chat History

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Date separator style
    let dateStyle = CometChatDateStyle()
    dateStyle.textColor = UIColor(hex: "#8E8E93")
    dateStyle.textFont = UIFont.systemFont(ofSize: 12)

    // Apply styles
    CometChatAIAssistantChatHistory.style.backgroundColor = UIColor(hex: "#FFF9F2")
    CometChatAIAssistantChatHistory.style.headerBackgroundColor = UIColor(hex: "#FFF9F2")
    CometChatAIAssistantChatHistory.style.headerTitleTextColor = UIColor(hex: "#141414")
    CometChatAIAssistantChatHistory.style.headerTitleTextFont = UIFont.boldSystemFont(ofSize: 18)
    CometChatAIAssistantChatHistory.style.newChatIconColor = UIColor(hex: "#F76808")
    CometChatAIAssistantChatHistory.style.itemTextColor = UIColor(hex: "#141414")
    CometChatAIAssistantChatHistory.style.itemTextFont = UIFont.systemFont(ofSize: 14)
    CometChatAIAssistantChatHistory.style.dateSeparatorStyle = dateStyle
    ```
  </Tab>
</Tabs>

***

## Base Component Styles

### Avatar

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let avatarStyle = AvatarStyle()
    avatarStyle.backgroundColor = UIColor(hex: "#6200EE")
    avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 24)  // Circle
    avatarStyle.borderWidth = 2
    avatarStyle.borderColor = .white
    avatarStyle.textFont = UIFont.systemFont(ofSize: 16, weight: .bold)
    avatarStyle.textColor = .white
    ```
  </Tab>
</Tabs>

[View AvatarStyle →](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Shared/Views/Avatar/AvatarStyle.swift)

### Badge

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let badgeStyle = BadgeStyle()
    badgeStyle.backgroundColor = UIColor(hex: "#F44336")
    badgeStyle.textColor = .white
    badgeStyle.textFont = UIFont.systemFont(ofSize: 12, weight: .bold)
    badgeStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 10)
    badgeStyle.borderWidth = 0
    ```
  </Tab>
</Tabs>

[View BadgeStyle →](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Shared/Views/Badge/BadgeCountStyle.swift)

### Status Indicator

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let statusStyle = StatusIndicatorStyle()
    statusStyle.backgroundColor = .systemGreen  // Online color
    statusStyle.borderColor = .white
    statusStyle.borderWidth = 2
    statusStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 6)  // Circle
    ```
  </Tab>
</Tabs>

[View StatusIndicatorStyle →](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Shared/Views/Status%20Indicator/StatusIndicatorStyle.swift)

### Receipt

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let receiptStyle = ReceiptStyle()
    receiptStyle.sentIconTint = UIColor(hex: "#9E9E9E")
    receiptStyle.deliveredIconTint = UIColor(hex: "#9E9E9E")
    receiptStyle.readIconTint = UIColor(hex: "#6200EE")
    receiptStyle.errorIconTint = UIColor(hex: "#F44336")
    ```
  </Tab>
</Tabs>

[View ReceiptStyle →](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Shared/Views/Receipt/ReceiptStyle.swift)

***

## Complete Styling Example

Apply consistent branding across all components:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift
    import UIKit

    class StyleManager {
        
        // Brand colors
        static let primaryColor = UIColor(hex: "#6200EE")
        static let secondaryColor = UIColor(hex: "#03DAC6")
        static let backgroundColor = UIColor.systemBackground
        static let surfaceColor = UIColor(hex: "#F5F5F5")
        static let textPrimary = UIColor(hex: "#212121")
        static let textSecondary = UIColor(hex: "#757575")
        
        static func applyGlobalStyles() {
            // Theme colors
            CometChatTheme.primaryColor = primaryColor
            
            // Avatar style (used everywhere)
            let avatarStyle = AvatarStyle()
            avatarStyle.backgroundColor = secondaryColor
            avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 20)
            
            // Badge style
            let badgeStyle = BadgeStyle()
            badgeStyle.backgroundColor = primaryColor
            badgeStyle.textColor = .white
            
            // Apply to Conversations
            CometChatConversations.avatarStyle = avatarStyle
            CometChatConversations.badgeStyle = badgeStyle
            CometChatConversations.style.titleColor = textPrimary
            CometChatConversations.style.titleFont = UIFont.systemFont(ofSize: 28, weight: .bold)
            CometChatConversations.style.backgroundColor = backgroundColor
            
            // Apply to Users
            CometChatUsers.avatarStyle = avatarStyle
            CometChatUsers.style.titleColor = textPrimary
            CometChatUsers.style.backgroundColor = backgroundColor
            
            // Apply to Groups
            CometChatGroups.avatarStyle = avatarStyle
            CometChatGroups.style.titleColor = textPrimary
            CometChatGroups.style.backgroundColor = backgroundColor
            
            // Apply to Message Header
            CometChatMessageHeader.avatarStyle = avatarStyle
            CometChatMessageHeader.style.titleTextColor = textPrimary
            CometChatMessageHeader.style.backgroundColor = backgroundColor
            
            // Apply to Message List
            CometChatMessageList.style.backgroundColor = surfaceColor
            CometChatMessageBubble.style.outgoing.backgroundColor = primaryColor
            CometChatMessageBubble.style.outgoing.textBubbleStyle.textColor = .white
            CometChatMessageBubble.style.incoming.backgroundColor = .white
            CometChatMessageBubble.style.incoming.textBubbleStyle.textColor = textPrimary
            
            // Apply to Message Composer
            CometChatMessageComposer.style.activeSendButtonImageBackgroundColor = primaryColor
            CometChatMessageComposer.style.attachmentImageTint = primaryColor
            CometChatMessageComposer.style.backgroundColor = backgroundColor
            
            // Apply to Call Logs
            CometChatCallLogs.avatarStyle = avatarStyle
            CometChatCallLogs.style.titleColor = textPrimary
            CometChatCallLogs.style.backgroundColor = backgroundColor
        }
    }

    // Apply in AppDelegate
    @main
    class AppDelegate: UIResponder, UIApplicationDelegate {
        func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
            StyleManager.applyGlobalStyles()
            return true
        }
    }
    ```
  </Tab>
</Tabs>

***

## Related

<CardGroup>
  <Card title="Color Resources" href="/ui-kit/ios/color-resources">
    Theme colors
  </Card>

  <Card title="Theme Introduction" href="/ui-kit/ios/theme-introduction">
    Complete theming
  </Card>

  <Card title="Components Overview" href="/ui-kit/ios/components-overview">
    All components
  </Card>
</CardGroup>


# Core Features
Source: https://www.cometchat.com/docs/ui-kit/ios/core-features

Review CometChat iOS UI Kit core features for messaging, media sharing, receipts, typing indicators, presence, reactions, threads, and search.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "category": "messaging",
    "features": [
      {"name": "instantMessaging", "description": "Send and receive text messages in real-time", "component": "CometChatMessages", "enabledByDefault": true},
      {"name": "mediaSharing", "description": "Share images, videos, audio files, and documents", "component": "CometChatMessageComposer", "enabledByDefault": true},
      {"name": "readReceipts", "description": "Show when messages are delivered and read", "component": "CometChatMessageList", "enabledByDefault": true},
      {"name": "typingIndicators", "description": "Show when users are typing in real-time", "component": "CometChatMessageHeader", "enabledByDefault": true},
      {"name": "userPresence", "description": "Display online/offline status for users", "component": "CometChatConversations", "enabledByDefault": true},
      {"name": "reactions", "description": "Let users react to messages with emojis", "component": "CometChatMessageList", "enabledByDefault": true},
      {"name": "mentions", "description": "Tag users in messages with @mentions", "component": "CometChatMessageComposer", "enabledByDefault": true},
      {"name": "threadedConversations", "description": "Reply to specific messages in threads", "component": "CometChatThreadedMessageHeader", "enabledByDefault": true},
      {"name": "groupChat", "description": "Create and manage group conversations", "component": "CometChatGroups", "enabledByDefault": true},
      {"name": "search", "description": "Search across conversations and messages", "component": "CometChatSearch", "enabledByDefault": true}
    ],
    "relatedComponents": ["CometChatMessages", "CometChatConversations", "CometChatMessageList", "CometChatMessageComposer"]
  }
  ```
</Accordion>

CometChat UI Kit provides production-ready components that work together to deliver a complete chat experience. This guide shows how to implement each core feature with copy-paste code examples.

## Instant Messaging

Send and receive text messages in real-time.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ChatViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // For one-on-one chat
        let messagesVC = CometChatMessages()
        
        // Set the user to chat with
        CometChat.getUser(UID: "cometchat-uid-1") { user in
            DispatchQueue.main.async {
                messagesVC.set(user: user)
                self.navigationController?.pushViewController(messagesVC, animated: true)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}
```

**Components Used:**

* [MessageComposer](/docs/ui-kit/ios/message-composer) - Text input and send button
* [MessageList](/docs/ui-kit/ios/message-list) - Displays sent and received messages
* [Messages](/docs/ui-kit/ios/message-header) - Complete messaging screen (includes both)

## Media Sharing

Share multiple images, videos, audio files, and documents in a single send. Tapping the attachment button opens a multi-select picker; the picks stage in a preview tray above the input box with per-file upload progress, and send together with an optional caption. Everything works out of the box:

<Frame>
  <img alt="Multi-attachment message list showing an image grid, a file card, and an audio bubble with caption, plus the composer staging tray with mixed image, video, and file tiles" />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class MediaChatViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let messagesVC = CometChatMessages()
        
        // The message composer includes multi-attachment media sharing:
        // - Multi-select photos and videos from the library
        // - Camera capture
        // - Multiple documents and audio files
        // - Clipboard paste (images, videos, documents, audio)
        // Picks stage in a preview tray, upload with progress, and send
        // as one batch with the composer text as the caption.
        
        CometChat.getUser(UID: "cometchat-uid-1") { user in
            DispatchQueue.main.async {
                messagesVC.set(user: user)
                self.navigationController?.pushViewController(messagesVC, animated: true)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}
```

Received messages render with per-type bubbles: a **media grid** for images and videos (with a fullscreen viewer — swipe, zoom, per-photo download, share), **playback rows** for audio files, and a **connected card stack** for documents. Messages from one send are grouped visually in the list. Per-message file count and per-file size limits come from your app's dashboard settings; violations surface directly in the tray.

See [Message Composer — Multiple Attachments](/docs/ui-kit/ios/message-composer#multiple-attachments) for configuration and [Message Bubble Styling](/docs/ui-kit/ios/message-bubble-styling) for the bubbles.

**Supported Media Types:**

| Type   | Bubble Component                                                                                                                                            |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Images | [Image Bubble](/docs/ui-kit/ios/message-bubble-styling#image-bubble) · multiple: [Media Grid Bubble](/docs/ui-kit/ios/message-bubble-styling#media-grid-bubble)       |
| Videos | [Video Bubble](/docs/ui-kit/ios/message-bubble-styling#video-bubble) · multiple: [Media Grid Bubble](/docs/ui-kit/ios/message-bubble-styling#media-grid-bubble)       |
| Audio  | [Audio Bubble](/docs/ui-kit/ios/message-bubble-styling#audio-bubble) (voice notes) · [Audio Files Bubble](/docs/ui-kit/ios/message-bubble-styling#audio-files-bubble) |
| Files  | [File Bubble](/docs/ui-kit/ios/message-bubble-styling#file-bubble) · multiple: [Files Bubble](/docs/ui-kit/ios/message-bubble-styling#files-bubble)                   |

## Read Receipts

Show when messages are delivered and read.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ReceiptsViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Read receipts are enabled by default
        let messagesVC = CometChatMessages()
        
        // To hide receipts:
        // messagesVC.hideReceipts = true
        
        CometChat.getUser(UID: "cometchat-uid-1") { user in
            DispatchQueue.main.async {
                messagesVC.set(user: user)
                self.navigationController?.pushViewController(messagesVC, animated: true)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
    
    // View detailed message information
    func showMessageInfo(for message: BaseMessage) {
        let messageInfo = CometChatMessageInformation()
        messageInfo.set(message: message)
        navigationController?.pushViewController(messageInfo, animated: true)
    }
}
```

**Receipt States:**

* ✓ Sent - Message sent to server
* ✓✓ Delivered - Message delivered to recipient's device
* ✓✓ (blue) Read - Recipient has seen the message

**Components Used:**

* [Conversations](/docs/ui-kit/ios/conversations) - Shows receipt status on last message
* [MessageList](/docs/ui-kit/ios/message-list) - Shows receipts on each message
* [MessageInformation](/docs/ui-kit/ios/core-features) - Detailed delivery/read info

## Mark As Unread

Let users mark messages as unread to revisit later.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class UnreadMessagesViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let messagesVC = CometChatMessages()
        
        // Enable starting from first unread message
        messagesVC.scrollToUnreadMessages = true
        
        CometChat.getUser(UID: "cometchat-uid-1") { user in
            DispatchQueue.main.async {
                messagesVC.set(user: user)
                self.navigationController?.pushViewController(messagesVC, animated: true)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
    
    // Mark a message as unread programmatically
    func markAsUnread(message: BaseMessage) {
        CometChat.markAsUnread(
            baseMessage: message
        ) { _ in
            print("Marked as unread")
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}
```

## Typing Indicators

Show when users are typing in real-time.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class TypingIndicatorViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Typing indicators are enabled by default in:
        // - CometChatConversations (shows "typing..." in conversation list)
        // - CometChatMessageHeader (shows "typing..." below user name)
        
        let messagesVC = CometChatMessages()
        
        CometChat.getUser(UID: "cometchat-uid-1") { user in
            DispatchQueue.main.async {
                messagesVC.set(user: user)
                self.navigationController?.pushViewController(messagesVC, animated: true)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
    
    // Send typing indicator manually
    func startTyping(to receiverUID: String) {
        let typingIndicator = TypingIndicator(
            receiverID: receiverUID,
            receiverType: .user
        )
        CometChat.startTyping(indicator: typingIndicator)
    }
    
    func stopTyping(to receiverUID: String) {
        let typingIndicator = TypingIndicator(
            receiverID: receiverUID,
            receiverType: .user
        )
        CometChat.endTyping(indicator: typingIndicator)
    }
}
```

**Components Used:**

* [Conversations](/docs/ui-kit/ios/conversations) - Shows typing in conversation list
* [MessageHeader](/docs/ui-kit/ios/message-header) - Shows typing below user/group name

## User Presence

Display online/offline status for users.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class PresenceViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // User presence is shown automatically in:
        // - CometChatConversations (green dot for online users)
        // - CometChatMessageHeader (shows "Online" or "Last seen")
        // - CometChatUsers (green dot for online users)
        // - CometChatGroupMembers (green dot for online members)
        
        let conversations = CometChatConversations()
        
        // To hide user status:
        // conversations.hideUserStatus = true
        
        navigationController?.pushViewController(conversations, animated: true)
    }
    
    // Listen for presence changes
    func listenForPresenceChanges() {
        CometChat.addUserListener("presence-listener", self)
    }
}

extension PresenceViewController: CometChatUserDelegate {
    func onUserOnline(user: User) {
        print("\(user.name ?? "") is now online")
    }
    
    func onUserOffline(user: User) {
        print("\(user.name ?? "") went offline")
    }
}
```

## Reactions

Let users react to messages with emojis.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ReactionsViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Reactions are enabled by default
        // Users can long-press a message to add reactions
        
        let messagesVC = CometChatMessages()
        
        CometChat.getUser(UID: "cometchat-uid-1") { user in
            DispatchQueue.main.async {
                messagesVC.set(user: user)
                self.navigationController?.pushViewController(messagesVC, animated: true)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
    
    // Add reaction programmatically
    func addReaction(to message: BaseMessage, emoji: String) {
        CometChat.addReaction(
            messageId: message.id,
            reaction: emoji
        ) { message in
            print("Reaction added")
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
    
    // Remove reaction
    func removeReaction(from message: BaseMessage, emoji: String) {
        CometChat.removeReaction(
            messageId: message.id,
            reaction: emoji
        ) { message in
            print("Reaction removed")
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}
```

## Mentions

Tag users in messages with @mentions.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class MentionsViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Mentions are enabled by default
        // Type @ in the composer to see mention suggestions
        
        let messagesVC = CometChatMessages()
        
        CometChat.getGroup(GUID: "group-123") { group in
            DispatchQueue.main.async {
                messagesVC.set(group: group)
                self.navigationController?.pushViewController(messagesVC, animated: true)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
    
    // Send message with mention programmatically
    func sendMessageWithMention(to groupID: String, mentionedUser: User) {
        let textMessage = TextMessage(
            receiverUid: groupID,
            text: "Hey @\(mentionedUser.name ?? ""), check this out!",
            receiverType: .group
        )
        
        // Add mentioned users
        textMessage.mentionedUsers = [mentionedUser]
        
        CometChat.sendTextMessage(message: textMessage) { message in
            print("Message with mention sent")
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}
```

## Rich Text Formatting

Rich Text Formatting allows users to style their messages with bold, italic, strikethrough, code, code blocks, blockquotes, ordered/unordered lists, and links. This brings richer expression to conversations and helps users emphasize key points.

<Frame>
  <img />
</Frame>

`enableRichTextFormatting` and `showRichTextFormattingOptions` are `true` by default. See the [CompactMessageComposer Rich Text Formatting](/docs/ui-kit/ios/compact-message-composer#rich-text-formatting) section for full configuration details.

<Note>
  Rich text formatting in message bubbles (rendering formatted text in the MessageList) is supported from UI Kit version 5.2.11 onwards. Earlier versions will display the raw markdown syntax instead of formatted text.
</Note>

| Component                                                      | Functionality                                                                                                                                                                 |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [CompactMessageComposer](/docs/ui-kit/ios/compact-message-composer) | Provides a built-in rich text editor with formatting toolbar and text selection menu items for bold, italic, strikethrough, code, links, lists, blockquotes, and code blocks. |
| [MessageList](/docs/ui-kit/ios/message-list)                        | Renders formatted messages with the appropriate styling applied, displaying rich text formatting as intended by the sender.                                                   |

## Threaded Conversations

Reply to specific messages in threads.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ThreadedMessagesViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Threaded messages are enabled by default
        // Users can tap "Reply in thread" on any message
        
        let messagesVC = CometChatMessages()
        
        CometChat.getUser(UID: "cometchat-uid-1") { user in
            DispatchQueue.main.async {
                messagesVC.set(user: user)
                self.navigationController?.pushViewController(messagesVC, animated: true)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
    
    // Open thread view for a message
    // Note: Thread replies are handled automatically by CometChatMessageList
    // when user taps "Reply in thread". The thread view uses CometChatThreadedMessageHeader
    // combined with CometChatMessageList and CometChatMessageComposer.
    func openThread(for parentMessage: BaseMessage, user: User) {
        // Create a view controller to host the threaded messages
        let threadVC = UIViewController()
        threadVC.view.backgroundColor = .systemBackground
        
        // Create threaded message header
        let threadedHeader = CometChatThreadedMessageHeader()
        threadedHeader.set(parentMessage: parentMessage)
        threadedHeader.set(controller: threadVC)
        threadedHeader.translatesAutoresizingMaskIntoConstraints = false
        
        // Create message list for thread replies
        let messageList = CometChatMessageList()
        messageList.set(user: user)
        messageList.set(parentMessage: parentMessage)
        messageList.set(controller: threadVC)
        messageList.translatesAutoresizingMaskIntoConstraints = false
        
        // Create composer for thread replies
        let composer = CometChatMessageComposer()
        composer.set(user: user)
        composer.set(parentMessage: parentMessage)
        composer.set(controller: threadVC)
        composer.translatesAutoresizingMaskIntoConstraints = false
        
        // Add to view
        threadVC.view.addSubview(threadedHeader)
        threadVC.view.addSubview(messageList)
        threadVC.view.addSubview(composer)
        
        // Layout constraints
        NSLayoutConstraint.activate([
            threadedHeader.topAnchor.constraint(equalTo: threadVC.view.safeAreaLayoutGuide.topAnchor),
            threadedHeader.leadingAnchor.constraint(equalTo: threadVC.view.leadingAnchor),
            threadedHeader.trailingAnchor.constraint(equalTo: threadVC.view.trailingAnchor),
            
            messageList.topAnchor.constraint(equalTo: threadedHeader.bottomAnchor),
            messageList.leadingAnchor.constraint(equalTo: threadVC.view.leadingAnchor),
            messageList.trailingAnchor.constraint(equalTo: threadVC.view.trailingAnchor),
            messageList.bottomAnchor.constraint(equalTo: composer.topAnchor),
            
            composer.leadingAnchor.constraint(equalTo: threadVC.view.leadingAnchor),
            composer.trailingAnchor.constraint(equalTo: threadVC.view.trailingAnchor),
            composer.bottomAnchor.constraint(equalTo: threadVC.view.safeAreaLayoutGuide.bottomAnchor)
        ])
        
        navigationController?.pushViewController(threadVC, animated: true)
    }
    
    // Send reply in thread programmatically
    func sendThreadReply(parentMessage: BaseMessage, text: String) {
        let reply = TextMessage(
            receiverUid: parentMessage.receiverUid,
            text: text,
            receiverType: parentMessage.receiverType
        )
        reply.parentMessageId = parentMessage.id
        
        CometChat.sendTextMessage(message: reply) { message in
            print("Thread reply sent")
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}
```

**Component Used:**

* [ThreadedMessages](/docs/ui-kit/ios/threaded-messages-header) - Displays thread replies

## Group Chat

Create and manage group conversations.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class GroupChatViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        showGroupsList()
    }
    
    // Show all groups
    func showGroupsList() {
        let groups = CometChatGroups()
        
        groups.set(onItemClick: { [weak self] group, _ in
            self?.openGroupChat(group: group)
        })
        
        navigationController?.pushViewController(groups, animated: true)
    }
    
    // Open chat for a group
    func openGroupChat(group: Group) {
        let messagesVC = CometChatMessages()
        messagesVC.set(group: group)
        navigationController?.pushViewController(messagesVC, animated: true)
    }
    
    // Create a new group
    func createGroup(name: String, type: CometChat.groupType) {
        let group = Group(
            guid: UUID().uuidString,
            name: name,
            groupType: type,
            password: nil
        )
        
        CometChat.createGroup(group: group) { createdGroup in
            print("Group created: \(createdGroup.name ?? "")")
            DispatchQueue.main.async {
                self.openGroupChat(group: createdGroup)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
    
    // Join a public group
    func joinGroup(guid: String) {
        CometChat.joinGroup(
            GUID: guid,
            groupType: .public,
            password: nil
        ) { group in
            print("Joined group: \(group.name ?? "")")
            DispatchQueue.main.async {
                self.openGroupChat(group: group)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}
```

**Related Guide:** [Groups](/docs/ui-kit/ios/groups)

## Quoted Reply

Reply to specific messages with context.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class QuotedReplyViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Quoted reply is enabled by default
        // Users can swipe right on a message or tap "Reply" in message actions
        
        let messagesVC = CometChatMessages()
        
        CometChat.getUser(UID: "cometchat-uid-1") { user in
            DispatchQueue.main.async {
                messagesVC.set(user: user)
                self.navigationController?.pushViewController(messagesVC, animated: true)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}
```

## Search

Search across conversations and messages.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class SearchViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Search is available in:
        // - CometChatConversations (search bar at top)
        // - CometChatMessageHeader (search button)
        
        let conversations = CometChatConversations()
        
        // Search is enabled by default
        // To hide search:
        // conversations.hideSearch = true
        
        navigationController?.pushViewController(conversations, animated: true)
    }
    
    // Open dedicated search screen
    func openSearch() {
        let search = CometChatSearch()
        navigationController?.pushViewController(search, animated: true)
    }
}
```

**Components Used:**

* [Search](/docs/ui-kit/ios/search) - Dedicated search screen
* [MessageHeader](/docs/ui-kit/ios/message-header) - Search within conversation
* [Conversations](/docs/ui-kit/ios/conversations) - Search conversations

## Moderation

Automatically filter inappropriate content.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ModerationViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Moderation is handled automatically based on your
        // CometChat dashboard settings
        
        // Blocked messages are displayed appropriately
        // based on your moderation rules
        
        let messagesVC = CometChatMessages()
        
        CometChat.getUser(UID: "cometchat-uid-1") { user in
            DispatchQueue.main.async {
                messagesVC.set(user: user)
                self.navigationController?.pushViewController(messagesVC, animated: true)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}
```

<Note>
  Configure moderation rules in your [CometChat Dashboard](/docs/moderation/overview).
</Note>

## Report Message

Allow users to report inappropriate messages.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ReportMessageViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Report message is available in message actions
        // Users can long-press a message and select "Report"
        
        let messagesVC = CometChatMessages()
        
        CometChat.getUser(UID: "cometchat-uid-1") { user in
            DispatchQueue.main.async {
                messagesVC.set(user: user)
                self.navigationController?.pushViewController(messagesVC, animated: true)
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}
```

<Note>
  View and manage reported messages in [Flagged Messages](/docs/moderation/flagged-messages).
</Note>


# Extensions
Source: https://www.cometchat.com/docs/ui-kit/ios/extensions

Enable CometChat iOS UI Kit extensions for stickers, polls, collaboration tools, reactions, moderation, smart replies, and link previews.

| Field           | Value                                                          |
| --------------- | -------------------------------------------------------------- |
| Dashboard setup | CometChat Dashboard → Extensions                               |
| Activation      | Enable in dashboard, features appear automatically in UI Kit   |
| Code required   | None — extensions work out of the box                          |
| Platforms       | Works across iOS, Android, and Web with the same configuration |

Extensions add powerful features to your chat app without writing any code. Simply enable them in your [CometChat Dashboard](https://app.cometchat.com), and they automatically appear in the UI Kit components.

## How Extensions Work

1. Log in to your [CometChat Dashboard](https://app.cometchat.com)
2. Navigate to the **Extensions** section
3. Enable the extensions you want
4. The features automatically appear in your app after initialization

<Note>
  Extensions are enabled at the dashboard level. Once activated, they work across all platforms (iOS, Android, Web) using the same CometChat app.
</Note>

## Composer Extensions

These extensions add new options to the [Message Composer](/docs/ui-kit/ios/message-composer) attachment menu or action sheet.

### Stickers

Let users express emotions with fun, pre-designed stickers.

<Frame>
  <img />
</Frame>

| Component                                        | Setup Guide                                 |
| ------------------------------------------------ | ------------------------------------------- |
| [Message Composer](/docs/ui-kit/ios/message-composer) | [Sticker Extension](/docs/fundamentals/stickers) |

### Polls

Create polls to gather opinions in group chats quickly.

<Frame>
  <img />
</Frame>

| Component                                        | Setup Guide                            |
| ------------------------------------------------ | -------------------------------------- |
| [Message Composer](/docs/ui-kit/ios/message-composer) | [Polls Extension](/docs/fundamentals/polls) |

### Collaborative Whiteboard

Real-time whiteboard for drawing, brainstorming, and sharing ideas together.

<Frame>
  <img />
</Frame>

| Component                                        | Setup Guide                                                        |
| ------------------------------------------------ | ------------------------------------------------------------------ |
| [Message Composer](/docs/ui-kit/ios/message-composer) | [Collaborative Whiteboard](/docs/fundamentals/collaborative-whiteboard) |

### Collaborative Document

Work together on shared documents in real-time with other users.

<Frame>
  <img />
</Frame>

| Component                                        | Setup Guide                                                    |
| ------------------------------------------------ | -------------------------------------------------------------- |
| [Message Composer](/docs/ui-kit/ios/message-composer) | [Collaborative Document](/docs/fundamentals/collaborative-document) |

### Smart Replies

AI-powered suggested responses for faster, more efficient conversations.

| Component                                        | Setup Guide                                  |
| ------------------------------------------------ | -------------------------------------------- |
| [Message Composer](/docs/ui-kit/ios/message-composer) | [Smart Replies](/docs/fundamentals/smart-replies) |

## Message List Extensions

These extensions enhance messages displayed in the [Message List](/docs/ui-kit/ios/message-list).

### Message Reactions

Let users react to messages with a range of emojis for quick responses.

<Frame>
  <img />
</Frame>

| Component                                | Setup Guide                                    |
| ---------------------------------------- | ---------------------------------------------- |
| [Message List](/docs/ui-kit/ios/message-list) | [Reactions Extension](/docs/fundamentals/reactions) |

### Message Translation

Translate messages into any language instantly, eliminating language barriers.

<Frame>
  <img />
</Frame>

| Component                                | Setup Guide                                              |
| ---------------------------------------- | -------------------------------------------------------- |
| [Message List](/docs/ui-kit/ios/message-list) | [Message Translation](/docs/fundamentals/message-translation) |

### Link Preview

Show rich previews for URLs shared in chat including title, description, and thumbnail.

<Frame>
  <img />
</Frame>

| Component                                | Setup Guide                                |
| ---------------------------------------- | ------------------------------------------ |
| [Message List](/docs/ui-kit/ios/message-list) | [Link Preview](/docs/fundamentals/link-preview) |

### Thumbnail Generation

Automatically create smaller preview images for faster loading and reduced bandwidth.

<Frame>
  <img />
</Frame>

| Component                                | Setup Guide                                                |
| ---------------------------------------- | ---------------------------------------------------------- |
| [Message List](/docs/ui-kit/ios/message-list) | [Thumbnail Generation](/docs/fundamentals/thumbnail-generation) |

## Moderation Extensions

These extensions help maintain a safe chat environment by filtering content automatically.

### Profanity Filter

Automatically censor inappropriate and obscene words in messages.

<Frame>
  <img />
</Frame>

| Component                                | Setup Guide                                                                                    |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [Message List](/docs/ui-kit/ios/message-list) | [Legacy Extensions](https://assets.cometchat.io/legacy-docs/moderation/legacy-extensions.html) |

### Data Masking

Automatically mask sensitive data like credit card numbers and phone numbers.

<Frame>
  <img />
</Frame>

| Component                                | Setup Guide                                                                                    |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [Message List](/docs/ui-kit/ios/message-list) | [Legacy Extensions](https://assets.cometchat.io/legacy-docs/moderation/legacy-extensions.html) |

### Image Moderation

Detect and filter inappropriate or explicit images using AI/ML.

<Frame>
  <img />
</Frame>

| Component                                | Setup Guide                                                                                    |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [Message List](/docs/ui-kit/ios/message-list) | [Legacy Extensions](https://assets.cometchat.io/legacy-docs/moderation/legacy-extensions.html) |

## Extensions Summary

| Extension        | Category     | Component        | Use Case               |
| ---------------- | ------------ | ---------------- | ---------------------- |
| Stickers         | Composer     | Message Composer | Fun expression         |
| Polls            | Composer     | Message Composer | Group decisions        |
| Whiteboard       | Composer     | Message Composer | Visual collaboration   |
| Document         | Composer     | Message Composer | Document collaboration |
| Smart Replies    | Composer     | Message Composer | Quick responses        |
| Reactions        | Message List | Message List     | Quick responses        |
| Translation      | Message List | Message List     | Multi-language support |
| Link Preview     | Message List | Message List     | Rich URL previews      |
| Thumbnails       | Message List | Message List     | Faster loading         |
| Profanity Filter | Moderation   | Message List     | Content moderation     |
| Data Masking     | Moderation   | Message List     | Privacy protection     |
| Image Moderation | Moderation   | Message List     | Safe content           |

## Next Steps

* [Extensions Overview](/docs/fundamentals/extensions-overview) — Full extension documentation
* [Moderation](/docs/moderation/overview) — Content moderation features
* [Message Composer](/docs/ui-kit/ios/message-composer) — Where composer extensions appear
* [Message List](/docs/ui-kit/ios/message-list) — Where message extensions appear


# iOS Integration
Source: https://www.cometchat.com/docs/ui-kit/ios/getting-started

Integrate CometChat iOS UI Kit with project setup, package installation, initialization, login, rendering, permissions, and optional calling.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                 |
  | ------------ | ------------------------------------------------------------------------------------- |
  | Package      | `CometChatUIKitSwift`                                                                 |
  | Version      | `5.1.18`                                                                              |
  | Requirements | Xcode 16+, iOS 13.0+, Swift 5.0+                                                      |
  | Init         | `CometChatUIKit.init(uiKitSettings:)` — must complete before `login()`                |
  | Login        | `CometChatUIKit.login(uid:)` — must complete before rendering components              |
  | Order        | `init()` → `login()` → render. Breaking this order = blank screen                     |
  | Auth Key     | Dev/testing only. Use Auth Token in production                                        |
  | Calling      | Optional. Install `CometChatCallsSDK 4.2.3` to enable                                 |
  | Dependencies | `CometChatSDK 4.1.7` (installed automatically)                                        |
  | AI Skills    | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills) |
</Accordion>

This guide walks you through adding CometChat to an iOS app. By the end you'll have a working chat UI.

<Frame>
  <img />
</Frame>

***

## Integrate with AI Coding Agents

Skip the manual steps — use [CometChat Skills](https://github.com/cometchat/cometchat-skills) to integrate via your AI coding agent. Your agent has a short conversation with you to understand your project and chat requirements, then writes production-grade integration code tailored to the files you already have.

```bash theme={null}
npx @cometchat/skills add
```

Use `--ide <name>` to target a specific IDE (e.g. `--ide cursor`), or `--ide all` for all supported IDEs.

Then in your IDE:

```
/cometchat add chat to my app
```

The skill detects your iOS project structure, navigation pattern (UIKit or SwiftUI), and existing auth system. It onboards you to CometChat directly in the terminal — signup, login, and app creation all via the CLI. It reads your view controllers, navigation, and components before proposing a placement, shows the plan, and waits for your approval before writing code. Credentials are saved via `Secrets.swift` or `.xcconfig`.

After the first integration, re-run `/cometchat` to access the iteration menu: theme presets, 40+ features, component customization, production auth, user management, and diagnostics.

Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [30+ more agents](https://github.com/cometchat/cometchat-skills).

***

## Prerequisites

You need three things from the [CometChat Dashboard](https://app.cometchat.com/):

| Credential | Where to find it                                           |
| ---------- | ---------------------------------------------------------- |
| App ID     | Dashboard → Your App → Credentials                         |
| Auth Key   | Dashboard → Your App → Credentials                         |
| Region     | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) |

You also need:

* Xcode 16 or later
* iOS device or simulator running iOS 13.0+
* Swift 5.0+
* macOS

<Warning>
  Auth Key is for development only. In production, generate Auth Tokens server-side via the [REST API](/docs/rest-api/chat-apis) and use [`loginWithAuthToken()`](/docs/ui-kit/ios/methods#login-using-auth-token). Never ship Auth Keys in client code.
</Warning>

***

## Step 1 — Create an iOS Project

Open Xcode and create a new project:

1. Select **iOS App** in the template picker and click Next
2. Enter your project name and bundle identifier
3. Select **Storyboard** for Interface
4. Select **Swift** for Language

***

## Step 2 — Install the UI Kit

<Tabs>
  <Tab title="CocoaPods">
    1. Create a Podfile in your project root:

    ```bash theme={null}
    pod init
    ```

    2. Add CometChat to your Podfile:

    ```ruby title="Podfile" theme={null}
    platform :ios, '13.0'
    use_frameworks!

    target 'YourApp' do
      pod 'CometChatUIKitSwift', '5.1.18'
      
      # Optional: Voice/Video Calling
      pod 'CometChatCallsSDK', '4.2.3'
    end
    ```

    3. Install dependencies:

    ```bash theme={null}
    pod install --repo-update
    ```

    4. Close the `.xcodeproj` file and open the `.xcworkspace` file instead. CocoaPods creates a workspace that includes your project and the installed pods.

    <Tip>
      Always open the `.xcworkspace` file after installing pods — opening the `.xcodeproj` will cause build errors. Having issues? See [CocoaPods Troubleshooting](/docs/ui-kit/ios/troubleshooting#cocoapods-issues).
    </Tip>
  </Tab>

  <Tab title="Swift Package Manager">
    1. Go to **File → Add Package Dependencies**

    2. Enter the repository URL:

    ```
    https://github.com/cometchat/cometchat-uikit-ios
    ```

    3. Select **Up to Exact Version** and enter:

    ```
    5.1.18
    ```

    4. Add the Chat SDK separately using:

    ```
    https://github.com/cometchat/chat-sdk-ios
    ```

    Exact Version: `4.1.7`
  </Tab>
</Tabs>

<Warning>
  **Pin the Chat SDK to the exact version the UI Kit requires.** `CometChatUIKitSwift` ships as a prebuilt binary compiled against one specific `CometChatSDK` version — for UI Kit `5.1.18` that is `CometChatSDK 4.1.7` (see the version table at the top of this page).

  * **CocoaPods** installs the matching `CometChatSDK` automatically when you run `pod install`. Don't add your own `CometChatSDK` pod pinned to a different version.
  * **Swift Package Manager** does not resolve it for you — add `chat-sdk-ios` with **Up to Exact Version** set to the version the UI Kit depends on. Forcing a newer or older Chat SDK (an SPM override) is unsupported and typically fails to build or crashes at runtime.

  To adopt a newer Chat SDK release, upgrade to a UI Kit version that depends on it rather than overriding the SDK version directly. The full list of Chat SDK releases is on [GitHub](https://github.com/cometchat/chat-sdk-ios/releases).
</Warning>

***

## Step 3 — Configure Permissions

Add these keys to your `Info.plist` for media messaging:

```xml title="Info.plist" lines theme={null}
<key>NSCameraUsageDescription</key>
<string>Allow access to the camera to capture photos and videos.</string>

<key>NSMicrophoneUsageDescription</key>
<string>Enable microphone access for voice and video communication.</string>

<key>NSPhotoLibraryAddUsageDescription</key>
<string>Allow saving photos and videos to your device's photo library.</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>Grant access to select and upload photos from your library.</string>
```

<Frame>
  <img />
</Frame>

Also disable **User Script Sandboxing** in Build Settings to ensure WebView can load scripts for collaborative tools:

1. Select your project in the Navigator
2. Select your app target
3. Go to **Build Settings** tab
4. Search for "User Script Sandboxing"
5. Set it to **No**

<Frame>
  <img />
</Frame>

***

## Step 4 — Initialize & Login

Add this to your `SceneDelegate.swift`. Init must complete before login, and login must complete before rendering any UI.

```swift title="SceneDelegate.swift" lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = (scene as? UIWindowScene) else { return }

        let uikitSettings = UIKitSettings()
            .set(appID: "APP_ID")        // Replace with your App ID
            .set(region: "REGION")       // Replace with your Region
            .set(authKey: "AUTH_KEY")    // Replace with your Auth Key (dev only)
            .subscribePresenceForAllUsers()
            .build()

        CometChatUIKit.init(uiKitSettings: uikitSettings) { result in
            switch result {
            case .success:
                debugPrint("CometChat initialized")
                
                let uid = "cometchat-uid-1"  // Test user
                
                CometChatUIKit.login(uid: uid) { loginResult in
                    switch loginResult {
                    case .success:
                        debugPrint("Login successful")
                        
                        // ✅ Option 1: Launch One-to-One or Group Chat Screen
                        // DispatchQueue.main.async { 
                        //     self.setUpOneOneOrGroupConversation(windowScene: windowScene, uid: "cometchat-uid-2")
                        // }

                        // ✅ Option 2: Launch Conversation List + Message View
                        // DispatchQueue.main.async {
                        //     self.setupConversationsView(windowScene: windowScene)
                        // }

                        // ✅ Option 3: Launch Tab-Based Chat Experience
                        // DispatchQueue.main.async {
                        //     self.setupTabbedView(windowScene: windowScene)
                        // }
                        
                    case .onError(let error):
                        debugPrint("Login failed: \(error.description)")
                    @unknown default:
                        break
                    }
                }
                
            case .failure(let error):
                debugPrint("Init failed: \(error.localizedDescription)")
            }
        }
    }
}
```

For development, use one of the pre-created test UIDs:

`cometchat-uid-1` · `cometchat-uid-2` · `cometchat-uid-3` · `cometchat-uid-4` · `cometchat-uid-5`

Or create new users via the [CometChat Dashboard](https://app.cometchat.com), [SDK method](/docs/ui-kit/ios/methods#create-user), or [REST API](/docs/rest-api/chat-apis).

After running the app, you should see:

```sh theme={null}
"CometChat initialized"
"Login successful"
```

<Warning>
  `init()` must complete before you call `login()`. If you call `login()` before init completes, it will fail silently.
</Warning>

<Note>
  For production, use [`loginWithAuthToken()`](/docs/ui-kit/ios/methods#login-using-auth-token) instead of Auth Key. Generate tokens server-side via the REST API.
</Note>

<Tip>
  Having issues? Check the [Troubleshooting Guide](/docs/ui-kit/ios/troubleshooting) for common problems and solutions.
</Tip>

***

## Step 5 — Choose a Chat Experience

Integrate a conversation view that suits your app's UX. Each option below includes a step-by-step guide.

### Conversation List + Message View

Two-panel layout — conversation list with push navigation to messages. Think iMessage or WhatsApp.

* Push-based navigation between conversations and messages
* Supports one-to-one and group chats
* Real-time sync with CometChat event listeners
* Session-aware — message states persist across app sessions

<Frame>
  <img />
</Frame>

<Card title="Build Conversation List + Message View" href="/ui-kit/ios/ios-conversation" icon="comments">
  Step-by-step guide to build this layout
</Card>

***

### One-to-One / Group Chat

Single chat window — no sidebar. Good for support chat, contextual messaging, or focused conversations.

* Dedicated chat window for one-on-one or group messaging
* No conversation list — users go directly into the chat
* Full-screen experience optimized for mobile
* Ideal for support workflows, community replies, or invitations

<Frame>
  <img />
</Frame>

<Card title="Build One-to-One / Group Chat" href="/ui-kit/ios/ios-one-to-one-chat" icon="message">
  Step-by-step guide to build this layout
</Card>

***

### Tab-Based Chat

Tabbed navigation — Chats, Calls, Users, Groups in separate tabs. Good for full-featured apps.

* UITabBarController or SwiftUI TabView navigation
* Full-screen messaging within each tab
* Modular UI — isolated controllers for each tab
* Scales well for adding future features like notifications or settings

<Frame>
  <img />
</Frame>

<Card title="Build Tab-Based Chat" href="/ui-kit/ios/ios-tab-based-chat" icon="table-columns">
  Step-by-step guide to build this layout
</Card>

***

## Build Your Own Chat Experience

Need full control over the UI? Use individual components, customize themes, and wire up your own layouts.

* [Sample App](https://github.com/cometchat/cometchat-uikit-ios/tree/v5/SampleApp) — Working reference app to compare against
* [Components](/docs/ui-kit/ios/components-overview) — All prebuilt UI elements with customization options
* [Core Features](/docs/ui-kit/ios/core-features) — Messaging, real-time updates, and other capabilities
* [Theming](/docs/ui-kit/ios/theme-introduction) — Colors, fonts, dark mode, and custom styling
* [Build Your Own UI](/docs/sdk/ios/overview) — Skip the UI Kit entirely and build on the raw SDK

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/ios/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/ios/theme-introduction">
    Customize colors, fonts, and styles
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/ios/core-features">
    Chat features included out of the box
  </Card>

  <Card title="Methods" icon="code" href="/ui-kit/ios/methods">
    SDK methods and API reference
  </Card>
</CardGroup>


# Conversation List + Message View
Source: https://www.cometchat.com/docs/ui-kit/ios/ios-conversation

Build CometChat iOS UI Kit conversation list and message view layouts with push navigation, headers, message lists, and composers.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                  |
  | ------------ | ------------------------------------------------------------------------------------------------------ |
  | Package      | `CometChatUIKitSwift`                                                                                  |
  | Framework    | UIKit / SwiftUI                                                                                        |
  | Components   | `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Push navigation — conversation list → message view                                                     |
  | Prerequisite | Complete [iOS Integration](/docs/ui-kit/ios/getting-started) Steps 1–4 first                                |
  | Pattern      | iMessage, WhatsApp, Slack                                                                              |
</Accordion>

This guide builds a conversation list with push navigation to messages. Users tap a conversation to open the chat view.

This assumes you've already completed [iOS Integration](/docs/ui-kit/ios/getting-started) (project created, UI Kit installed, init + login working, permissions configured).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three components working together:

1. **Conversation list** — shows all active conversations (users and groups)
2. **Message view** — displays chat messages for the selected conversation in real time
3. **Message composer** — text input with support for media, emojis, and reactions

***

## Step 1 — Setup SceneDelegate

Wire up the conversation list after successful login. When a user taps a conversation, push to the messages view.

```swift title="SceneDelegate.swift" highlight={13-15} lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = (scene as? UIWindowScene) else { return }

        let uikitSettings = UIKitSettings()
            .set(appID: "APP_ID")        // Replace with your App ID
            .set(region: "REGION")       // Replace with your Region
            .set(authKey: "AUTH_KEY")    // Replace with your Auth Key (dev only)
            .subscribePresenceForAllUsers()
            .build()

        CometChatUIKit.init(uiKitSettings: uikitSettings) { result in
            switch result {
            case .success:
                debugPrint("CometChat initialized")

                let uid = "cometchat-uid-1"

                CometChatUIKit.login(uid: uid) { loginResult in
                    switch loginResult {
                    case .success:
                        debugPrint("Login successful")

                        DispatchQueue.main.async { [weak self] in
                            self?.setupConversationsView(windowScene: windowScene)
                        }

                    case .onError(let error):
                        debugPrint("Login failed: \(error.description)")
                    @unknown default: break
                    }
                }

            case .failure(let error):
                debugPrint("Init failed: \(error.localizedDescription)")
            }
        }
    }

    func setupConversationsView(windowScene: UIWindowScene) {
        let conversationsVC = CometChatConversations()
        let navController = UINavigationController(rootViewController: conversationsVC)

        conversationsVC.set(onItemClick: { [weak navController] conversation, _ in
            let messagesVC = MessagesVC()
            messagesVC.group = conversation.conversationWith as? Group
            messagesVC.user = conversation.conversationWith as? User
            navController?.pushViewController(messagesVC, animated: true)
        })

        window = UIWindow(windowScene: windowScene)
        window?.rootViewController = navController
        window?.makeKeyAndVisible()
    }
}
```

Key points:

* `CometChatConversations` displays the conversation list
* `onItemClick` fires when a user taps a conversation, passing the `Conversation` object
* Extract `User` or `Group` from `conversation.conversationWith` and pass to the messages view

***

## Step 2 — Create MessagesVC

Create a new Swift file for the messages view controller:

1. In Xcode, right-click your project folder in the Navigator
2. Select **New File...**
3. Choose **Swift File** and click Next
4. Name it `MessagesVC.swift` and click Create

Add the following code. This view controller assembles the header, message list, and composer.

```swift title="MessagesVC.swift" lines theme={null}
import UIKit
import CometChatSDK
import CometChatUIKitSwift

class MessagesVC: UIViewController {
    
    // MARK: - Properties
    var user: User?
    var group: Group?
    
    // MARK: - UI Components
    private lazy var headerView: CometChatMessageHeader = {
        let view = CometChatMessageHeader()
        view.translatesAutoresizingMaskIntoConstraints = false
        if let user = user {
            view.set(user: user)
        } else if let group = group {
            view.set(group: group)
        }
        view.set(controller: self)
        return view
    }()
    
    private lazy var messageListView: CometChatMessageList = {
        let listView = CometChatMessageList()
        listView.translatesAutoresizingMaskIntoConstraints = false
        if let user = user {
            listView.set(user: user)
        } else if let group = group {
            listView.set(group: group)
        }
        listView.set(controller: self)
        return listView
    }()
    
    private lazy var composerView: CometChatMessageComposer = {
        let composer = CometChatMessageComposer()
        composer.translatesAutoresizingMaskIntoConstraints = false
        if let user = user {
            composer.set(user: user)
        } else if let group = group {
            composer.set(group: group)
        }
        composer.set(controller: self)
        return composer
    }()
    
    // MARK: - Lifecycle
    override func viewDidLoad() {
        super.viewDidLoad()
        configureView()
        setupLayout()
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        navigationController?.setNavigationBarHidden(false, animated: true)
    }
    
    // MARK: - Setup
    private func configureView() {
        view.backgroundColor = .systemBackground
        navigationController?.setNavigationBarHidden(true, animated: false)
    }
    
    private func setupLayout() {
        [headerView, messageListView, composerView].forEach { view.addSubview($0) }
        
        NSLayoutConstraint.activate([
            // Header
            headerView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
            headerView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            headerView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            headerView.heightAnchor.constraint(equalToConstant: 50),
            
            // Message list
            messageListView.topAnchor.constraint(equalTo: headerView.bottomAnchor),
            messageListView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            messageListView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            messageListView.bottomAnchor.constraint(equalTo: composerView.topAnchor),
            
            // Composer
            composerView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            composerView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            composerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
        ])
    }
}
```

How it works:

* `CometChatMessageHeader` shows user/group info and back button
* `CometChatMessageList` displays messages with real-time updates
* `CometChatMessageComposer` handles text input, media, and reactions
* Pass either `user` or `group` to each component, never both

***

## Step 3 — Run the Project

Build and run in Xcode. You should see the conversation list. Tap any conversation to push to the messages view.

***

## Next Steps

<CardGroup>
  <Card title="Theming" icon="paintbrush" href="/ui-kit/ios/theme-introduction">
    Customize colors, fonts, and styles to match your brand
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/ios/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="iOS Integration" icon="apple" href="/ui-kit/ios/getting-started">
    Back to the main setup guide
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/ios/core-features">
    Chat features included out of the box
  </Card>
</CardGroup>


# One-to-One / Group Chat
Source: https://www.cometchat.com/docs/ui-kit/ios/ios-one-to-one-chat

Build focused CometChat iOS UI Kit one-to-one or group chat screens with headers, message lists, composers, and direct chat navigation.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                        |
  | ------------ | ---------------------------------------------------------------------------- |
  | Package      | `CometChatUIKitSwift`                                                        |
  | Framework    | UIKit / SwiftUI                                                              |
  | Components   | `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | Single chat window — no sidebar, no conversation list                        |
  | Prerequisite | Complete [iOS Integration](/docs/ui-kit/ios/getting-started) Steps 1–4 first      |
  | Pattern      | Support chat, embedded widgets, focused messaging                            |
</Accordion>

This guide builds a single chat window — no sidebar, no conversation list. Users go directly into a one-to-one or group chat. Good for support chat, contextual messaging, or any focused messaging experience.

This assumes you've already completed [iOS Integration](/docs/ui-kit/ios/getting-started) (project created, UI Kit installed, init + login working, permissions configured).

<Frame>
  <img />
</Frame>

***

## What You're Building

Three components stacked vertically:

1. **Chat header** — displays recipient name, avatar, online status, and optional call buttons
2. **Message list** — real-time chat history with scrolling
3. **Message composer** — text input with media, emojis, and reactions

***

## Step 1 — Setup SceneDelegate

Fetch the user (or group) after login and launch directly into the messages view.

```swift title="SceneDelegate.swift" highlight={13-15,34} lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = (scene as? UIWindowScene) else { return }

        let uikitSettings = UIKitSettings()
            .set(appID: "APP_ID")        // Replace with your App ID
            .set(region: "REGION")       // Replace with your Region
            .set(authKey: "AUTH_KEY")    // Replace with your Auth Key (dev only)
            .subscribePresenceForAllUsers()
            .build()

        CometChatUIKit.init(uiKitSettings: uikitSettings) { result in
            switch result {
            case .success:
                debugPrint("CometChat initialized")

                let uid = "cometchat-uid-1"

                CometChatUIKit.login(uid: uid) { loginResult in
                    switch loginResult {
                    case .success:
                        debugPrint("Login successful")

                        DispatchQueue.main.async { [weak self] in
                            self?.setUpOneOneOrGroupConversation(
                                windowScene: windowScene,
                                uid: "cometchat-uid-2"  // The user to chat with
                            )
                        }

                    case .onError(let error):
                        debugPrint("Login failed: \(error.description)")
                    @unknown default: break
                    }
                }

            case .failure(let error):
                debugPrint("Init failed: \(error.localizedDescription)")
            }
        }
    }

    func setUpOneOneOrGroupConversation(windowScene: UIWindowScene, uid: String) {
        CometChat.getUser(UID: uid) { user in
            DispatchQueue.main.async {
                let messagesVC = MessagesVC()
                messagesVC.user = user
                
                let navController = UINavigationController(rootViewController: messagesVC)
                self.window = UIWindow(windowScene: windowScene)
                self.window?.rootViewController = navController
                self.window?.makeKeyAndVisible()
            }
        } onError: { error in
            debugPrint("Failed to fetch user: \(error?.description ?? "")")
        }
    }
}
```

Key points:

* `CometChat.getUser(UID:)` fetches the user object from the SDK — you need a real user object, not a manually constructed one.
* The highlighted lines show where to set the credentials and the UID of the user to chat with.

***

## Switching Between User and Group Chat

To load a group chat instead of one-to-one, replace `getUser` with `getGroup`:

```swift highlight={2} lines theme={null}
func setUpGroupConversation(windowScene: UIWindowScene, guid: String) {
    CometChat.getGroup(GUID: guid) { group in
        DispatchQueue.main.async {
            let messagesVC = MessagesVC()
            messagesVC.group = group
            
            let navController = UINavigationController(rootViewController: messagesVC)
            self.window = UIWindow(windowScene: windowScene)
            self.window?.rootViewController = navController
            self.window?.makeKeyAndVisible()
        }
    } onError: { error in
        debugPrint("Failed to fetch group: \(error?.description ?? "")")
    }
}
```

***

## Step 2 — Create MessagesVC

Create a new Swift file for the messages view controller:

1. In Xcode, right-click your project folder in the Navigator
2. Select **New File...**
3. Choose **Swift File** and click Next
4. Name it `MessagesVC.swift` and click Create

Add the following code. This view controller assembles the header, message list, and composer.

```swift title="MessagesVC.swift" lines theme={null}
import UIKit
import CometChatSDK
import CometChatUIKitSwift

class MessagesVC: UIViewController {
    
    // MARK: - Properties
    var user: User?
    var group: Group?
    
    // MARK: - UI Components
    private lazy var headerView: CometChatMessageHeader = {
        let view = CometChatMessageHeader()
        view.translatesAutoresizingMaskIntoConstraints = false
        if let user = user {
            view.set(user: user)
        } else if let group = group {
            view.set(group: group)
        }
        view.set(controller: self)
        return view
    }()
    
    private lazy var messageListView: CometChatMessageList = {
        let listView = CometChatMessageList()
        listView.translatesAutoresizingMaskIntoConstraints = false
        if let user = user {
            listView.set(user: user)
        } else if let group = group {
            listView.set(group: group)
        }
        listView.set(controller: self)
        return listView
    }()
    
    private lazy var composerView: CometChatMessageComposer = {
        let composer = CometChatMessageComposer()
        composer.translatesAutoresizingMaskIntoConstraints = false
        if let user = user {
            composer.set(user: user)
        } else if let group = group {
            composer.set(group: group)
        }
        composer.set(controller: self)
        return composer
    }()
    
    // MARK: - Lifecycle
    override func viewDidLoad() {
        super.viewDidLoad()
        configureView()
        setupLayout()
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        navigationController?.setNavigationBarHidden(false, animated: true)
    }
    
    // MARK: - Setup
    private func configureView() {
        view.backgroundColor = .systemBackground
        navigationController?.setNavigationBarHidden(true, animated: false)
    }
    
    private func setupLayout() {
        [headerView, messageListView, composerView].forEach { view.addSubview($0) }
        
        NSLayoutConstraint.activate([
            // Header
            headerView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
            headerView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            headerView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            headerView.heightAnchor.constraint(equalToConstant: 50),
            
            // Message list
            messageListView.topAnchor.constraint(equalTo: headerView.bottomAnchor),
            messageListView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            messageListView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            messageListView.bottomAnchor.constraint(equalTo: composerView.topAnchor),
            
            // Composer
            composerView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            composerView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            composerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
        ])
    }
}
```

How it works:

* `CometChatMessageHeader` shows user/group info and back button
* `CometChatMessageList` displays messages with real-time updates
* `CometChatMessageComposer` handles text input, media, and reactions
* Pass either `user` or `group` to each component, never both

***

## Step 3 — Run the Project

Build and run in Xcode. You should see the chat window load directly with the conversation for the UID you set.

***

## Next Steps

<CardGroup>
  <Card title="Theming" icon="paintbrush" href="/ui-kit/ios/theme-introduction">
    Customize colors, fonts, and styles to match your brand
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/ios/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="iOS Integration" icon="apple" href="/ui-kit/ios/getting-started">
    Back to the main setup guide
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/ios/core-features">
    Chat features included out of the box
  </Card>
</CardGroup>


# Tab-Based Chat
Source: https://www.cometchat.com/docs/ui-kit/ios/ios-tab-based-chat

Build CometChat iOS UI Kit tab-based chat with Chats, Calls, Users, and Groups tabs, message views, and UITabBarController navigation.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                                                                            |
  | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package      | `CometChatUIKitSwift`                                                                                                                                            |
  | Framework    | UIKit / SwiftUI                                                                                                                                                  |
  | Components   | `CometChatConversations`, `CometChatCallLogs`, `CometChatUsers`, `CometChatGroups`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` |
  | Layout       | UITabBarController with Chats, Calls, Users, Groups tabs                                                                                                         |
  | Prerequisite | Complete [iOS Integration](/docs/ui-kit/ios/getting-started) Steps 1–4 first                                                                                          |
  | Pattern      | Full-featured messaging app with multiple sections                                                                                                               |
</Accordion>

This guide builds a tabbed messaging UI — Chats, Calls, Users, and Groups tabs using `UITabBarController`. Good for full-featured apps that need more than just conversations.

This assumes you've already completed [iOS Integration](/docs/ui-kit/ios/getting-started) (project created, UI Kit installed, init + login working, permissions configured).

<Frame>
  <img />
</Frame>

***

## What You're Building

Four tabs working together:

1. **Chats** — conversation list with push navigation to messages
2. **Calls** — call logs history
3. **Users** — list of available users
4. **Groups** — list of available groups

***

## Step 1 — Setup SceneDelegate

Initialize CometChat and launch the tabbed view after login.

```swift title="SceneDelegate.swift" highlight={9-11} lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
    guard let windowScene = (scene as? UIWindowScene) else { return }

    let uikitSettings = UIKitSettings()
        .set(appID: "APP_ID")        // Replace with your App ID
        .set(region: "REGION")       // Replace with your Region
        .set(authKey: "AUTH_KEY")    // Replace with your Auth Key (dev only)
        .subscribePresenceForAllUsers()
        .build()

    CometChatUIKit.init(uiKitSettings: uikitSettings) { result in
        switch result {
        case .success:
            CometChatUIKit.login(uid: "cometchat-uid-1") { loginResult in
                switch loginResult {
                case .success:
                    DispatchQueue.main.async {
                        self.setupTabbedView(windowScene: windowScene)
                    }
                default:
                    break
                }
            }
        default:
            break
        }
    }
}
```

***

## Step 2 — Setup Tab Bar

Create the `UITabBarController` with all four tabs. Each tab has its own navigation controller.

```swift title="SceneDelegate.swift" lines theme={null}
func setupTabbedView(windowScene: UIWindowScene) {
    let tabBarController = UITabBarController()
    tabBarController.tabBar.backgroundColor = .white
    
    // MARK: - Conversations Tab
    let conversationsVC = CometChatConversations()
    let conversationsNav = UINavigationController(rootViewController: conversationsVC)
    conversationsVC.tabBarItem = UITabBarItem(
        title: "CHATS",
        image: UIImage(systemName: "message.fill"),
        tag: 0
    )
    
    conversationsVC.set(onItemClick: { [weak conversationsNav] conversation, indexPath in
        let messagesVC = MessagesVC()
        messagesVC.group = conversation.conversationWith as? Group
        messagesVC.user = conversation.conversationWith as? User
        messagesVC.hidesBottomBarWhenPushed = true
        conversationsNav?.pushViewController(messagesVC, animated: true)
    })
    
    // MARK: - Call Logs Tab
    let callLogsVC = CometChatCallLogs()
    let callLogsNav = UINavigationController(rootViewController: callLogsVC)
    callLogsVC.tabBarItem = UITabBarItem(
        title: "CALLS",
        image: UIImage(systemName: "phone.fill"),
        tag: 1
    )
    
    // MARK: - Users Tab
    let usersVC = CometChatUsers()
    let usersNav = UINavigationController(rootViewController: usersVC)
    usersVC.tabBarItem = UITabBarItem(
        title: "USERS",
        image: UIImage(systemName: "person.2.fill"),
        tag: 2
    )
    
    // MARK: - Groups Tab
    let groupsVC = CometChatGroups()
    let groupsNav = UINavigationController(rootViewController: groupsVC)
    groupsVC.tabBarItem = UITabBarItem(
        title: "GROUPS",
        image: UIImage(systemName: "person.3.fill"),
        tag: 3
    )
    
    tabBarController.viewControllers = [
        conversationsNav,
        callLogsNav,
        usersNav,
        groupsNav
    ]
    
    tabBarController.extendedLayoutIncludesOpaqueBars = true
    
    window = UIWindow(windowScene: windowScene)
    window?.rootViewController = tabBarController
    window?.makeKeyAndVisible()
}
```

Key points:

* Each tab wraps its view controller in a `UINavigationController` for push navigation
* `onItemClick` on conversations pushes to the messages view
* `hidesBottomBarWhenPushed = true` hides the tab bar when viewing messages
* SF Symbols are used for tab icons — customize as needed

***

## Step 3 — Create MessagesVC

Create a new Swift file for the messages view controller:

1. In Xcode, right-click your project folder in the Navigator
2. Select **New File...**
3. Choose **Swift File** and click Next
4. Name it `MessagesVC.swift` and click Create

Add the following code. This view controller assembles the header, message list, and composer.

```swift title="MessagesVC.swift" lines theme={null}
import UIKit
import CometChatSDK
import CometChatUIKitSwift

class MessagesVC: UIViewController {
    
    // MARK: - Properties
    var user: User?
    var group: Group?
    
    // MARK: - UI Components
    private lazy var headerView: CometChatMessageHeader = {
        let view = CometChatMessageHeader()
        view.translatesAutoresizingMaskIntoConstraints = false
        if let user = user {
            view.set(user: user)
        } else if let group = group {
            view.set(group: group)
        }
        view.set(controller: self)
        return view
    }()
    
    private lazy var messageListView: CometChatMessageList = {
        let listView = CometChatMessageList()
        listView.translatesAutoresizingMaskIntoConstraints = false
        if let user = user {
            listView.set(user: user)
        } else if let group = group {
            listView.set(group: group)
        }
        listView.set(controller: self)
        return listView
    }()
    
    private lazy var composerView: CometChatMessageComposer = {
        let composer = CometChatMessageComposer()
        composer.translatesAutoresizingMaskIntoConstraints = false
        if let user = user {
            composer.set(user: user)
        } else if let group = group {
            composer.set(group: group)
        }
        composer.set(controller: self)
        return composer
    }()
    
    // MARK: - Lifecycle
    override func viewDidLoad() {
        super.viewDidLoad()
        configureView()
        setupLayout()
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        navigationController?.setNavigationBarHidden(false, animated: true)
    }
    
    // MARK: - Setup
    private func configureView() {
        view.backgroundColor = .systemBackground
        navigationController?.setNavigationBarHidden(true, animated: false)
    }
    
    private func setupLayout() {
        [headerView, messageListView, composerView].forEach { view.addSubview($0) }
        
        NSLayoutConstraint.activate([
            // Header
            headerView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
            headerView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            headerView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            headerView.heightAnchor.constraint(equalToConstant: 50),
            
            // Message list
            messageListView.topAnchor.constraint(equalTo: headerView.bottomAnchor),
            messageListView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            messageListView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            messageListView.bottomAnchor.constraint(equalTo: composerView.topAnchor),
            
            // Composer
            composerView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            composerView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            composerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
        ])
    }
}
```

***

## Step 4 — Run the Project

Build and run in Xcode. You should see the tab bar at the bottom with Chats, Calls, Users, and Groups. Tap any conversation to push to the messages view.

***

## Next Steps

<CardGroup>
  <Card title="Theming" icon="paintbrush" href="/ui-kit/ios/theme-introduction">
    Customize colors, fonts, and styles to match your brand
  </Card>

  <Card title="Components Overview" icon="grid-2" href="/ui-kit/ios/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="iOS Integration" icon="apple" href="/ui-kit/ios/getting-started">
    Back to the main setup guide
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/ios/core-features">
    Chat features included out of the box
  </Card>
</CardGroup>


# Localize
Source: https://www.cometchat.com/docs/ui-kit/ios/localize

Adapt CometChat UI Kit to different languages and customize date/time formatting for your iOS application

<Accordion title="AI Integration Quick Reference">
  | Field               | Value                                                                                      |
  | ------------------- | ------------------------------------------------------------------------------------------ |
  | Platform            | iOS UI Kit                                                                                 |
  | Localize Class      | `CometChatLocalize`                                                                        |
  | Set Locale          | `CometChatLocalize.set(locale: .french)`                                                   |
  | Get Locale          | `CometChatLocalize.getLocale()`                                                            |
  | Supported Languages | 17 languages (en, fr, de, es, hi, ru, pt, zh, ja, ko, tr, ms, sv, lt, hu, nl)              |
  | Override Strings    | Define same key in app's `Localizable.strings`                                             |
  | DateTime Formatter  | `CometChatUIKit.dateTimeFormatter` or component-level                                      |
  | DateTime Closures   | `time`, `today`, `yesterday`, `lastweek`, `otherDay`, `minute`, `minutes`, `hour`, `hours` |
</Accordion>

## Overview

CometChat UI Kit provides language localization to adapt to the language of a specific country or region. The `CometChatLocalize` class allows you to detect the language of your users based on their browser or device settings, and set the language accordingly.

`CometChatLocalize` is a class that includes methods related to locale. Developers can use these methods to change the language of the UI Kit library.

### Supported Languages

The UI Kit supports 17 languages for localization:

| Language   | Code          | Language   | Code |
| ---------- | ------------- | ---------- | ---- |
| English    | `en`, `en-US` | Japanese   | `ja` |
| English-UK | `en-GB`       | Korean     | `ko` |
| Chinese    | `zh`, `zh-TW` | Turkish    | `tr` |
| Spanish    | `es`          | Malay      | `ms` |
| Hindi      | `hi`          | Swedish    | `sv` |
| Russian    | `ru`          | Lithuanian | `lt` |
| Portuguese | `pt`          | Hungarian  | `hu` |
| French     | `fr`          | Dutch      | `nl` |
| German     | `de`          |            |      |

***

## How Localization Works

Localization in the SDK is powered by:

1. The `CometChatLocalize` class — for setting and fetching the active locale
2. A `String` extension method called `.localize` — to fetch localized text dynamically

```swift lines theme={null}
// Example: Localizing a string key
"CHATS".localize
```

The SDK checks the following bundles in order:

1. The app's `Localizable.strings` (for developer-defined overrides)
2. The SDK's built-in localization files
3. Fallback to English or the original key if no match is found

***

## Methods

The `CometChatLocalize` class provides the following methods:

| Method         | Description                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------- |
| `set(locale:)` | Sets the language using Language enum (`.english`, `.french`, etc.)                                   |
| `getLocale()`  | Returns the currently active locale. By default, returns the current language from the device/browser |

### Usage

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Set Language to French
    CometChatLocalize.set(locale: .french)

    // Get Current Language
    let lang = CometChatLocalize.getLocale()
    ```
  </Tab>
</Tabs>

***

## App-Level Overrides

To customize any text used by the SDK, simply define the same key in your app's `Localizable.strings` files.

<Tabs>
  <Tab title="Localizable.strings (en.lproj)">
    ```swift lines theme={null}
    "CHATS" = "Conversations";
    "USERS" = "People";
    ```
  </Tab>
</Tabs>

When your app runs, this will override the SDK's built-in translation for "CHATS" and "USERS" wherever they are used via `.localize`.

No additional configuration is needed.

***

## How to Discover Available Keys

All localization keys used by the SDK are available in our [GitHub repository](https://github.com/cometchat/cometchat-uikit-ios/tree/v5/CometChatUIKitSwift/Components/Shared/Resources). This allows you to:

* Know exactly which keys are used
* Provide custom translations for them in your app
* Keep your localization files in sync with SDK updates

By using the `CometChatLocalize` class, you can provide a user-friendly, localized experience to your users, enhancing the overall user experience within your application.

***

## Customization

CometChatUIKit for iOS allows developers to customize localization values easily. For example, if an English-language app requires the label "Chat" to be shown as "Chats," the developer can simply define the same localization key used in the UIKit inside the app's English localization file and assign it a different value. CometChatUIKit will automatically detect and use the overridden value from the app-level localization.

### Steps to Customize Strings

1. **Identify the String Key**
   * Check the UIKit source code for the exact key of the string you want to modify: [Localization file](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Shared/Resources/en.lproj/Localizable.strings)

2. **Navigate to the App Level Localization File**
   * Add the same key with the changed value you want

3. **Build and Run Your App**
   * The changes will automatically reflect wherever the key is used

***

## DateTimeFormatter

This feature allows developers to customize how date and time values are displayed across the CometChat UI Kit components. It introduces the `CometChatDateTimeFormatter` class, enabling tailored formatting for strings such as "Today", "Yesterday", or time formats like "12:00 PM".

Custom formats can be set based on locale, branding, or user preferences, enhancing localization and UX consistency.

Rather than always showing a static date like "27/04/2025, 3:45 PM", developers can customize how the date is displayed depending on how old the message is — such as:

* "Just now"
* "2 minutes ago"
* "Today, 3:45 PM"
* "Yesterday, 4:20 PM"
* "Last week", etc.

This system uses closures that you can override to provide your own custom strings.

***

### CometChatDateTimeFormatter

`CometChatDateTimeFormatter` is a configuration class that exposes customizable closures for various time-related strings. Developers can assign custom behavior to each closure based on their desired formatting logic.

#### Available Closures

| Property    | Description                                                        | Code                                                   |
| ----------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| `time`      | Called to format a timestamp as a standard time (e.g., "12:30 PM") | `CometChatUIKit.dateTimeFormatter.time = { ... }`      |
| `today`     | Called when rendering messages sent today                          | `CometChatUIKit.dateTimeFormatter.today = { ... }`     |
| `yesterday` | Called for yesterday's messages                                    | `CometChatUIKit.dateTimeFormatter.yesterday = { ... }` |
| `lastWeek`  | Called for messages within the last week                           | `CometChatUIKit.dateTimeFormatter.lastWeek = { ... }`  |
| `otherDay`  | Called for dates older than last week                              | `CometChatUIKit.dateTimeFormatter.otherDay = { ... }`  |
| `minute`    | Called when referring to "a minute ago"                            | `CometChatUIKit.dateTimeFormatter.minute = { ... }`    |
| `minutes`   | Called for "x minutes ago"                                         | `CometChatUIKit.dateTimeFormatter.minutes = { ... }`   |
| `hour`      | Called for "an hour ago"                                           | `CometChatUIKit.dateTimeFormatter.hour = { ... }`      |
| `hours`     | Called for "x hours ago"                                           | `CometChatUIKit.dateTimeFormatter.hours = { ... }`     |

Each closure receives a timestamp (`Int`, representing UNIX time) and must return a `String` representing the formatted time.

***

### Integration Options

The formatter can be applied at three levels:

#### 1. Global Level

A global formatter is available via `CometChatUIKit.dateTimeFormatter`. Use this to apply formatting across all components in the `CometChatUIKit`.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    CometChatUIKit.dateTimeFormatter.hour = { timestamp in
        return "Today"
    }

    CometChatUIKit.dateTimeFormatter.time = { timestamp in
        return "12:00 PM"
    }
    ```
  </Tab>
</Tabs>

#### 2. Component Global Level

Each component has a static formatter that overrides the global formatter only for that component across all instances.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    CometChatMessageList.dateTimeFormatter.hour = { timestamp in
        return "Today"
    }

    CometChatMessageList.dateTimeFormatter.time = { timestamp in
        return "12:00 PM"
    }
    ```
  </Tab>
</Tabs>

#### 3. Local Component Level

Components also expose an instance-level formatter for per-instance customization. This provides the highest precedence.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let messageList = CometChatMessageList()
    messageList.set(user: user)

    messageList.dateTimeFormatter.hour = { timestamp in
        return "Today"
    }

    messageList.dateTimeFormatter.time = { timestamp in
        return "12:00 PM"
    }
    ```
  </Tab>
</Tabs>

***

### Component-Level Date-Time Formatting Options

The following components support `dateTimeFormatter`:

* [CometChatConversations](/docs/ui-kit/ios/conversations#date-time-formatter)
* [CometChatMessageList](/docs/ui-kit/ios/message-list#date-time-formatter)
* [CometChatCallLogs](/docs/ui-kit/ios/call-logs#date-time-formatter)
* [CometChatMessageHeader](/docs/ui-kit/ios/message-header#date-time-formatter)

Each of these components checks the most relevant closure in `CometChatDateTimeFormatter` based on the timestamp and context.

The `CometChatDateTimeFormatter` gives developers fine-grained control over how date and time appear throughout their app. Whether you're customizing for locale, branding, or clarity, this system ensures your app's time formatting is as user-friendly and context-aware as possible.

***

## Next Steps

<CardGroup>
  <Card title="Theme Introduction" href="/ui-kit/ios/theme-introduction">
    Customize the visual appearance of UI components
  </Card>

  <Card title="Color Resources" href="/ui-kit/ios/color-resources">
    Configure color schemes for your app
  </Card>

  <Card title="Component Styling" href="/ui-kit/ios/component-styling">
    Apply custom styles to individual components
  </Card>
</CardGroup>


# Message Bubble Styling
Source: https://www.cometchat.com/docs/ui-kit/ios/message-bubble-styling

Customize CometChat iOS UI Kit message bubbles with incoming and outgoing styles, borders, corner radius, and per-message-type styling.

<Accordion title="AI Integration Quick Reference">
  | Field             | Value                                                                                                                                                                                        |
  | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Platform          | iOS UI Kit                                                                                                                                                                                   |
  | Incoming Style    | `CometChatMessageBubble.style.incoming`                                                                                                                                                      |
  | Outgoing Style    | `CometChatMessageBubble.style.outgoing`                                                                                                                                                      |
  | Global Properties | `backgroundColor`, `borderWidth`, `borderColor`, `cornerRadius`                                                                                                                              |
  | Bubble Types      | `textBubbleStyle`, `imageBubbleStyle`, `videoBubbleStyle`, `audioBubbleStyle`, `fileBubbleStyle`, `pollBubbleStyle`, `linkPreviewBubbleStyle`, `deleteBubbleStyle`, `aiAssistantBubbleStyle` |
  | Action Bubble     | `CometChatMessageBubble.actionBubbleStyle`                                                                                                                                                   |
</Accordion>

## Overview

The MessageBubble styling API allows developers to customize the appearance of incoming and outgoing message bubbles globally or at the component level. This includes various message types such as text, image, video, audio, file, and document bubbles.

There are two primary classes for styling message bubbles:

* **CometChat Incoming Message Bubble Style**
* **CometChat Outgoing Message Bubble Style**

Both classes provide properties for customizing background color, border, corner radius, and specific styles for individual message types.

***

## Properties

### Global Styling (Static Variables)

| Property               | Description                                 |
| ---------------------- | ------------------------------------------- |
| **backgroundColor**    | The background color for message bubbles    |
| **backgroundDrawable** | A background image for message bubbles      |
| **borderWidth**        | The width of the border for message bubbles |
| **borderColor**        | The color of the border for message bubbles |
| **cornerRadius**       | The corner radius for message bubbles       |

### Specific Message Type Styles

| Property                | Description                        |
| ----------------------- | ---------------------------------- |
| **textBubbleStyle**     | Style for text message bubbles     |
| **imageBubbleStyle**    | Style for image message bubbles    |
| **videoBubbleStyle**    | Style for video message bubbles    |
| **audioBubbleStyle**    | Style for audio message bubbles    |
| **fileBubbleStyle**     | Style for file message bubbles     |
| **documentBubbleStyle** | Style for document message bubbles |

***

## Customization Examples

### Customizing Incoming Message Bubble

The following code snippet shows how to customize the incoming message bubble style:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Customize incoming message bubble appearance
    CometChatMessageBubble.style.incoming.backgroundColor = UIColor(hexString: "#F76808")
    CometChatMessageBubble.style.incoming.borderWidth = 2
    CometChatMessageBubble.style.incoming.borderColor = UIColor.black
    ```
  </Tab>
</Tabs>

### Customizing Outgoing Message Bubble

The following code snippet shows how to customize the outgoing message bubble style:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Customize outgoing message bubble appearance
    CometChatMessageBubble.style.outgoing.backgroundColor = UIColor(hexString: "#F76808")
    CometChatMessageBubble.style.outgoing.borderWidth = 2
    CometChatMessageBubble.style.outgoing.borderColor = UIColor.black
    ```
  </Tab>
</Tabs>

***

## Text Bubble

Text bubbles display plain text messages, which are the most common message type.

The following code snippet shows how to customize the text message bubble:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Customize text bubble for incoming messages
    CometChatMessageBubble.style.incoming.textBubbleStyle.backgroundColor = UIColor(hexString: "#FEEDE1")

    // Customize text bubble for outgoing messages
    CometChatMessageBubble.style.outgoing.textBubbleStyle.backgroundColor = UIColor(hexString: "#F76808")
    ```
  </Tab>
</Tabs>

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

***

## Image Bubble

Image bubbles display messages with images.

The following code snippet shows how to customize the image message bubble:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Customize image bubble for incoming messages
    CometChatMessageBubble.style.incoming.imageBubbleStyle.backgroundColor = UIColor(hexString: "#FEEDE1")

    // Customize image bubble for outgoing messages
    CometChatMessageBubble.style.outgoing.imageBubbleStyle.backgroundColor = UIColor(hexString: "#F76808")
    ```
  </Tab>
</Tabs>

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

***

## Video Bubble

Video bubbles display messages with video clips.

The following code snippet shows how to customize the video message bubble:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Customize video bubble for incoming messages
    CometChatMessageBubble.style.incoming.videoBubbleStyle.backgroundColor = UIColor(hexString: "#FEEDE1")
    CometChatMessageBubble.style.incoming.videoBubbleStyle.playButtonTint = UIColor(hexString: "#F76808")

    // Customize video bubble for outgoing messages
    CometChatMessageBubble.style.outgoing.deleteBubbleStyle.backgroundColor = UIColor(hexString: "#F76808")
    CometChatMessageBubble.style.outgoing.videoBubbleStyle.playButtonTint = UIColor(hexString: "#F76808")
    ```
  </Tab>
</Tabs>

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

***

## Audio Bubble

Audio bubbles display audio messages.

The following code snippet shows how to customize the audio message bubble:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Customize audio bubble for incoming messages
    CometChatMessageBubble.style.incoming.audioBubbleStyle.audioWaveFormTintColor = UIColor(hexString: "#F76808")
    CometChatMessageBubble.style.incoming.audioBubbleStyle.playImageTintColor = UIColor(hexString: "#F76808")
    CometChatMessageBubble.style.incoming.audioBubbleStyle.backgroundColor = UIColor(hexString: "#FEEDE1")

    // Customize audio bubble for outgoing messages
    CometChatMessageBubble.style.outgoing.audioBubbleStyle.playImageTintColor = UIColor(hexString: "#F76808")
    CometChatMessageBubble.style.outgoing.audioBubbleStyle.backgroundColor = UIColor(hexString: "#F76808")
    ```
  </Tab>
</Tabs>

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

***

## Media Grid Bubble

Media grid bubbles render messages that carry **multiple image or video attachments** as a count-based grid (1, 2, 3, 4, or 5+ tiles). When there are more items than visible tiles, the last tile shows a "+N" overflow badge; video tiles carry a play badge and duration pill. Tapping any tile opens the fullscreen media viewer with swipe navigation, pinch-to-zoom, inline video playback, per-photo download, and share.

<Frame>
  <img alt="Media grid bubbles rendering multiple image attachments as a 2x2 grid with a +4 overflow badge on the last tile, shown for both incoming and outgoing messages" />
</Frame>

<Frame>
  <img alt="Media grid bubbles rendering multiple video attachments with play badges on each tile and a +3 overflow badge on the last tile, shown for both incoming and outgoing messages" />
</Frame>

Grid layout and colors come from `GalleryBubbleStyle`:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    var style = GalleryBubbleStyle()
    style.gridSpacing = 4
    style.tileCornerRadius = 8
    style.overflowOverlayColor = UIColor.black.withAlphaComponent(0.6)
    style.playIconTint = .white
    ```
  </Tab>
</Tabs>

Key `GalleryBubbleStyle` properties for the grid:

| Property                                   | Type                 | Description                                                                                                                                         |
| ------------------------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bubbleWidth`                              | `CGFloat`            | Content width of the media grid — screen-relative (≈62% of screen width, clamped 210–300) so the bubble keeps its proportion across iPhone and iPad |
| `gridSpacing`                              | `CGFloat`            | Gap between tiles                                                                                                                                   |
| `containerCornerRadius`                    | `CGFloat`            | Corner radius of the whole grid container                                                                                                           |
| `tileCornerRadius`                         | `CGFloat`            | Corner radius of each media tile                                                                                                                    |
| `singleAspectRatio`                        | `CGFloat`            | Height/width ratio when a single item is shown full width                                                                                           |
| `placeholderColor`                         | `UIColor`            | Shown while a tile's media loads                                                                                                                    |
| `overflowOverlayColor`                     | `UIColor`            | Dark scrim over the last tile when items overflow                                                                                                   |
| `overflowTextColor` / `overflowTextFont`   | `UIColor` / `UIFont` | The "+N" overflow label                                                                                                                             |
| `playIconTint` / `playIconBackgroundColor` | `UIColor`            | The play badge on video tiles                                                                                                                       |

***

## Audio Files Bubble

Audio files bubbles render messages carrying **audio file attachments** — one playback row per file, with a play/pause button, a seekable progress slider, the duration, the file name, and a download control. Only one row plays at a time.

<Frame>
  <img alt="Audio files bubble stacking multiple audio playback rows, each with a play button, seekable progress slider, duration and file name, plus a Show 2 more toggle, shown for both incoming and outgoing messages" />
</Frame>

<Note>
  This bubble is distinct from the [Audio Bubble](#audio-bubble) above, which renders **voice notes** recorded with the composer's microphone. Voice notes keep their waveform look and are never grouped with other attachments.
</Note>

Audio rows share the caption and section styling of `GalleryBubbleStyle` (`sectionSpacing`, `captionFont`, `captionColor`), and flip their colors automatically on outgoing bubbles.

***

## Files Bubble

Files bubbles render messages carrying **document attachments** as a connected stack of file cards — each with a file-type icon (PDF, Word, Excel, PowerPoint, ZIP, …), the file name, and its metadata. Four or more files collapse behind a "+N more" toggle. Tapping a card opens the file: a downloaded copy previews in-app, otherwise the file is offered through the share sheet.

<Frame>
  <img alt="Files bubble showing a connected stack of document cards, each with a file-type icon, name, size and download control, plus a Show 2 more toggle, shown for both incoming and outgoing messages" />
</Frame>

File card styling comes from `GalleryBubbleStyle`:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    var style = GalleryBubbleStyle()
    style.fileCardBackgroundColor = UIColor(hexString: "#FEEDE1")
    style.fileNameFont = .systemFont(ofSize: 15, weight: .semibold)
    style.expandButtonColor = UIColor(hexString: "#F76808")
    ```
  </Tab>
</Tabs>

Key `GalleryBubbleStyle` properties for file cards and the shared caption row:

| Property                                 | Type                 | Description                                                       |
| ---------------------------------------- | -------------------- | ----------------------------------------------------------------- |
| `fileCardBackgroundColor`                | `UIColor`            | Background of each file card                                      |
| `fileCardSpacing`                        | `CGFloat`            | Gap between cards in the stack                                    |
| `fileIconTint`                           | `UIColor`            | Tint of the file-type icon                                        |
| `fileNameFont` / `fileNameColor`         | `UIFont` / `UIColor` | File name text                                                    |
| `fileMetaFont` / `fileMetaColor`         | `UIFont` / `UIColor` | File size/type metadata text                                      |
| `expandButtonFont` / `expandButtonColor` | `UIFont` / `UIColor` | The "+N more" / "Show less" toggle                                |
| `sectionSpacing`                         | `CGFloat`            | Vertical spacing between media, audio, files and caption sections |
| `captionFont` / `captionColor`           | `UIFont` / `UIColor` | The shared caption row under the attachments                      |
| `captionDividerColor`                    | `UIColor`            | The divider line above the caption                                |

<Note>
  Captions containing rich text (code blocks, quote blocks, inline code) render through the same pipeline as [Text Bubbles](#text-bubble), so their formatting looks identical across message types.
</Note>

***

## Poll Bubble

Poll bubbles display messages with polling options.

The following code snippet shows how to customize the poll message bubble:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Customize poll bubble for incoming messages
    CometChatMessageBubble.style.incoming.pollBubbleStyle.optionProgressTintColor = UIColor(hexString: "#F76808")
    CometChatMessageBubble.style.incoming.pollBubbleStyle.selectedPollImageTint = UIColor(hexString: "#F76808")
    CometChatMessageBubble.style.incoming.pollBubbleStyle.backgroundColor = UIColor(hexString: "#FEEDE1")

    // Customize poll bubble for outgoing messages
    CometChatMessageBubble.style.outgoing.pollBubbleStyle.backgroundColor = UIColor(hexString: "#F76808")
    ```
  </Tab>
</Tabs>

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

***

## Link Preview Bubble

The Link Preview Bubble displays a preview of links shared in messages. It enriches the messaging experience by showing details such as the page title, description, and an image from the linked content, making links more engaging and informative.

The following code snippet shows how to customize the link preview message bubble:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Customize link preview bubble for incoming messages
    CometChatMessageBubble.style.incoming.linkPreviewBubbleStyle.backgroundColor = UIColor(hexString: "#FEEDE1")

    // Customize link preview bubble for outgoing messages
    CometChatMessageBubble.style.outgoing.linkPreviewBubbleStyle.backgroundColor = UIColor(hexString: "#F76808")
    ```
  </Tab>
</Tabs>

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

***

## Action Bubble

Action bubbles provide a customizable interface for displaying a variety of actions, such as group actions, within a chat.

The following code snippet shows how to customize the action message bubble:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Customize action bubble appearance
    CometChatMessageBubble.actionBubbleStyle.backgroundColor = UIColor(hexString: "#FEEDE1")
    CometChatMessageBubble.actionBubbleStyle.bubbleTextColor = UIColor(hexString: "#F76808")
    CometChatMessageBubble.actionBubbleStyle.borderColor = UIColor(hexString: "#F76808")
    ```
  </Tab>
</Tabs>

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

***

## Delete Bubble

Delete bubbles display messages that have been deleted by the sender. These indicate the message removal within the chat interface.

The following code snippet shows how to customize the delete message bubble:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Customize delete bubble for incoming messages
    CometChatMessageBubble.style.incoming.deleteBubbleStyle.backgroundColor = UIColor(hexString: "#FEEDE1")

    // Customize delete bubble for outgoing messages
    CometChatMessageBubble.style.outgoing.deleteBubbleStyle.backgroundColor = UIColor(hexString: "#F76808")
    ```
  </Tab>
</Tabs>

**Default**

<Frame>
  <img />
</Frame>

**Customization**

<Frame>
  <img />
</Frame>

***

## AI Assistant Bubble

The AI Assistant Bubble displays responses or messages sent by the AI assistant within the chat interface. These bubbles are designed to visually distinguish AI-generated messages from user messages, maintaining a clear and intuitive conversation flow.

You can customize the appearance of the AI Assistant message bubble to match your app's theme — including background color, text color, font, and border styling.

The following code snippet shows how to customize the AI Assistant message bubble:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Customize AI assistant bubble for incoming messages
    CometChatMessageBubble.style.incoming.aiAssistantBubbleStyle.backgroundColor = UIColor(hexString: "#FEEDE1")

    // Customize AI assistant bubble for outgoing messages
    CometChatMessageBubble.style.outgoing.aiAssistantBubbleStyle.backgroundColor = UIColor(hexString: "#F76808")
    ```
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup>
  <Card title="Message List" href="/ui-kit/ios/message-list">
    Display and customize the message list component
  </Card>

  <Card title="Message Composer" href="/ui-kit/ios/message-composer">
    Customize the message input component
  </Card>

  <Card title="Component Styling" href="/ui-kit/ios/component-styling">
    Learn about global styling options
  </Card>
</CardGroup>


# CometChat UI Kit For iOS
Source: https://www.cometchat.com/docs/ui-kit/ios/overview

Integrate chat functionality into iOS applications with prebuilt, modular, and customizable UI components

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "platform": "iOS UI Kit",
    "package": "CometChatUIKitSwift",
    "version": "5.1.9",
    "description": "Pre-built UI components for iOS chat applications using SwiftUI",
    "metadata": {
      "peerDependencies": {
        "CometChatSDK": ">= 4.0.0"
      },
      "supportedPlatforms": ["iOS 13.0+", "iPadOS 13.0+", "Mac Catalyst 13.0+"],
      "language": "Swift 5.0+",
      "license": "MIT"
    },
    "quickLinks": {
      "documentation": "https://www.cometchat.com/docs/ui-kit/ios/overview",
      "repository": "https://github.com/cometchat/cometchat-uikit-ios",
      "demo": "https://demo.cometchat.com"
    }
  }
  ```
</Accordion>

| Property          | Value                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------- |
| Package           | CometChatUIKitSwift                                                                   |
| Version           | 5.1.9                                                                                 |
| Peer Dependencies | CometChatSDK >= 4.0.0                                                                 |
| Platforms         | iOS 13.0+, iPadOS 13.0+, Mac Catalyst 13.0+                                           |
| Language          | Swift 5.0+                                                                            |
| AI Skills         | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills) |
| License           | MIT                                                                                   |

***

## Introduction

The CometChat UI Kit for iOS provides a seamless solution to integrate chat functionality into your iOS applications. With prebuilt, modular, and customizable UI components, it accelerates development and ensures your chat application is robust, scalable, and tailored to your needs.

### Key Features

* Effortless Integration: Ready-to-use SwiftUI components for rapid implementation
* Highly Customizable: Adapt UI components to match your brand and user experience requirements
* Built on Core SDK: Leverages the powerful [CometChat iOS SDK](/docs/sdk/ios/overview) for reliable performance
* Scalable & Reliable: Optimized for enterprise-grade applications

***

## Integrate with AI Coding Agents

Use [CometChat Skills](https://github.com/cometchat/cometchat-skills) to add chat to any iOS project through your AI coding agent. The skill takes an AI-first approach — your agent has a short conversation with you to understand your project and chat requirements, then writes production-grade integration code tailored to the files you already have.

Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [30+ more agents](https://github.com/cometchat/cometchat-skills).

```bash theme={null}
npx @cometchat/skills add
```

Use `--ide <name>` to target a specific IDE (e.g. `--ide cursor`), or `--ide all` to install for all supported IDEs.

Then in your IDE:

```
/cometchat add chat to my app
```

The skill detects your iOS project structure, navigation pattern, and existing auth system. It onboards you to CometChat directly in the terminal — signup, login, and app creation all via the CLI. It reads your view controllers, navigation, and components before proposing a placement, shows the plan (which files it will create, modify, and leave untouched), and waits for your approval before writing code. Credentials are saved via `Secrets.swift` or `.xcconfig`.

After the first integration, re-run `/cometchat` anytime to pick from the iteration menu:

* **Customize look & feel** — theme presets (slack / whatsapp / imessage / discord / notion) or your own brand color
* **Add a feature** — 40+ features including calls, reactions, polls, AI smart replies, file sharing, presence
* **Customize a component** — custom message bubbles, headers, composer actions, empty/loading states
* **Set up production auth** — replace the dev Auth Key with a server-side token endpoint
* **Set up user management** — server endpoints for creating/updating/deleting CometChat users
* **Run diagnostics** — verify, drift detection, symptom-to-cause lookup

***

## Try It

<CardGroup>
  <Card title="Demo App" icon="play" href="https://link.cometchat.com/ios-demo-app">
    Experience the UI Kit in action with our interactive demo
  </Card>

  <Card title="Sample App" icon="github" href="https://github.com/cometchat/cometchat-uikit-ios">
    Explore the complete source code on GitHub
  </Card>
</CardGroup>

***

## Get Started

Before integrating the CometChat UI Kit, familiarize yourself with the key concepts and features offered by CometChat's platform:

* Review the [Key Concepts](/docs/fundamentals/key-concepts) to understand essential terminology and features
* Follow the [Getting Started Guide](/docs/ui-kit/ios/getting-started) for detailed steps on initial setup and integration

<Frame>
  <img />
</Frame>

***

## Explore

<CardGroup>
  <Card title="Components" icon="puzzle-piece" href="/ui-kit/ios/components-overview">
    Pre-built UI components for conversations, messages, users, and groups
  </Card>

  <Card title="Features" icon="sparkles" href="/ui-kit/ios/core-features">
    Core messaging, calling, and AI-powered features
  </Card>

  <Card title="Theming" icon="palette" href="/ui-kit/ios/theme-introduction">
    Customize colors, typography, and styling to match your brand
  </Card>

  <Card title="Integration" icon="plug" href="/ui-kit/ios/getting-started">
    Step-by-step guides for integrating the UI Kit
  </Card>

  <Card title="API Reference" icon="code" href="/sdk/ios/overview">
    Complete SDK documentation and API details
  </Card>

  <Card title="Guides" icon="book" href="/ui-kit/ios/guide-overview">
    Tutorials and how-to guides for common use cases
  </Card>
</CardGroup>

***

## Resources

<CardGroup>
  <Card title="Demo App" icon="play" href="https://link.cometchat.com/ios-demo-app">
    Try the interactive demo on your iOS device
  </Card>

  <Card title="Sample App" icon="github" href="https://github.com/cometchat/cometchat-uikit-ios">
    Complete sample application source code
  </Card>

  <Card title="Integration Guides" icon="rocket" href="/ui-kit/ios/getting-started">
    Step-by-step integration tutorials
  </Card>

  <Card title="Components" icon="puzzle-piece" href="/ui-kit/ios/components-overview">
    Browse all available UI components
  </Card>

  <Card title="Features" icon="sparkles" href="/ui-kit/ios/core-features">
    Explore messaging, calling, and AI features
  </Card>

  <Card title="Theming" icon="palette" href="/ui-kit/ios/theme-introduction">
    Customize the look and feel
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/ios/troubleshooting">
    Common issues and solutions
  </Card>

  <Card title="Support" icon="headset" href="https://help.cometchat.com/hc/en-us/requests/new">
    Get help from our support team
  </Card>
</CardGroup>

***


# Sound Manager
Source: https://www.cometchat.com/docs/ui-kit/ios/sound-manager

Manage CometChat iOS UI Kit sounds for incoming and outgoing messages, calls, custom audio files, playback, and pause controls.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                    |
  | ------------ | ------------------------------------------------------------------------ |
  | Platform     | iOS UI Kit                                                               |
  | Class        | `CometChatSoundManager`                                                  |
  | Purpose      | Manages audio playback for messages and calls                            |
  | Play Method  | `play(sound: Sound, customSound: URL?)`                                  |
  | Pause Method | `pause()`                                                                |
  | Sound Types  | `.incomingMessage`, `.outgoingMessage`, `.incomingCall`, `.outgoingCall` |
  | Custom Sound | Pass `URL` to override default sounds                                    |
</Accordion>

## Overview

`CometChatSoundManager` is a helper class that manages audio playback in the CometChat UI Kit. It handles sound events for incoming and outgoing messages and calls, supporting both default sounds and custom audio files.

***

## Methods

### Play Sound

The `play(sound:customSound:)` method triggers audio playback based on user interactions with the chat interface. If no custom sound file is provided, the default sound for that event type is played.

```swift lines theme={null}
play(sound: Sound, customSound: URL?)
```

| Parameter   | Type  | Description                                                                                              |
| ----------- | ----- | -------------------------------------------------------------------------------------------------------- |
| sound       | Sound | The type of sound event (e.g., `.incomingMessage`, `.outgoingMessage`, `.incomingCall`, `.outgoingCall`) |
| customSound | URL?  | Optional URL to a custom sound file. If `nil`, the default sound is used.                                |

### Pause Sound

The `pause()` method stops any sound currently being played by the SoundManager.

```swift lines theme={null}
pause()
```

***

## Usage

### Playing Default Sounds

Play the default sound for an incoming message:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Play the default incoming message sound
    CometChatSoundManager().play(sound: .incomingMessage)
    ```
  </Tab>
</Tabs>

### Playing Custom Sounds

Provide a custom audio file URL to override the default sound:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Play a custom sound for incoming messages
    if let customSoundURL = Bundle.main.url(forResource: "customSound", withExtension: "wav") {
        CometChatSoundManager().play(sound: .incomingMessage, customSound: customSoundURL)
    }
    ```
  </Tab>
</Tabs>

### Pausing Sounds

Stop any currently playing sound:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Pause the currently playing sound
    CometChatSoundManager().pause()
    ```
  </Tab>
</Tabs>

***

## Sound Types

The `Sound` enum provides the following options:

| Sound Type         | Description                              |
| ------------------ | ---------------------------------------- |
| `.incomingMessage` | Played when a new message is received    |
| `.outgoingMessage` | Played when a message is sent            |
| `.incomingCall`    | Played when an incoming call is received |
| `.outgoingCall`    | Played when initiating an outgoing call  |

***

By using `CometChatSoundManager`, you can enhance the user experience in your chat application by integrating audible cues for chat interactions.

***

## Next Steps

<CardGroup>
  <Card title="Theme Introduction" href="/ui-kit/ios/theme-introduction">
    Customize the visual appearance
  </Card>

  <Card title="Localization" href="/ui-kit/ios/localize">
    Adapt to different languages
  </Card>

  <Card title="Component Styling" href="/ui-kit/ios/component-styling">
    Style individual components
  </Card>
</CardGroup>


# Introduction
Source: https://www.cometchat.com/docs/ui-kit/ios/theme-introduction

Customize CometChat iOS UI Kit themes with global colors, typography, spacing, component styles, branding, and light or dark mode.

<Accordion title="AI Integration Quick Reference">
  | Field                 | Value                                                                        |
  | --------------------- | ---------------------------------------------------------------------------- |
  | Platform              | iOS UI Kit                                                                   |
  | Package               | `CometChatUIKitSwift`                                                        |
  | Theme Class           | `CometChatTheme` — Global theming system for all CometChat components        |
  | Primary Color         | `CometChatTheme.primaryColor = UIColor`                                      |
  | Background Colors     | `CometChatTheme.backgroundColor01`, `backgroundColor02`, `backgroundColor03` |
  | Border Colors         | `CometChatTheme.borderColorDefault`, `borderColorLight`, `borderColorDark`   |
  | Typography Class      | `CometChatTypography`                                                        |
  | Typography Properties | `Body.regular`, `Body.bold`, `Heading.regular`                               |
  | Apply Timing          | Set theme before `CometChatUIKit.init()`                                     |
  | Example               | `CometChatTheme.primaryColor = UIColor(hex: "#F76808")`                      |
</Accordion>

## Overview

Theming in CometChat for iOS allows you to create visually consistent and customizable user interfaces that align with your application's branding. The `CometChatTheme` system enables global theming, customization of colors, typography, spacing, and component-specific styles to enhance the user experience across all CometChat components.

With global styles and an easy-to-override architecture, you can seamlessly apply themes at both a global and component level.

***

## Using Theming in Your Project

### Global Theming

Set up the global theme for your application during app launch. This ensures all CometChat components use the specified theme.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatSDK

    @main
    class AppDelegate: UIResponder, UIApplicationDelegate {
        var window: UIWindow?

        func application(
            _ application: UIApplication,
            didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
        ) -> Bool {
            
            // Apply the global theme
            CometChatTheme.primaryColor = UIColor.systemBackground
            
            // Apply custom typography
            CometChatTypography.Body.regular = UIFont.systemFont(ofSize: 18, weight: .bold)
            
            return true
        }
    }
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

***

## Customization

### Customizing Colors

Override specific color attributes globally in `CometChatTheme`. This is equivalent to overriding attributes in Android's `themes.xml`.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Set a custom primary color
    CometChatTheme.primaryColor = UIColor(hex: "#F76808")
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

***

## Next Steps

<CardGroup>
  <Card title="Color Resources" href="/ui-kit/ios/color-resources">
    Customize theme colors and dark mode
  </Card>

  <Card title="Component Styling" href="/ui-kit/ios/component-styling">
    Style individual components
  </Card>

  <Card title="Message Bubble Styling" href="/ui-kit/ios/message-bubble-styling">
    Customize message bubbles
  </Card>
</CardGroup>


# Changelog
Source: https://www.cometchat.com/docs/ui-kit/react-native/link/changelog

Navigate to Changelog documentation.



# AI Assistant Chat History
Source: https://www.cometchat.com/docs/ui-kit/ios/ai-assistant-chat-history

Complete guide to displaying AI assistant conversation history in iOS apps - production-ready code included

The `CometChatAIAssistanceChatHistory` component displays past conversations between users and AI assistants. Users can review previous AI interactions and start new conversations.

<Frame>
  <img />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatAIAssistanceChatHistory",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "description": "Displays past conversations between users and AI assistants",
    "inherits": "UIViewController",
    "primaryOutput": {
      "callback": "onItemClick",
      "type": "(AIConversation) -> Void"
    },
    "props": {
      "data": {
        "user": { "type": "User?", "default": "nil" },
        "group": { "type": "Group?", "default": "nil" }
      },
      "callbacks": {
        "onItemClick": "(AIConversation) -> Void",
        "onBack": "() -> Void",
        "onError": "(CometChatException) -> Void"
      }
    },
    "events": [],
    "sdkListeners": [],
    "compositionExample": {
      "description": "AIAssistanceChatHistory shows previous AI conversations for a user or group",
      "components": ["CometChatAIAssistanceChatHistory", "CometChatMessages"],
      "flow": "User opens AI history → selects conversation → views full AI chat"
    }
  }
  ```
</Accordion>

| Field     | Value                             |
| --------- | --------------------------------- |
| Component | `CometChatAIAssistantChatHistory` |
| Package   | `CometChatUIKitSwift`             |
| Inherits  | `UIViewController`                |

***

## Prerequisites

<Steps>
  <Step title="Install CometChat UI Kit">
    Add to your Podfile:

    ```ruby theme={null}
    pod 'CometChatUIKitSwift', '5.1.9'
    ```

    Run `pod install`
  </Step>

  <Step title="Enable AI Features">
    Go to [CometChat Dashboard](https://app.cometchat.com) → AI → Enable AI features
  </Step>

  <Step title="Initialize CometChat">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let uikitSettings = UIKitSettings()
        .set(appID: "YOUR_APP_ID")
        .set(authKey: "YOUR_AUTH_KEY")
        .set(region: "YOUR_REGION")
        .build()

    CometChatUIKit.init(uiKitSettings: uikitSettings) { result in
        switch result {
        case .success:
            CometChatUIKit.login(uid: "USER_ID") { _ in }
        case .failure(let error):
            print(error.localizedDescription)
        }
    }
    ```
  </Step>
</Steps>

***

## Basic Implementation

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK

    class ViewController: UIViewController {
        
        var user: CometChat.User!
        
        func showAIChatHistory() {
            let chatHistory = CometChatAIAssistanceChatHistory()
            chatHistory.user = user  // Required!
            
            navigationController?.pushViewController(chatHistory, animated: true)
        }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  You **must** set either `user` or `group`. Without this, only a loading indicator will display.
</Warning>

***

## Production-Ready Implementation

Complete implementation with all features:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK

    class AIAssistantViewController: UIViewController {
        
        // MARK: - Properties
        private var user: CometChat.User!
        private var chatHistoryComponent: CometChatAIAssistanceChatHistory!
        
        // MARK: - Initialization
        convenience init(user: CometChat.User) {
            self.init()
            self.user = user
        }
        
        // MARK: - Lifecycle
        override func viewDidLoad() {
            super.viewDidLoad()
            setupChatHistory()
        }
        
        // MARK: - Setup
        private func setupChatHistory() {
            chatHistoryComponent = CometChatAIAssistanceChatHistory()
            chatHistoryComponent.user = user
            
            // Configure callbacks
            setupCallbacks()
            
            // Configure styling
            setupStyling()
            
            // Configure date formatting
            setupDateFormatting()
            
            // Configure empty/error states
            setupStateViews()
            
            // Present
            navigationController?.pushViewController(chatHistoryComponent, animated: true)
        }
        
        // MARK: - Callbacks
        private func setupCallbacks() {
            // New chat button tapped
            chatHistoryComponent.onNewChatButtonClicked = { [weak self] user in
                self?.startNewAIChat()
            }
            
            // Message tapped
            chatHistoryComponent.onMessageClicked = { [weak self] message in
                self?.handleMessageTap(message)
            }
            
            // Data loaded successfully
            chatHistoryComponent.set(onLoad: { messages in
                print("✅ Loaded \(messages.count) AI messages")
            })
            
            // No data available
            chatHistoryComponent.set(onEmpty: { [weak self] in
                print("📭 No AI chat history")
            })
            
            // Error occurred
            chatHistoryComponent.set(onError: { [weak self] error in
                self?.showError(error.localizedDescription)
            })
        }
        
        // MARK: - Styling
        private func setupStyling() {
            let style = AiAssistantChatHistoryStyle()
            
            // Background
            style.backgroundColor = .systemBackground
            
            // Item text
            style.itemTextFont = UIFont.systemFont(ofSize: 16, weight: .medium)
            style.itemTextColor = .label
            
            // New chat button
            style.newChatTitleFont = UIFont.systemFont(ofSize: 18, weight: .bold)
            style.newChatTitleColor = .systemBlue
            
            chatHistoryComponent.style = style
        }
        
        // MARK: - Date Formatting
        private func setupDateFormatting() {
            // Today's messages
            chatHistoryComponent.dateTimeFormatter.today = { timestamp in
                let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
                let formatter = DateFormatter()
                formatter.timeStyle = .short
                return "Today at \(formatter.string(from: date))"
            }
            
            // Yesterday's messages
            chatHistoryComponent.dateTimeFormatter.yesterday = { timestamp in
                let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
                let formatter = DateFormatter()
                formatter.timeStyle = .short
                return "Yesterday at \(formatter.string(from: date))"
            }
            
            // Older messages
            chatHistoryComponent.dateTimeFormatter.otherDay = { timestamp in
                let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
                let formatter = DateFormatter()
                formatter.dateFormat = "MMM d, yyyy 'at' h:mm a"
                return formatter.string(from: date)
            }
        }
        
        // MARK: - State Views
        private func setupStateViews() {
            // Empty state text
            chatHistoryComponent.emptyStateText = "No AI conversations yet"
            chatHistoryComponent.emptyStateSubtitleText = "Tap 'New Chat' to start talking with AI"
            
            // Error state text
            chatHistoryComponent.errorStateText = "Couldn't load history"
            chatHistoryComponent.errorStateSubtitleText = "Please check your connection and try again"
        }
        
        // MARK: - Actions
        private func startNewAIChat() {
            // Option 1: Open messages view for new AI chat
            let messagesVC = CometChatMessages()
            messagesVC.user = user
            navigationController?.pushViewController(messagesVC, animated: true)
            
            // Option 2: Show action sheet with options
            // showNewChatOptions()
        }
        
        private func handleMessageTap(_ message: BaseMessage) {
            print("Tapped message ID: \(message.id)")
            print("Message text: \(message.text ?? "No text")")
            
            // Show message details or continue conversation
            let alert = UIAlertController(
                title: "Message",
                message: message.text,
                preferredStyle: .alert
            )
            alert.addAction(UIAlertAction(title: "Continue Chat", style: .default) { [weak self] _ in
                self?.continueChat(from: message)
            })
            alert.addAction(UIAlertAction(title: "Close", style: .cancel))
            present(alert, animated: true)
        }
        
        private func continueChat(from message: BaseMessage) {
            let messagesVC = CometChatMessages()
            messagesVC.user = user
            navigationController?.pushViewController(messagesVC, animated: true)
        }
        
        private func showError(_ message: String) {
            let alert = UIAlertController(
                title: "Error",
                message: message,
                preferredStyle: .alert
            )
            alert.addAction(UIAlertAction(title: "Retry", style: .default) { [weak self] _ in
                self?.setupChatHistory()
            })
            alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
            present(alert, animated: true)
        }
    }
    ```
  </Tab>
</Tabs>

***

## Custom Views

### Custom Loading View

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let chatHistory = CometChatAIAssistanceChatHistory()
    chatHistory.user = user

    // Custom loading indicator
    let loadingView = UIActivityIndicatorView(style: .large)
    loadingView.color = .systemBlue
    loadingView.startAnimating()

    chatHistory.set(loadingView: loadingView)
    ```
  </Tab>
</Tabs>

### Custom Empty State View

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift

    class CustomEmptyView: UIView {
        
        private let imageView: UIImageView = {
            let iv = UIImageView()
            iv.image = UIImage(systemName: "sparkles")
            iv.tintColor = .systemBlue
            iv.contentMode = .scaleAspectFit
            iv.translatesAutoresizingMaskIntoConstraints = false
            return iv
        }()
        
        private let titleLabel: UILabel = {
            let label = UILabel()
            label.text = "No AI Conversations"
            label.font = .systemFont(ofSize: 20, weight: .bold)
            label.textAlignment = .center
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
        
        private let subtitleLabel: UILabel = {
            let label = UILabel()
            label.text = "Start a conversation with AI to see it here"
            label.font = .systemFont(ofSize: 16)
            label.textColor = .secondaryLabel
            label.textAlignment = .center
            label.numberOfLines = 0
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
        
        let startChatButton: UIButton = {
            let button = UIButton(type: .system)
            button.setTitle("Start New Chat", for: .normal)
            button.titleLabel?.font = .systemFont(ofSize: 16, weight: .semibold)
            button.backgroundColor = .systemBlue
            button.setTitleColor(.white, for: .normal)
            button.layer.cornerRadius = 12
            button.translatesAutoresizingMaskIntoConstraints = false
            return button
        }()
        
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupUI()
        }
        
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
        
        private func setupUI() {
            addSubview(imageView)
            addSubview(titleLabel)
            addSubview(subtitleLabel)
            addSubview(startChatButton)
            
            NSLayoutConstraint.activate([
                imageView.centerXAnchor.constraint(equalTo: centerXAnchor),
                imageView.centerYAnchor.constraint(equalTo: centerYAnchor, constant: -80),
                imageView.widthAnchor.constraint(equalToConstant: 80),
                imageView.heightAnchor.constraint(equalToConstant: 80),
                
                titleLabel.topAnchor.constraint(equalTo: imageView.bottomAnchor, constant: 24),
                titleLabel.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 32),
                titleLabel.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -32),
                
                subtitleLabel.topAnchor.constraint(equalTo: titleLabel.bottomAnchor, constant: 8),
                subtitleLabel.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 32),
                subtitleLabel.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -32),
                
                startChatButton.topAnchor.constraint(equalTo: subtitleLabel.bottomAnchor, constant: 24),
                startChatButton.centerXAnchor.constraint(equalTo: centerXAnchor),
                startChatButton.widthAnchor.constraint(equalToConstant: 180),
                startChatButton.heightAnchor.constraint(equalToConstant: 48)
            ])
        }
    }

    // Usage
    let chatHistory = CometChatAIAssistanceChatHistory()
    chatHistory.user = user

    let emptyView = CustomEmptyView()
    emptyView.startChatButton.addTarget(self, action: #selector(startNewChat), for: .touchUpInside)

    chatHistory.set(emptyView: emptyView)
    ```
  </Tab>
</Tabs>

### Custom Error State View

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift

    class CustomErrorView: UIView {
        
        private let iconView: UIImageView = {
            let iv = UIImageView()
            iv.image = UIImage(systemName: "exclamationmark.triangle")
            iv.tintColor = .systemRed
            iv.contentMode = .scaleAspectFit
            iv.translatesAutoresizingMaskIntoConstraints = false
            return iv
        }()
        
        private let titleLabel: UILabel = {
            let label = UILabel()
            label.text = "Something went wrong"
            label.font = .systemFont(ofSize: 18, weight: .semibold)
            label.textAlignment = .center
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
        
        private let messageLabel: UILabel = {
            let label = UILabel()
            label.text = "We couldn't load your AI chat history.\nPlease check your connection."
            label.font = .systemFont(ofSize: 14)
            label.textColor = .secondaryLabel
            label.textAlignment = .center
            label.numberOfLines = 0
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
        
        let retryButton: UIButton = {
            let button = UIButton(type: .system)
            button.setTitle("Try Again", for: .normal)
            button.titleLabel?.font = .systemFont(ofSize: 16, weight: .medium)
            button.backgroundColor = .systemBlue
            button.setTitleColor(.white, for: .normal)
            button.layer.cornerRadius = 10
            button.translatesAutoresizingMaskIntoConstraints = false
            return button
        }()
        
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupUI()
        }
        
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
        
        private func setupUI() {
            addSubview(iconView)
            addSubview(titleLabel)
            addSubview(messageLabel)
            addSubview(retryButton)
            
            NSLayoutConstraint.activate([
                iconView.centerXAnchor.constraint(equalTo: centerXAnchor),
                iconView.centerYAnchor.constraint(equalTo: centerYAnchor, constant: -60),
                iconView.widthAnchor.constraint(equalToConstant: 60),
                iconView.heightAnchor.constraint(equalToConstant: 60),
                
                titleLabel.topAnchor.constraint(equalTo: iconView.bottomAnchor, constant: 16),
                titleLabel.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 24),
                titleLabel.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -24),
                
                messageLabel.topAnchor.constraint(equalTo: titleLabel.bottomAnchor, constant: 8),
                messageLabel.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 24),
                messageLabel.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -24),
                
                retryButton.topAnchor.constraint(equalTo: messageLabel.bottomAnchor, constant: 20),
                retryButton.centerXAnchor.constraint(equalTo: centerXAnchor),
                retryButton.widthAnchor.constraint(equalToConstant: 140),
                retryButton.heightAnchor.constraint(equalToConstant: 44)
            ])
        }
    }

    // Usage
    let chatHistory = CometChatAIAssistanceChatHistory()
    chatHistory.user = user

    let errorView = CustomErrorView()
    errorView.retryButton.addTarget(self, action: #selector(retryLoading), for: .touchUpInside)

    chatHistory.set(errorView: errorView)
    ```
  </Tab>
</Tabs>

***

## Filter Messages

Customize which messages are displayed:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatSDK
    import CometChatUIKitSwift

    let chatHistory = CometChatAIAssistanceChatHistory()
    chatHistory.user = user

    // Create custom message request builder
    let builder = MessagesRequest.MessageRequestBuilder()
        .set(uid: user.uid ?? "")
        .set(limit: 50)

    chatHistory.set(messagesRequestBuilder: builder)
    ```
  </Tab>
</Tabs>

<Note>
  These parameters are **always overridden** by the component:

  * `uid` / `guid`
  * `types`
  * `categories`
</Note>

***

## Embed in Your App

### As a Tab

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK

    class MainTabBarController: UITabBarController {
        
        var currentUser: CometChat.User!
        
        override func viewDidLoad() {
            super.viewDidLoad()
            fetchUserAndSetupTabs()
        }
        
        private func fetchUserAndSetupTabs() {
            // Get current logged in user
            guard let user = CometChat.getLoggedInUser() else { return }
            currentUser = user
            setupTabs()
        }
        
        private func setupTabs() {
            // Chats Tab
            let chatsVC = CometChatConversationsWithMessages()
            let chatsNav = UINavigationController(rootViewController: chatsVC)
            chatsNav.tabBarItem = UITabBarItem(
                title: "Chats",
                image: UIImage(systemName: "message"),
                selectedImage: UIImage(systemName: "message.fill")
            )
            
            // AI Assistant Tab
            let aiVC = CometChatAIAssistanceChatHistory()
            aiVC.user = currentUser
            aiVC.onNewChatButtonClicked = { [weak self] user in
                self?.startNewAIChat()
            }
            let aiNav = UINavigationController(rootViewController: aiVC)
            aiNav.tabBarItem = UITabBarItem(
                title: "AI Assistant",
                image: UIImage(systemName: "sparkles"),
                selectedImage: UIImage(systemName: "sparkles")
            )
            
            // Users Tab
            let usersVC = CometChatUsersWithMessages()
            let usersNav = UINavigationController(rootViewController: usersVC)
            usersNav.tabBarItem = UITabBarItem(
                title: "Users",
                image: UIImage(systemName: "person.2"),
                selectedImage: UIImage(systemName: "person.2.fill")
            )
            
            viewControllers = [chatsNav, aiNav, usersNav]
        }
        
        private func startNewAIChat() {
            let messagesVC = CometChatMessages()
            messagesVC.user = currentUser
            
            if let nav = selectedViewController as? UINavigationController {
                nav.pushViewController(messagesVC, animated: true)
            }
        }
    }
    ```
  </Tab>
</Tabs>

### As a Button Action

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK

    class ProfileViewController: UIViewController {
        
        var user: CometChat.User!
        
        private let aiHistoryButton: UIButton = {
            let button = UIButton(type: .system)
            button.setTitle("View AI Chat History", for: .normal)
            button.setImage(UIImage(systemName: "sparkles"), for: .normal)
            button.backgroundColor = .systemBlue
            button.tintColor = .white
            button.layer.cornerRadius = 12
            button.translatesAutoresizingMaskIntoConstraints = false
            return button
        }()
        
        override func viewDidLoad() {
            super.viewDidLoad()
            setupUI()
        }
        
        private func setupUI() {
            view.backgroundColor = .systemBackground
            view.addSubview(aiHistoryButton)
            
            NSLayoutConstraint.activate([
                aiHistoryButton.centerXAnchor.constraint(equalTo: view.centerXAnchor),
                aiHistoryButton.centerYAnchor.constraint(equalTo: view.centerYAnchor),
                aiHistoryButton.widthAnchor.constraint(equalToConstant: 250),
                aiHistoryButton.heightAnchor.constraint(equalToConstant: 50)
            ])
            
            aiHistoryButton.addTarget(self, action: #selector(showAIHistory), for: .touchUpInside)
        }
        
        @objc private func showAIHistory() {
            let chatHistory = CometChatAIAssistanceChatHistory()
            chatHistory.user = user
            
            chatHistory.onNewChatButtonClicked = { [weak self] selectedUser in
                let messagesVC = CometChatMessages()
                messagesVC.user = selectedUser
                self?.navigationController?.pushViewController(messagesVC, animated: true)
            }
            
            navigationController?.pushViewController(chatHistory, animated: true)
        }
    }
    ```
  </Tab>
</Tabs>

***

## API Reference

### Properties

| Property                 | Type                          | Required | Description               |
| ------------------------ | ----------------------------- | -------- | ------------------------- |
| `user`                   | `CometChat.User`              | Yes\*    | User for AI chat history  |
| `group`                  | `CometChat.Group`             | Yes\*    | Group for AI chat history |
| `style`                  | `AiAssistantChatHistoryStyle` | No       | Custom styling            |
| `emptyStateText`         | `String`                      | No       | Empty state title         |
| `emptyStateSubtitleText` | `String`                      | No       | Empty state subtitle      |
| `errorStateText`         | `String`                      | No       | Error state title         |
| `errorStateSubtitleText` | `String`                      | No       | Error state subtitle      |
| `hideDateSeparator`      | `Bool`                        | No       | Hide date separators      |
| `backButton`             | `UIButton`                    | No       | Custom back button        |

\*Either `user` or `group` is required

### Callbacks

| Method                   | Parameters                | Description            |
| ------------------------ | ------------------------- | ---------------------- |
| `onNewChatButtonClicked` | `(User) -> Void`          | New chat button tapped |
| `onMessageClicked`       | `(BaseMessage) -> Void`   | Message tapped         |
| `set(onLoad:)`           | `([BaseMessage]) -> Void` | Data loaded            |
| `set(onEmpty:)`          | `() -> Void`              | No data                |
| `set(onError:)`          | `(Error) -> Void`         | Error occurred         |

### Custom Views

| Method                         | Parameters               | Description         |
| ------------------------------ | ------------------------ | ------------------- |
| `set(loadingView:)`            | `UIView`                 | Custom loading view |
| `set(emptyView:)`              | `UIView`                 | Custom empty state  |
| `set(errorView:)`              | `UIView`                 | Custom error state  |
| `set(messagesRequestBuilder:)` | `MessagesRequestBuilder` | Filter messages     |

### Style Properties (AiAssistantChatHistoryStyle)

| Property            | Type      | Description           |
| ------------------- | --------- | --------------------- |
| `backgroundColor`   | `UIColor` | Background color      |
| `itemTextFont`      | `UIFont`  | Message text font     |
| `itemTextColor`     | `UIColor` | Message text color    |
| `newChatTitleFont`  | `UIFont`  | New chat button font  |
| `newChatTitleColor` | `UIColor` | New chat button color |

***

## Common Patterns

### Present AI Chat History from Profile

Show AI chat history when user taps a button in their profile:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    @objc func showAIChatHistory() {
        guard let currentUser = CometChat.getLoggedInUser() else { return }
        
        let chatHistory = CometChatAIAssistanceChatHistory()
        chatHistory.user = currentUser
        
        chatHistory.onNewChatButtonClicked = { [weak self] user in
            let messagesVC = CometChatMessages()
            messagesVC.user = user
            self?.navigationController?.pushViewController(messagesVC, animated: true)
        }
        
        navigationController?.pushViewController(chatHistory, animated: true)
    }
    ```
  </Tab>
</Tabs>

### Handle Message Selection from History

Navigate to the full conversation when a message is tapped:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let chatHistory = CometChatAIAssistanceChatHistory()
    chatHistory.user = user

    chatHistory.onMessageClicked = { [weak self] message in
        // Open the messages view to continue the conversation
        let messagesVC = CometChatMessages()
        messagesVC.user = self?.user
        self?.navigationController?.pushViewController(messagesVC, animated: true)
    }
    ```
  </Tab>
</Tabs>

### Custom Date Formatting for AI History

Format dates to show relative time for recent conversations:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let chatHistory = CometChatAIAssistanceChatHistory()
    chatHistory.user = user

    // Instance-level date formatting
    chatHistory.dateTimeFormatter.today = { timestamp in
        let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
        let formatter = DateFormatter()
        formatter.timeStyle = .short
        return "Today at \(formatter.string(from: date))"
    }

    chatHistory.dateTimeFormatter.yesterday = { timestamp in
        let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
        let formatter = DateFormatter()
        formatter.timeStyle = .short
        return "Yesterday at \(formatter.string(from: date))"
    }

    // Or use global-level formatting
    CometChatAIAssistanceChatHistory.dateTimeFormatter.otherDay = { timestamp in
        let formatter = DateFormatter()
        formatter.dateFormat = "MMM d, yyyy"
        return formatter.string(from: Date(timeIntervalSince1970: TimeInterval(timestamp)))
    }
    ```
  </Tab>
</Tabs>

### AI History as Tab in Main Navigation

Add AI chat history as a dedicated tab:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    class MainTabBarController: UITabBarController {
        
        override func viewDidLoad() {
            super.viewDidLoad()
            
            guard let currentUser = CometChat.getLoggedInUser() else { return }
            
            let aiHistory = CometChatAIAssistanceChatHistory()
            aiHistory.user = currentUser
            
            aiHistory.onNewChatButtonClicked = { [weak self] user in
                let messagesVC = CometChatMessages()
                messagesVC.user = user
                if let nav = self?.selectedViewController as? UINavigationController {
                    nav.pushViewController(messagesVC, animated: true)
                }
            }
            
            let aiNav = UINavigationController(rootViewController: aiHistory)
            aiNav.tabBarItem = UITabBarItem(
                title: "AI Assistant",
                image: UIImage(systemName: "sparkles"),
                selectedImage: UIImage(systemName: "sparkles")
            )
            
            viewControllers = [/* other tabs */, aiNav]
        }
    }
    ```
  </Tab>
</Tabs>

***

## Related

<CardGroup>
  <Card title="AI Features Overview" href="/ui-kit/ios/ai-features">
    All AI features
  </Card>

  <Card title="Message List" href="/ui-kit/ios/message-list">
    Chat message display
  </Card>

  <Card title="Message Composer" href="/ui-kit/ios/message-composer">
    Message input
  </Card>

  <Card title="Components Overview" href="/ui-kit/ios/components-overview">
    All components
  </Card>
</CardGroup>


# Call Buttons
Source: https://www.cometchat.com/docs/ui-kit/ios/call-buttons

Add CometChat iOS UI Kit call buttons for voice and video calls with user or group targets, click callbacks, and error handling.

The `CometChatCallButtons` component provides users with the ability to make calls, access call-related functionalities, and control call settings. Clicking this button typically triggers the call to be placed to the desired recipient.

<Frame>
  <img alt="CometChatCallButtons showing voice and video call buttons for initiating calls" />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatCallButtons",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "description": "Provides voice and video call buttons for initiating calls with users or groups",
    "inherits": "UIView",
    "primaryOutput": {
      "callback": "onVoiceCallClick",
      "type": "(User?, Group?) -> Void"
    },
    "props": {
      "data": {
        "user": { "type": "User?", "default": "nil" },
        "group": { "type": "Group?", "default": "nil" }
      },
      "callbacks": {
        "onVoiceCallClick": "(User?, Group?) -> Void",
        "onVideoCallClick": "(User?, Group?) -> Void",
        "onError": "(CometChatException) -> Void"
      },
      "visibility": {
        "hideVoiceCallButton": { "type": "Bool", "default": false },
        "hideVideoCallButton": { "type": "Bool", "default": false }
      }
    },
    "events": [
      { "name": "onOutgoingCallAccepted", "payload": "Call", "description": "Fires when outgoing call is accepted" },
      { "name": "onOutgoingCallRejected", "payload": "Call", "description": "Fires when outgoing call is rejected" }
    ],
    "sdkListeners": [],
    "compositionExample": {
      "description": "CallButtons is typically used in MessageHeader or as standalone call controls",
      "components": ["CometChatCallButtons", "CometChatOutgoingCall"],
      "flow": "User taps call button → OutgoingCall screen appears → Call connects or is rejected"
    }
  }
  ```
</Accordion>

| Field     | Value                  |
| --------- | ---------------------- |
| Component | `CometChatCallButtons` |
| Package   | `CometChatUIKitSwift`  |
| Inherits  | `UIView`               |

***

## Usage

### Integration

Since `CometChatCallButton` is a **custom view**, it offers flexibility in integration. It can be easily added to any view or embedded within other components, enhancing user interactions and providing seamless access to call functionalities.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let user =  User(uid: "your-uid", name: "")

    let cometChatCallButton = CometChatCallButtons(width: 24, height: 24)
    cometChatCallButton.set(user: user)
    container.addSubview(cometChatCallButton)
    ```
  </Tab>
</Tabs>

***

### Actions

[Actions](/docs/ui-kit/ios/components-overview#actions) dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the component to fit your specific needs.

##### 1. SetOnVoiceCallClick

The `setOnVoiceCallClick` action is usually invoked when a voice call is initiated, executing predefined actions. However, by utilizing the provided code snippet, you can effortlessly tailor or override this default behavior to suit your unique requirements.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let cometChatCallButton = CometChatCallButtons(width: 24, height: 24)
    .set(onVoiceCallClick: { user, group in
    //Perform Your Action
    })
    ```
  </Tab>
</Tabs>

##### 2. SetOnVideoCallClick

The `setOnVideoCallClick` action is typically triggered when a video call is initiated, executing default actions. However, with the provided code snippet, you have the flexibility to easily customize or override this default behavior according to your specific preferences or requirements.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let cometChatCallButton = CometChatCallButtons(width: 24, height: 24)
    .set(onVideoCallClick: { user, group in
    //Perform Your Action
      
    })
    ```
  </Tab>
</Tabs>

##### 3. SetOnError

You can customize this behavior by using the provided code snippet to override the `On Error` and improve error handling.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let cometChatCallButton = CometChatCallButtons(width: 24, height: 24)
        .set(onError: { error in
        //Perform Your Action

    })
    ```
  </Tab>
</Tabs>

***

### Filters

**Filters** allow you to customize the data displayed in a list within a Component. You can filter the list based on your specific criteria, allowing for a more customized. Filters can be applied using RequestBuilders of Chat SDK.

The CallButton component does not have any exposed filters.

***

### Events

[Events](/docs/ui-kit/ios/components-overview#events) are emitted by a `Component`. By using event you can extend existing functionality. Being global events, they can be applied in Multiple Locations and are capable of being Added or Removed.

Events emitted by the Call buttons component is as follows.

| Event                      | Description                                  |
| -------------------------- | -------------------------------------------- |
| **onOutgoingCallAccepted** | Triggers when the outgoing call is accepted. |
| **onOutgoingCallRejected** | Triggers when the outgoing call is rejected. |

<Tabs>
  <Tab title="Add Listener">
    ```swift lines theme={null}
    // View controller from your project where you want to listen events.
    public class ViewController: UIViewController {

       public override func viewDidLoad() {
            super.viewDidLoad()

           // Subscribing for the listener to listen events from user module
            CometChatCallEvents.addListener("UNIQUE_ID", self as CometChatCallEventListener)
        }

    }
     // Listener events from user module
    extension  ViewController: CometChatCallEventListener {

        func onOutgoingCallAccepted(call: Call) {
            // Do Stuff
        }

        func onOutgoingCallRejected(call: Call){
            // Do Stuff
        }

        func onCallEnded(call: Call) {
            // Do Stuff
        }
    }
    ```

    ```swift Emitting Group Events theme={null}
    //emit this when the other user accepts the call
    CometChatCallEvents.emitOnOutgoingCallAccepted(call: Call)

    //emit this when the other user rejects a call
    CometChatCallEvents.emitOnOutgoingCallRejected(call: Call)

    //emit this when logged in user cancels a call
    CometChatCallEvents.emitOnCallEnded(call: Call)
    ```
  </Tab>
</Tabs>

***

<Tabs>
  <Tab title="Remove Listener">
    ```swift View Controller theme={null}
    public override func viewWillDisappear(_ animated: Bool) {
          // Uncubscribing for the listener to listen events from user module
          CometChatCallEvents.removeListener("LISTENER_ID_USED_FOR_ADDING_THIS_LISTENER")
    }
    ```
  </Tab>
</Tabs>

***

## Customization

To fit your app's design requirements, you can customize the appearance of the conversation component. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.

### Style

Using Style you can customize the look and feel of the component in your app, These parameters typically control elements such as the color, size, shape, and fonts used within the component.

##### 1. CallButtons Style

You can customize the appearance of the `CallButtons` Component by applying the `CallButtonStyle` to it using the following code snippet.

**Global level styling**

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    CometChatCallButtons.style.audioCallButtonBackground = UIColor(hex: "#EDEAFA")
    CometChatCallButtons.style.audioCallIconTint = UIColor(hex: "#6852D6")
    CometChatCallButtons.style.videoCallButtonBackground = UIColor(hex: "#EDEAFA")
    CometChatCallButtons.style.videoCallIconTint = UIColor(hex: "#6852D6")
    ```
  </Tab>
</Tabs>

**Instance level styling**

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callButtonStyle = CallButtonStyle()
    callButtonStyle.audioCallButtonBackground = UIColor(hex: "#EDEAFA")
    callButtonStyle.audioCallIconTint = UIColor(hex: "#6852D6")
    callButtonStyle.videoCallButtonBackground = UIColor(hex: "#EDEAFA")
    callButtonStyle.videoCallIconTint = UIColor(hex: "#6852D6")
            
    let callButton = CometChatCallButtons(width: 10, height: 10)
    callButton.style = callButtonStyle
    ```
  </Tab>
</Tabs>

<Frame>
  <img alt="CometChatCallButtons with custom styling showing purple tinted call icons on light purple background" />
</Frame>

List of properties exposed by ButtonStyle

| **Property**                     | **Description**                             | **Code**                                                                          |
| -------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------- |
| **Video Call Icon Tint**         | Tint color for the video call icon.         | `CometChatCallButtons.style.videoCallIconTint = CometChatTheme.iconColorPrimary`  |
| **Video Call Text Font**         | Font for the video call button text.        | `CometChatCallButtons.style.videoCallTextFont = CometChatTypography.Body.regular` |
| **Video Call Text Color**        | Color for the video call button text.       | `CometChatCallButtons.style.videoCallTextColor = CometChatTheme.iconColorPrimary` |
| **Video Call Button Background** | Background color for the video call button. | `CometChatCallButtons.style.videoCallButtonBackground = .clear`                   |
| **Video Call Corner Radius**     | Corner radius for the video call button.    | `CometChatCallButtons.style.videoCallButtonCornerRadius = CometChatCornerStyle?`  |
| **Video Call Border Width**      | Border width for the video call button.     | `CometChatCallButtons.style.videoCallButtonBorder = 0`                            |
| **Video Call Border Color**      | Border color for the video call button.     | `CometChatCallButtons.style.videoCallButtonBorderColor = .clear`                  |
| **Video Call Icon**              | Icon for the video call button.             | `CometChatCallButtons.style.videoCallIcon = UIImage(systemName: "video")`         |
| **Audio Call Icon Tint**         | Tint color for the audio call icon.         | `CometChatCallButtons.style.audioCallIconTint = CometChatTheme.iconColorPrimary`  |
| **Audio Call Text Font**         | Font for the audio call button text.        | `CometChatCallButtons.style.audioCallTextFont = CometChatTypography.Body.regular` |
| **Audio Call Text Color**        | Color for the audio call button text.       | `CometChatCallButtons.style.audioCallTextColor = CometChatTheme.iconColorPrimary` |
| **Audio Call Button Background** | Background color for the audio call button. | `CometChatCallButtons.style.audioCallButtonBackground = .clear`                   |
| **Audio Call Corner Radius**     | Corner radius for the audio call button.    | `CometChatCallButtons.style.audioCallButtonCornerRadius = CometChatCornerStyle?`  |
| **Audio Call Border Width**      | Border width for the audio call button.     | `CometChatCallButtons.style.audioCallButtonBorder = 0`                            |
| **Audio Call Border Color**      | Border color for the audio call button.     | `CometChatCallButtons.style.audioCallButtonBorderColor = .clear`                  |
| **Audio Call Icon**              | Icon for the audio call button.             | `CometChatCallButtons.style.audioCallIcon = UIImage(systemName: "phone")`         |

***

### Functionality

These are a set of small functional customizations that allow you to fine-tune the overall experience of the component. With these, you can change text, set custom icons, and toggle the visibility of UI elements.

Below is a list of customizations along with corresponding code snippets

| Property                        | Description                                                          | Code                                                         |
| ------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ |
| hideVideoCallButton             | Hides the video call button                                          | `hideVoiceCallButton = true`                                 |
| hideVoiceCallButton             | Hides the voice call button                                          | `hideVoiceCallButton = true`                                 |
| set(user:User)                  | Sets the User object for CometChatCallButtons.                       | `.set(user:User)`                                            |
| set(group:Group)                | Sets the Group object for CometChatCallButtons.                      | `.set(group:Group)`                                          |
| set(outgoingCallConfiguration:) | Sets the configuration for outgoing calls.                           | `setOutgoingCallConfiguration(config)`                       |
| set(customSoundForCalls:)       | Sets a custom sound for incoming and outgoing calls.                 | `set(customSoundForCalls: URL)`                              |
| set(callSettingBuilder:)        | Function to build call settings based on call type and participants. | `.set(callSettingBuilder { callType, participants in ... })` |

### Advanced

For advanced-level customization, you can set custom views to the component. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your views, layouts, and UI elements and then incorporate those into the component.

The `Call Buttons` component does not provide additional functionalities beyond this level of customization.

***

## Configurations

[Configurations](/docs/ui-kit/ios/components-overview#configurations) offer the ability to customize the properties of each individual component within a Composite Component.

* `Configurations` expose properties that are available in its individual components.

***

#### Outgoing Call

You can customize the properties of the Outgoing Call component by making use of the `OutgoingCallConfiguration`. You can accomplish this by employing the `OutgoingCallConfiguration` as demonstrated below:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Create an object of  OutgoingCallConfiguration
    let outgoingCallConfiguration = OutgoingCallConfiguration()
    ```
  </Tab>
</Tabs>

All exposed properties of `OutgoingCallConfiguration` can be found under [Outgoing Call](/docs/ui-kit/ios/outgoing-call). Properties marked with the 🛑 symbol are not accessible within the Configuration Object.

**Example**

Let's say you want to change the style of the Outgoing Call subcomponent and, in addition, you only want to disable soundForCalls.

You can modify the style using the `OutgoingCallStyle` property, disable sound for calls using `.disable(soundForCalls: bool)` property.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let outgoingCallConfiguration = OutgoingCallConfiguration()
    .disable(soundForCalls: true)

    let cometChatCallButton = CometChatCallButtons(width: 24, height: 24)
    cometChatCallButton.set(outgoingCallConfiguration: outgoingCallConfiguration)
    cometChatCallButton.set(user: user)
    ```
  </Tab>
</Tabs>

***

<Note>
  To ensure that the `CallButtons` is properly configured, passing the controller is mandatory.

  * Swift

  ```swift lines theme={null}
  let callButtons = CometChatCallButtons(width: 24, height: 24)
  callButtons.set(controller: UIViewController) // Passing the controller is required
  ```
</Note>

***

## Props

All props are optional.

***

### user

The user for 1-on-1 call buttons. Pass either `user` or `group`, not both.

|         |         |
| ------- | ------- |
| Type    | `User?` |
| Default | `nil`   |

***

### group

The group for group call buttons. Pass either `user` or `group`, not both.

|         |          |
| ------- | -------- |
| Type    | `Group?` |
| Default | `nil`    |

***

### hideVoiceCallButton

Hides the voice call button.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

***

### hideVideoCallButton

Hides the video call button.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

***

### outgoingCallConfiguration

Configuration object for the internal `CometChatOutgoingCall` sub-component.

|         |                               |
| ------- | ----------------------------- |
| Type    | `OutgoingCallConfiguration`   |
| Default | `OutgoingCallConfiguration()` |

***

### customSoundForCalls

Custom sound file URL for calls.

|         |        |
| ------- | ------ |
| Type    | `URL?` |
| Default | `nil`  |

***

## Events

Events emitted by the Call Buttons component:

| Event                    | Description                                 |
| ------------------------ | ------------------------------------------- |
| `onOutgoingCallAccepted` | Triggers when the outgoing call is accepted |
| `onOutgoingCallRejected` | Triggers when the outgoing call is rejected |
| `onCallEnded`            | Triggers when the call ends                 |

***

## Common Patterns

### Add Call Buttons to Message Header

Integrate call buttons into a custom message header:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    class CustomMessageHeader: UIView {
        
        private var callButtons: CometChatCallButtons!
        
        func configure(with user: User) {
            callButtons = CometChatCallButtons(width: 24, height: 24)
            callButtons.set(user: user)
            callButtons.set(controller: parentViewController)
            
            // Add to header view
            addSubview(callButtons)
            // Set up constraints...
        }
    }
    ```
  </Tab>
</Tabs>

### Voice-Only Call Button

Show only the voice call button for audio-focused apps:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callButtons = CometChatCallButtons(width: 24, height: 24)
    callButtons.set(user: user)
    callButtons.hideVideoCallButton = true
    callButtons.set(controller: self)
    ```
  </Tab>
</Tabs>

### Custom Call Initiation with Confirmation

Show confirmation before starting a call:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callButtons = CometChatCallButtons(width: 24, height: 24)
    callButtons.set(user: user)
    callButtons.set(onVoiceCallClick: { [weak self] user, group in
        let alert = UIAlertController(
            title: "Start Voice Call",
            message: "Call \(user?.name ?? group?.name ?? "")?",
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
        alert.addAction(UIAlertAction(title: "Call", style: .default) { _ in
            // Initiate the call
            self?.initiateVoiceCall(to: user, group: group)
        })
        self?.present(alert, animated: true)
    })
    ```
  </Tab>
</Tabs>

### Group Video Call Button

Configure call buttons for group video calls:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callButtons = CometChatCallButtons(width: 24, height: 24)
    callButtons.set(group: group)
    callButtons.hideVoiceCallButton = true  // Groups often use video calls
    callButtons.set(controller: self)

    // Custom call settings for group calls
    callButtons.set(callSettingBuilder: { callType, participants in
        return CallSettingsBuilder()
            .setDefaultLayout(true)
            .setShowRecordingButton(true)
    })
    ```
  </Tab>
</Tabs>

***

## Related Components

<CardGroup>
  <Card title="Incoming Call" href="/ui-kit/ios/incoming-call">
    Display incoming call interface
  </Card>

  <Card title="Outgoing Call" href="/ui-kit/ios/outgoing-call">
    Display outgoing call interface
  </Card>

  <Card title="Call Logs" href="/ui-kit/ios/call-logs">
    Display call history
  </Card>
</CardGroup>

***


# Call Logs
Source: https://www.cometchat.com/docs/ui-kit/ios/call-logs

Display CometChat iOS UI Kit call logs with call type, duration, participants, timestamps, request builders, and selection callbacks.

The `CometChatCallLogs` component shows the list of call logs available. By default, names are shown for all listed users, along with their avatar if available.

<Frame>
  <img alt="CometChatCallLogs showing a list of call history with caller names, call types, and timestamps" />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatCallLogs",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatCallsSDK",
    "description": "Displays a list of call logs with call type, duration, and participant information",
    "inherits": "UIViewController",
    "primaryOutput": {
      "callback": "onItemClick",
      "type": "(Any) -> Void",
      "note": "CallLog is passed as Any type, cast to CometChatCallsSDK.CallLog"
    },
    "props": {
      "data": {
        "callRequestBuilder": { "type": "CallLogsRequest.CallLogsBuilder?", "default": "nil" }
      },
      "callbacks": {
        "onItemClick": "(Any) -> Void",
        "onItemLongClick": "(Any, IndexPath) -> Void",
        "onBack": "() -> Void",
        "onError": "(Any) -> Void",
        "onEmpty": "() -> Void",
        "onLoad": "([Any]) -> Void"
      },
      "visibility": {
        "hideError": { "type": "Bool", "default": false },
        "hideNavigationBar": { "type": "Bool", "default": false },
        "hideLoadingState": { "type": "Bool", "default": false },
        "hideBackIcon": { "type": "Bool", "default": false }
      },
      "viewSlots": {
        "listItemView": "(Any) -> UIView",
        "titleView": "(Any) -> UIView",
        "leadingView": "(Any) -> UIView",
        "trailView": "(Any) -> UIView"
      }
    },
    "events": [],
    "sdkListeners": [],
    "compositionExample": {
      "description": "CallLogs is typically used as a standalone screen or tab in the main navigation",
      "components": ["CometChatCallLogs", "CometChatCallLogDetails"],
      "flow": "User views call history → taps call log → sees call details or initiates callback"
    }
  }
  ```
</Accordion>

| Field     | Value                 |
| --------- | --------------------- |
| Component | `CometChatCallLogs`   |
| Package   | `CometChatUIKitSwift` |
| Inherits  | `UIViewController`    |

***

The `Call Logs` component is composed of the following BaseComponents:

| Components                                           | Description                                                                                                                                                                              |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [CometChatListBase](/docs/ui-kit/ios/components-overview) | `CometChatListBase` is a container component featuring a title, customizable background options, and a dedicated list view for seamless integration within your application's interface. |
| [CometChatListItem](/docs/ui-kit/ios/components-overview) | This component displays data retrieved from a CallLog object on a card, presenting a title and subtitle.                                                                                 |

***

## Usage

### Integration

`CometChatCallLogs` being a custom **view controller**, offers versatility in its integration. It can be seamlessly launched via button clicks or any user-triggered action, enhancing the overall user experience and facilitating smoother interactions within the application.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // To navigate to the CometChatCallLogs
    let callLogs = CometChatCallLogs()
    self.navigationController?.pushViewController(callLogs, animated: true)
    ```
  </Tab>
</Tabs>

### Actions

[Actions](/docs/ui-kit/ios/components-overview#actions) dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the component to fit your specific needs.

1. ##### set(onItemClick:)

`set(OnItemClick:)` is triggered when you click on a ListItem of the Conversations component. This `set(OnItemClick:)` method proves beneficial when a user intends to customize the on-click behavior in CometChatCallLogs.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // syntax for set(onItemClick: ((_ callLog: Any) -> ())?)
    // Note: callLog is of type CometChatCallsSDK.CallLog, cast it to access properties
    cometChatCallLogs.set(onItemClick: { callLog in
        // Override on item click
        guard let callLog = callLog as? CallLog else { return }
        // Access callLog properties
    })
    ```
  </Tab>
</Tabs>

***

2. ##### set(OnItemLongClick:)

`set(OnItemLongClick:)` is triggered when you long press on a ListItem of the Call logs component. This `set(OnItemLongClick:)` method proves beneficial when a user intends to additional functionality on long press on list item in CometChatCallLogs.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // syntax for set(onItemLongClick: ((_ callLog: Any, _ indexPath: IndexPath) -> ())?)
    // Note: callLog is of type CometChatCallsSDK.CallLog, cast it to access properties
    cometChatCallLogs.set(onItemLongClick: { callLog, indexPath in
        // Override on item long click
        guard let callLog = callLog as? CallLog else { return }
        // Access callLog properties
    })
    ```
  </Tab>
</Tabs>

***

##### 3. set(onBack:)

This `set(onBack:)` method becomes valuable when a user needs to override the action triggered upon pressing the back button in CometChatCallLogs.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatCallLogs.set(onBack: {
        // Override on back
    })
    ```
  </Tab>
</Tabs>

***

##### 4. set(onError:)

This method proves helpful when a user needs to customize the action taken upon encountering an error in CometChatCallLogs.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatCallLogs.set(onError: { error in
        // Override on error
    })
    ```
  </Tab>
</Tabs>

***

##### 5. set(onEmpty:)

This `set(onEmpty:)` method is triggered when the call logs list is empty in CometChatCallLogs.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatCallLogs.set(onEmpty: {

    })
    ```
  </Tab>
</Tabs>

***

##### 6. setOnLoad

This set(onLoad:) method is triggered when call logs are successfully loaded in CometChatCallLogs.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatCallLogs.set(onLoad: { callLogs in
    })
    ```
  </Tab>
</Tabs>

***

### Filters

**Filters** allow you to customize the data displayed in a list within a Component. You can filter the list based on your specific criteria, allowing for a more customized. Filters can be applied using RequestBuilders of Chat SDK.

##### 1. CallRequestBuilder

The [callRequestBuilder](/docs/sdk/ios/call-logs) enables you to filter and customize the call list based on available parameters in callRequestBuilder. This feature allows you to create more specific and targeted queries during the call. The following are the parameters available in [callRequestBuilder](/docs/sdk/ios/call-logs)

| Method            | Description                                         | Code                                                                                                                      |
| ----------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **fetchPrevious** | Fetches previous call logs                          | `fetchPrevious(authToken: String, onSuccess: (([CallLog]) -> Void), onError: (_ error: CometChatCallException?) -> Void)` |
| **fetchNext**     | Fetches next call logs                              | `fetchNext(onSuccess: (([CallLog]) -> Void), onError: (_ error: CometChatCallException?) -> Void)`                        |
| **limit**         | Sets the limit for the call logs request            | `.set(limit: Int)`                                                                                                        |
| **callType**      | Sets the call type for the call logs request        | `.set(callType: CallType)`                                                                                                |
| **callStatus**    | Sets the call status for the call logs request      | `.set(callStatus: CallStatus)`                                                                                            |
| **hasRecording**  | Sets the recording status for the call logs request | `.set(hasRecording: Bool)`                                                                                                |
| **callDirection** | Sets the call direction for the call logs request   | `.set(callDirection: CallDirection)`                                                                                      |
| **uid**           | Sets the user ID for the call logs request          | `.set(uid: String)`                                                                                                       |
| **guid**          | Sets the group ID for the call logs request         | `.set(guid: String)`                                                                                                      |
| **authToken**     | Sets the auth token for the call logs request       | `.set(authToken: String?)`                                                                                                |
| **build**         | Builds the call logs request                        | `.build()`                                                                                                                |

**Example**

In the example below, we are applying a filter based on limit , calltype and call status.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}

    let callRequestBuilder = CallLogsRequest.CallLogsBuilder()
    .set(limit: 2)
    .set(callType: .audio)
    .set(callStatus: .initiated)

    // To navigate to the CometChatCallLogs
    let callLogs = CometChatCallLogs()
    .set(callRequestBuilder: callRequestBuilder)

    self.navigationController?.pushViewController(callLogs, animated: true)
    ```
  </Tab>
</Tabs>

***

### Events

[Events](/docs/ui-kit/ios/components-overview#events) are emitted by a `Component`. By using event you can extend existing functionality. Being global events, they can be applied in Multiple Locations and are capable of being Added or Removed.

The `Call Logs` component does not have any exposed events.

***

## Customization

To fit your app's design requirements, you can customize the appearance of the conversation component. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.

### Style

Using Style you can customize the look and feel of the component in your app, These parameters typically control elements such as the color, size, shape, and fonts used within the component.

##### 1. CallLog Style

You can customize the appearance of the `CallLog` Component by applying the `CallLogStyle` to it using the following code snippet.

**Global level styling**

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let customAvatarStyle = AvatarStyle()
    customAvatarStyle.backgroundColor = UIColor(hex: "#FBAA75")
    customAvatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)
            
    CometChatCallLogs.style.titleColor = UIColor(hex: "#F76808")
    CometChatCallLogs.style.titleFont = UIFont(name: "Times-New-Roman", size: 34)
    CometChatCallLogs.avatarStyle = customAvatarStyle
    ```
  </Tab>
</Tabs>

**Instance level styling**

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let customAvatarStyle = AvatarStyle()
    customAvatarStyle.backgroundColor = UIColor(hex: "#FBAA75")
    customAvatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 20)
            
    let callLogStyle = CallLogStyle()
    callLogStyle.titleColor = UIColor(hex: "#F76808")
    callLogStyle.titleFont = UIFont(name: "Times-New-Roman", size: 34)
            
    let callLog = CometChatCallLogs()
    callLog.style = callLogStyle
    callLog.avatarStyle = customAvatarStyle
    ```
  </Tab>
</Tabs>

<Frame>
  <img alt="CometChatCallLogs with custom styling showing orange title text and rounded avatar with custom background color" />
</Frame>

List of properties exposed by CallLogStyle

| **Property**                  | **Default Value**                     | **Description**                              |
| ----------------------------- | ------------------------------------- | -------------------------------------------- |
| **List Item Styles**          |                                       |                                              |
| `listItemTitleTextColor`      | `CometChatTheme.textColorPrimary`     | Text color for the list item title.          |
| `listItemTitleFont`           | `CometChatTypography.Heading4.medium` | Font for the list item title.                |
| `listItemSubTitleTextColor`   | `CometChatTheme.textColorSecondary`   | Text color for the list item subtitle.       |
| `listItemSubTitleFont`        | `CometChatTypography.Body.regular`    | Font for the list item subtitle.             |
| `listItemBackground`          | `CometChatTheme.backgroundColor01`    | Background color for the list item.          |
| `listItemSelectedBackground`  | `CometChatTheme.backgroundColor01`    | Background color for the selected list item. |
| `listItemBorderWidth`         | `0`                                   | Border width for the list item.              |
| `listItemBorderColor`         | `CometChatTheme.borderColorLight`     | Border color for the list item.              |
| `listItemCornerRadius`        | `.init(cornerRadius: 0)`              | Corner radius for the list item.             |
| `listItemSelectionImageTint`  | `.clear`                              | Tint color for the selection image.          |
| `listItemDeSelectedImageTint` | `.clear`                              | Tint color for the deselected image.         |
| `listItemSelectedImage`       | `UIImage()`                           | Image for the selected list item.            |
| `listItemDeSelectedImage`     | `UIImage()`                           | Image for the deselected list item.          |
| **Background Styles**         |                                       |                                              |
| `backgroundColor`             | `CometChatTheme.backgroundColor01`    | Background color.                            |
| `borderWidth`                 | `0`                                   | Border width.                                |
| `borderColor`                 | `CometChatTheme.borderColorLight`     | Border color.                                |
| `cornerRadius`                | `.init(cornerRadius: 0)`              | Corner radius.                               |
| **Title Styles**              |                                       |                                              |
| `titleColor`                  | `CometChatTheme.textColorPrimary`     | Text color for the title.                    |
| `titleFont`                   | `CometChatTypography.Heading4.bold`   | Font for the title.                          |
| `largeTitleColor`             | `CometChatTheme.textColorPrimary`     | Text color for large titles.                 |
| `largeTitleFont`              | `nil`                                 | Font for large titles.                       |
| **Navigation Bar Styles**     |                                       |                                              |
| `navigationBarTintColor`      | `CometChatTheme.backgroundColor01`    | Background color for the navigation bar.     |
| `navigationBarItemsTintColor` | `CometChatTheme.iconColorPrimary`     | Tint color for navigation bar items.         |
| **Error Message Styles**      |                                       |                                              |
| `errorTitleTextFont`          | `CometChatTypography.Heading4.bold`   | Font for the error title.                    |
| `errorTitleTextColor`         | `CometChatTheme.textColorPrimary`     | Text color for the error title.              |
| `errorSubTitleFont`           | `CometChatTypography.Body.regular`    | Font for the error subtitle.                 |
| `errorSubTitleTextColor`      | `CometChatTheme.textColorSecondary`   | Text color for the error subtitle.           |
| **Retry Button Styles**       |                                       |                                              |
| `retryButtonTextColor`        | `CometChatTheme.white`                | Text color for the retry button.             |
| `retryButtonTextFont`         | `CometChatTypography.Button.medium`   | Font for the retry button text.              |
| `retryButtonBackgroundColor`  | `CometChatTheme.primaryColor`         | Background color for the retry button.       |
| `retryButtonBorderColor`      | `.clear`                              | Border color for the retry button.           |
| `retryButtonBorderWidth`      | `0`                                   | Border width for the retry button.           |
| `retryButtonCornerRadius`     | `.init(cornerRadius: 0)`              | Corner radius for the retry button.          |
| **Empty State Styles**        |                                       |                                              |
| `emptyTitleTextFont`          | `CometChatTypography.Heading4.bold`   | Font for the empty state title.              |
| `emptyTitleTextColor`         | `CometChatTheme.textColorPrimary`     | Text color for the empty state title.        |
| `emptySubTitleFont`           | `CometChatTypography.Body.regular`    | Font for the empty state subtitle.           |
| `emptySubTitleTextColor`      | `CometChatTheme.textColorSecondary`   | Text color for the empty state subtitle.     |
| **TableView Styles**          |                                       |                                              |
| `tableViewSeparator`          | `.clear`                              | Color for the table view separator.          |
| **Icon Styles**               |                                       |                                              |
| `backIcon`                    | `nil`                                 | Icon for the back button.                    |
| `backIconTint`                | `CometChatTheme.iconColorPrimary`     | Tint color for the back icon.                |
| `incomingCallIcon`            | System icon for "arrow\.down.left"    | Icon for incoming calls.                     |
| `incomingCallIconTint`        | `CometChatTheme.errorColor`           | Tint color for the incoming call icon.       |
| `outgoingCallIcon`            | System icon for "arrow\.up.right"     | Icon for outgoing calls.                     |
| `outgoingCallIconTint`        | `CometChatTheme.successColor`         | Tint color for the outgoing call icon.       |
| `missedCallTitleColor`        | `CometChatTheme.errorColor`           | Text color for missed call titles.           |
| `missedCallIcon`              | `nil`                                 | Icon for missed calls.                       |
| `missedCallIconTint`          | `CometChatTheme.errorColor`           | Tint color for the missed call icon.         |
| `audioCallIcon`               | System icon for "phone"               | Icon for audio calls.                        |
| `audioCallIconTint`           | `CometChatTheme.iconColorPrimary`     | Tint color for the audio call icon.          |
| `videoCallIcon`               | System icon for "video"               | Icon for video calls.                        |
| `videoCallIconTint`           | `CometChatTheme.iconColorPrimary`     | Tint color for the video call icon.          |
| `separatorColor`              | `.clear`                              | Color for separators.                        |

***

### Functionality

These are a set of small functional customizations that allow you to fine-tune the overall experience of the component. With these, you can change text, set custom icons, and toggle the visibility of UI elements.

Below is a list of customizations along with corresponding code snippets

| Property           | Description                                        | Code                            |
| ------------------ | -------------------------------------------------- | ------------------------------- |
| callRequestBuilder | Sets the `CallLogsBuilder` instance for call logs. | `.set(callRequestBuilder: Any)` |
| hideError          | Hides the error state view.                        | `hideError = true`              |
| hideNavigationBar  | Hides the navigation bar.                          | `hideNavigationBar = true`      |
| hideLoadingState   | Hides the loading state view.                      | `hideLoadingState = true`       |
| hideBackIcon       | Hides the back icon in the navigation bar.         | `hideBackIcon = true`           |

***

### Advance

For advanced-level customization, you can set custom views to the component. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your views, layouts, and UI elements and then incorporate those into the component.

#### Date Time Formatter

The **CometChatCallLogs** component supports full customization of how date and time are displayed using the [CometChatDateTimeFormatter](/docs/ui-kit/ios/localize#datetimeformatter).

This enables developers to localize, format, or personalize the date and time strings shown next to each call log such as “Today”, “Yesterday”, “12:45 PM”, etc.

1. Component-Level (Global)

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    CometChatCallLogs.dateTimeFormatter.time = { timestamp in
        return "at " + DateFormatter.localizedString(from: Date(timeIntervalSince1970: TimeInterval(timestamp)), dateStyle: .none, timeStyle: .short)
    }

    CometChatCallLogs.dateTimeFormatter.today = { timestamp in
        return "Today • \(formattedTime(from: timestamp))"
    }

    CometChatCallLogs.dateTimeFormatter.otherDay = { timestamp in // This will display older dates as "24 Apr 2025" instead of the default relative format.
        let formatter = DateFormatter()
        formatter.dateFormat = "dd MMM yyyy"
        return formatter.string(from: Date(timeIntervalSince1970: TimeInterval(timestamp)))
    }
    ```
  </Tab>
</Tabs>

2. Instance-Level (Local)

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callLogs = CometChatCallLogs()
    callLogs.dateTimeFormatter.yesterday = { timestamp in
        return "Yesterday at " + formattedTime(from: timestamp)
    }
    ```
  </Tab>
</Tabs>

##### Available closures

| Property  | Description                                                         | Code                                                      |
| --------- | ------------------------------------------------------------------- | --------------------------------------------------------- |
| time      | Called to format a timestamp as a standard time (e.g., "12:30 PM"). | `CometChatCallLogs.dateTimeFormatter.time = { ... }`      |
| today     | Called when rendering messages sent today.                          | `CometChatCallLogs.dateTimeFormatter.today = { ... }`     |
| yesterday | Called for yesterday's messages.                                    | `CometChatCallLogs.dateTimeFormatter.yesterday = { ... }` |
| lastweek  | Called for messages within the last week.                           | `CometChatCallLogs.dateTimeFormatter.lastweek = { ... }`  |
| otherDay  | Called for dates older than last week.                              | `CometChatCallLogs.dateTimeFormatter.otherDay = { ... }`  |
| minute    | Called when referring to "a minute ago".                            | `CometChatCallLogs.dateTimeFormatter.minute = { ... }`    |
| minutes   | Called for "x minutes ago".                                         | `CometChatCallLogs.dateTimeFormatter.minutes = { ... }`   |
| hour      | Called for "an hour ago".                                           | `CometChatCallLogs.dateTimeFormatter.hour = { ... }`      |
| hours     | Called for "x hours ago".                                           | `CometChatCallLogs.dateTimeFormatter.hours = { ... }`     |

Each closure receives a timestamp (Int, representing UNIX time) and must return a String representing the formatted time.

***

#### SetListItemView

With this function, you can assign a custom ListItem to the CallLogs Component.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callLogs = CometChatCallLogs()
    callLogs.set(listItemView: { callLog in
       let view = CustomListItem()
       return view         
    })
    ```
  </Tab>
</Tabs>

<Frame>
  <img alt="CometChatCallLogs with custom list item view showing call icon, caller name, subtitle, and date" />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatCallsSDK

    class CustomListItem: UIView {
        // Initialize UI components
        public var callImage: UIImageView = {
            let imageView = UIImageView()
            imageView.translatesAutoresizingMaskIntoConstraints = false
            return imageView
        }()
                
        public var nameLabel: UILabel = {
            let label = UILabel()
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
                
        public var subTitleLabel: UILabel = {
            let label = UILabel()
            label.translatesAutoresizingMaskIntoConstraints = false
            label.textAlignment = .center
            label.textColor = .lightGray
            return label
        }()
                
        public var dateLabel: UILabel = {
            let label = UILabel()
            label.translatesAutoresizingMaskIntoConstraints = false
            label.textAlignment = .center
            label.textColor = .systemGray3
            return label
        }()
                
        public var detailStackView: UIStackView = {
            let stack = UIStackView()
            stack.translatesAutoresizingMaskIntoConstraints = false
            stack.alignment = .leading
            stack.distribution = .fill
            stack.spacing = 4
            return stack
        }()
                
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupUI()
        }
                
        required init?(coder aDecoder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
                
        private func setupUI() {
            addSubview(callImage)
            addSubview(detailStackView)
            detailStackView.addArrangedSubview(nameLabel)
            detailStackView.addArrangedSubview(subTitleLabel)
            addSubview(dateLabel)
                    
            NSLayoutConstraint.activate([
                callImage.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 8),
                callImage.centerYAnchor.constraint(equalTo: centerYAnchor),
                callImage.widthAnchor.constraint(equalToConstant: 40),
                callImage.heightAnchor.constraint(equalToConstant: 40),
                        
                detailStackView.leadingAnchor.constraint(equalTo: callImage.trailingAnchor, constant: 8),
                detailStackView.trailingAnchor.constraint(equalTo: dateLabel.trailingAnchor, constant: -8),
                detailStackView.centerYAnchor.constraint(equalTo: callImage.centerYAnchor),
                        
                dateLabel.centerYAnchor.constraint(equalTo: callImage.centerYAnchor),
                dateLabel.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -12)
            ])
        }
    }
    ```
  </Tab>
</Tabs>

You can indeed create a custom listitem UIView file named `CustomListItem` for more complex or unique list items.

Afterwards, seamlessly integrate this `CustomListItem` UIView file into the `.setListItemView` method within **CometChatCallLogs()**.

***

#### SetTitleView

You can create a custom Title view for more complex or unique list items and integrate this `CustomTitleView` UIView file into the `.set(titleView:)` method within **CometChatCallLogs()**.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callLogs = CometChatCallLogs()
    callLogs.set(titleView: { callLog in
        let view = CustomTitleView()
        view.configure(callLog: callLog)
        return view
    })
    ```
  </Tab>
</Tabs>

**Example**

<Frame>
  <img alt="CometChatCallLogs with custom title view showing caller name with clock icon and duration" />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK
    import CometChatCallsSDK

    import UIKit

    class CustomTitleView: UIView {
        
        private let nameLabel: UILabel = {
            let label = UILabel()
            label.font = UIFont.systemFont(ofSize: 16, weight: .semibold)
            label.textColor = .black
            return label
        }()
        
        private let separatorLabel: UILabel = {
            let label = UILabel()
            label.text = "•"
            label.font = UIFont.systemFont(ofSize: 16, weight: .regular)
            label.textColor = .gray
            return label
        }()
        
        private let clockIcon: UIImageView = {
            let imageView = UIImageView(image: UIImage(systemName: "clock.fill"))
            imageView.tintColor = .gray
            imageView.contentMode = .scaleAspectFit
            return imageView
        }()
        
        private let timeLabel: UILabel = {
            let label = UILabel()
            label.font = UIFont.systemFont(ofSize: 16, weight: .regular)
            label.textColor = .gray
            return label
        }()
        
        private let stackView: UIStackView = {
            let stackView = UIStackView()
            stackView.axis = .horizontal
            stackView.alignment = .center
            stackView.spacing = 4
            return stackView
        }()
        
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupUI()
        }
        
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
        
        private func setupUI() {
            stackView.addArrangedSubview(nameLabel)
            stackView.addArrangedSubview(separatorLabel)
            stackView.addArrangedSubview(clockIcon)
            stackView.addArrangedSubview(timeLabel)
            
            addSubview(stackView)
            stackView.translatesAutoresizingMaskIntoConstraints = false
            NSLayoutConstraint.activate([
                stackView.leadingAnchor.constraint(equalTo: leadingAnchor),
                stackView.topAnchor.constraint(equalTo: topAnchor),
                stackView.bottomAnchor.constraint(equalTo: bottomAnchor),
                stackView.trailingAnchor.constraint(equalTo: trailingAnchor)
            ])
        }
        
        func configure(callLog: CometChatCallsSDK.CallLog){
            
            if let group = (callLog.receiver as? CallGroup) {
                callGroup = group
            } else if let initiator = (callLog.initiator as? CallUser), initiator.uid != CometChatUIKit.getLoggedInUser()?.uid {
                callUser = initiator
            } else if let receiver = (callLog.receiver as? CallUser) {
                callUser = receiver
            }
            
            nameLabel.text = callUser?.name ?? callGroup?.name ?? ""
            timeLabel.text = formatTime(seconds: (participant?.totalDurationInMinutes ?? 0.0)*60)
        }
    }
    ```
  </Tab>
</Tabs>

***

***

#### SetLeadingView

You can create a custom Title view for more complex or unique list items and integrate this `CustomLeadingView` UIView file into the `.set(leadingView:)` method within **CometChatCallLogs()**.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callLogs = CometChatCallLogs()
    callLogs.set(leadingView: { callLog in
        let view = CustomLeadingView()
        view.configure(callLog: callLog)
        return view
    })
    ```
  </Tab>
</Tabs>

**Example**

<Frame>
  <img alt="CometChatCallLogs with custom leading view showing purple circular call icon button" />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK
    import CometChatCallsSDK

    import UIKit

    class CustomLeadingView: UIButton {
        
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupUI()
        }
        
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
        
        private func setupUI() {
            let callIcon = UIImage(systemName: "phone.arrow.up.right")?.withRenderingMode(.alwaysTemplate)
            setImage(callIcon, for: .normal)
            tintColor = UIColor.purple
            backgroundColor = UIColor.purple.withAlphaComponent(0.1)
            layer.cornerRadius = 24 // Make it circular
            clipsToBounds = true
            
            NSLayoutConstraint.activate([
                widthAnchor.constraint(equalToConstant: 48),
                heightAnchor.constraint(equalToConstant: 48)
            ])
        }
        
        func configure(callLog: CometChatCallsSDK.CallLog){
            var image = UIImage()
            switch callLog?.status {
            case .busy, .unanswered, .rejected, .cancelled:
                image = UIImage(named: "missed_call_image")
            case .initiated, .ongoing, .ended:
                if isInitiator{
                    image = UIImage(systemName: "arrow.up.right")
                }else{
                    image = UIImage(systemName: "arrow.down.left")
                }
            case .none:
                break
            @unknown default:
                break
            }
            self.setImage(image, for: .normal)
        }
    }
    ```
  </Tab>
</Tabs>

***

#### SetSubTitleView

You can customize the subtitle view for each callLog item to meet your requirements.

You can indeed create a custom Subtitleview UIView file named `SubtitleView` for more complex or unique list items.

Afterwards, seamlessly integrate this `SubtitleView` UIView file into the `.setSubtitle` method within **CometChatCallLogs()**.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callLogs = CometChatCallLogs()
    callLogs.set(subtitleView: { callLog in
        let view =  CustomSubtitleView()
        return view
    })
    ```
  </Tab>
</Tabs>

**Example**

<Frame>
  <img alt="CometChatCallLogs with custom subtitle view showing call initiation timestamp" />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK
    import CometChatCallsSDK

    class CustomSubtitleView: UIView {
                
        // MARK: - Properties
        private let subtitleLabel: UILabel = {
            let label = UILabel()
            label.translatesAutoresizingMaskIntoConstraints = false
            label.font = UIFont.systemFont(ofSize: 14, weight: .regular) // Customize font
            label.textColor = .darkGray // Customize text color
            label.numberOfLines = 1 // Single line
            label.textAlignment = .left // Align to the left
            return label
        }()
                
        // MARK: - Initializers
        override init(frame: CGRect) {
            super.init(frame: frame)
                setupView()
        }
                
        required init?(coder: NSCoder) {
            super.init(coder: coder)
            setupView()
        }
                
        // MARK: - Setup
        private func setupView() {
            addSubview(subtitleLabel)
                    
            // Constraints
            NSLayoutConstraint.activate([
                subtitleLabel.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 8),
                subtitleLabel.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -8),
                subtitleLabel.topAnchor.constraint(equalTo: topAnchor, constant: 4),
                subtitleLabel.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -4)
            ])
        }
                
        // MARK: - Configuration
        func set(call: CometChatCallsSDK.CallLog) {
            subtitleLabel.text = call.initiatedAt
        }
    }
    ```
  </Tab>
</Tabs>

***

#### SetTrailView

You can customize the tail view for each users item to meet your requirements

You can indeed create a custom TrailView UIView file named `CustomTailView` for more complex or unique list items.

Afterwards, seamlessly integrate this `CustomTrailView` UIView file into the `.set(trailView:)` method within **CometChatCallLogs()**.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callLogs = CometChatCallLogs()
    callLogs.set(trailView: { callLog in
        let view = CustomTrailView()
        return view
    })
    ```
  </Tab>
</Tabs>

**Example**

<Frame>
  <img alt="CometChatCallLogs with custom trail view showing call timestamp on the right side" />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift
    import CometChatSDK
    import CometChatCallsSDK

    class CustomTrailView: UIView {
                
        // MARK: - Properties
        private let tailLabel: UILabel = {
            let label = UILabel()
            label.translatesAutoresizingMaskIntoConstraints = false
            label.font = UIFont.systemFont(ofSize: 14, weight: .regular) // Customize font
            label.textColor = .darkGray // Customize text color
            label.numberOfLines = 1 // Single line
            label.textAlignment = .right // Align to the right
            return label
        }()
                
        // MARK: - Initializers
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupView()
        }
                
        required init?(coder: NSCoder) {
            super.init(coder: coder)
            setupView()
        }
                
        // MARK: - Setup
        private func setupView() {
            addSubview(tailLabel)
                    
            // Constraints
            NSLayoutConstraint.activate([
                tailLabel.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 8),
                tailLabel.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -8),
                tailLabel.topAnchor.constraint(equalTo: topAnchor, constant: 4),
                tailLabel.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -4)
            ])
        }
                
        // MARK: - Configuration
        func set(call: CometChatCallsSDK.CallLog) {
            tailLabel.text = call.initiatedAt
        }
    }
    ```
  </Tab>
</Tabs>

***

***

## Props

All props are optional.

***

### callRequestBuilder

Controls which call logs load and in what order.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `CallLogsRequest.CallLogsBuilder?` |
| Default | `nil`                              |

***

### hideError

Hides the error state view.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

***

### hideNavigationBar

Hides the navigation bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

***

### hideLoadingState

Hides the loading state view.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

***

### hideBackIcon

Hides the back icon in the navigation bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

***

### avatarStyle

Customizes the appearance of avatars in the call logs list.

|         |                 |
| ------- | --------------- |
| Type    | `AvatarStyle`   |
| Default | `AvatarStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let customAvatarStyle = AvatarStyle()
customAvatarStyle.backgroundColor = UIColor.systemBlue
customAvatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)

let callLogs = CometChatCallLogs()
callLogs.avatarStyle = customAvatarStyle
```

***

## Events

Events emitted by the Call Logs component:

| Event             | Description                                     |
| ----------------- | ----------------------------------------------- |
| `onItemClick`     | Triggers when a call log item is clicked        |
| `onItemLongClick` | Triggers when a call log item is long pressed   |
| `onBack`          | Triggers when the back button is pressed        |
| `onError`         | Triggers when an error occurs                   |
| `onEmpty`         | Triggers when the call logs list is empty       |
| `onLoad`          | Triggers when call logs are successfully loaded |

***

## View Slots

| Slot           | Signature             | Replaces                        |
| -------------- | --------------------- | ------------------------------- |
| `listItemView` | `(CallLog) -> UIView` | Entire list item row            |
| `titleView`    | `(CallLog) -> UIView` | Name / title text               |
| `leadingView`  | `(CallLog) -> UIView` | Avatar / left section           |
| `trailView`    | `(CallLog) -> UIView` | Right section with call button  |
| `subtitleView` | `(CallLog) -> UIView` | Call type, direction, timestamp |

***

<Note>
  Ensure to pass and present `CometChatCallLogs`. If a navigation controller is already in use, utilize the pushViewController function instead of directly presenting the view controller.
</Note>

***

## Common Patterns

### Present Call Logs as a Tab

Add call logs as a tab in your main navigation:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    class MainTabBarController: UITabBarController {
        
        override func viewDidLoad() {
            super.viewDidLoad()
            
            let callLogs = CometChatCallLogs()
            let callLogsNav = UINavigationController(rootViewController: callLogs)
            callLogsNav.tabBarItem = UITabBarItem(
                title: "Calls",
                image: UIImage(systemName: "phone"),
                selectedImage: UIImage(systemName: "phone.fill")
            )
            
            viewControllers = [/* other tabs */, callLogsNav]
        }
    }
    ```
  </Tab>
</Tabs>

### Callback on Call Log Selection

Handle call log selection to initiate a callback:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callLogs = CometChatCallLogs()
    callLogs.set(onItemClick: { [weak self] callLog, indexPath in
        // Get the other participant
        var callUser: CallUser?
        if let initiator = callLog.initiator as? CallUser,
           initiator.uid != CometChatUIKit.getLoggedInUser()?.uid {
            callUser = initiator
        } else if let receiver = callLog.receiver as? CallUser {
            callUser = receiver
        }
        
        guard let user = callUser else { return }
        
        // Show callback options
        let alert = UIAlertController(title: "Call \(user.name ?? "")?", message: nil, preferredStyle: .actionSheet)
        alert.addAction(UIAlertAction(title: "Voice Call", style: .default) { _ in
            self?.initiateCall(uid: user.uid ?? "", type: .audio)
        })
        alert.addAction(UIAlertAction(title: "Video Call", style: .default) { _ in
            self?.initiateCall(uid: user.uid ?? "", type: .video)
        })
        alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
        self?.present(alert, animated: true)
    })
    ```
  </Tab>
</Tabs>

### Filter Call Logs by Type

Show only missed calls or specific call types:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Show only missed calls
    let missedCallsBuilder = CallLogsRequest.CallLogsBuilder()
        .set(callStatus: .unanswered)
        .set(limit: 30)

    let callLogs = CometChatCallLogs()
    callLogs.set(callRequestBuilder: missedCallsBuilder)

    // Show only video calls
    let videoCallsBuilder = CallLogsRequest.CallLogsBuilder()
        .set(callType: .video)
        .set(limit: 30)
    ```
  </Tab>
</Tabs>

### Call Logs with Custom Empty State

Show a custom view when there are no call logs:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callLogs = CometChatCallLogs()

    callLogs.set(onEmpty: { [weak self] in
        // Show custom empty state or prompt user to make their first call
        print("No call history yet")
    })

    // Or set a custom empty view
    let emptyView = UIView()
    let label = UILabel()
    label.text = "No calls yet\nStart a conversation!"
    label.textAlignment = .center
    label.numberOfLines = 0
    emptyView.addSubview(label)
    // Add constraints...

    callLogs.set(emptyView: emptyView)
    ```
  </Tab>
</Tabs>

***

## Related Components

<CardGroup>
  <Card title="Incoming Call" href="/ui-kit/ios/incoming-call">
    Display incoming call interface
  </Card>

  <Card title="Outgoing Call" href="/ui-kit/ios/outgoing-call">
    Display outgoing call interface
  </Card>

  <Card title="Call Buttons" href="/ui-kit/ios/call-buttons">
    Voice and video call buttons
  </Card>
</CardGroup>

***


# Compact Message Composer
Source: https://www.cometchat.com/docs/ui-kit/ios/compact-message-composer

Configure CometChat iOS UI Kit Compact Message Composer with single-line input, rich text, attachments, mentions, stickers, and voice recording.

## Overview

`CometChatCompactMessageComposer` is a [Component](/docs/ui-kit/ios/components-overview#components) that provides a compact, single-line message input designed for chat applications. It offers a streamlined interface with optional rich text formatting capabilities, supporting bold, italic, strikethrough, code, links, lists, and blockquotes.

Features such as Rich Text Formatting, Attachments, Message Editing, Mentions, Stickers, and Voice Recording are supported.

## Usage

### Integration

The following code snippet illustrates how you can directly incorporate the CompactMessageComposer component into your view.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let compactComposer = CometChatCompactMessageComposer()
    compactComposer.set(user: user)
    compactComposer.set(controller: self)
    compactComposer.translatesAutoresizingMaskIntoConstraints = false
    view.addSubview(compactComposer)
    ```
  </Tab>
</Tabs>

<Note>
  To ensure that the `CometChatCompactMessageComposer` is properly configured, passing the controller is mandatory.

  ```swift theme={null}
  compactComposer.set(controller: self) // Passing the controller is required
  ```
</Note>

### Actions

[Actions](/docs/ui-kit/ios/components-overview#actions) dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the component to fit your specific needs.

##### setOnSendButtonClick

The `set(onSendButtonClick:)` event gets activated when the send message button is clicked. It has a predefined function of sending messages entered in the composer. However, you can override this action with the following code snippet.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    compactComposer.set(onSendButtonClick: { message in
        // Your custom send handling
    })
    ```
  </Tab>
</Tabs>

***

##### setOnError

This action doesn't change the behavior of the component but rather listens for any errors that occur in the CompactMessageComposer component.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    compactComposer.set(onError: { error in
        // Your Exception Handling code
    })
    ```
  </Tab>
</Tabs>

***

##### setOnTextChangedListener

Function triggered whenever the message input's text value changes, enabling dynamic text handling.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    compactComposer.set(onTextChangedListener: { text in
        // Handle text change
    })
    ```
  </Tab>
</Tabs>

***

##### setAttachmentOptions

This action is triggered when the attachment button is clicked. You can override the default attachment sheet behavior with a custom implementation.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    compactComposer.set(attachmentOptions: { user, group, controller in
        // Return custom attachment actions
        return [CometChatMessageComposerAction]
    })
    ```
  </Tab>
</Tabs>

***

### Filters

CompactMessageComposer component does not have any available filters.

***

### Events

[Events](/docs/ui-kit/ios/components-overview#events) are emitted by a `Component`. By using event you can extend existing functionality. Being global events, they can be applied in Multiple Locations and are capable of being Added or Removed.

The CompactMessageComposer Component does not emit any events of its own.

***

## Customization

To fit your app's design requirements, you can customize the appearance of the CompactMessageComposer component. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.

### Style

Using Style you can customize the look and feel of the component in your app. These parameters typically control elements such as the color, size, shape, and fonts used within the component.

**Global level styling**

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    CometChatCompactMessageComposer.style.activeSendButtonBackgroundColor = UIColor(hex: "#F76808")
    CometChatCompactMessageComposer.style.attachmentImageTint = UIColor(hex: "#F76808")
    CometChatCompactMessageComposer.style.voiceRecordingImageTint = UIColor(hex: "#F76808")
    CometChatCompactMessageComposer.style.stickersImageTint = UIColor(hex: "#F76808")
    ```
  </Tab>
</Tabs>

**Instance level styling**

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    var customStyle = CompactMessageComposerStyle()
    customStyle.activeSendButtonBackgroundColor = UIColor(hex: "#F76808")
    customStyle.attachmentImageTint = UIColor(hex: "#F76808")
    customStyle.voiceRecordingImageTint = UIColor(hex: "#F76808")
    customStyle.stickersImageTint = UIColor(hex: "#F76808")

    let compactComposer = CometChatCompactMessageComposer()
    compactComposer.style = customStyle
    ```
  </Tab>
</Tabs>

The following properties are exposed by `CompactMessageComposerStyle`:

| Property                                 | Description                                             | Code                                                                              |
| ---------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------- |
| backgroundColor                          | Background color of the composer container.             | `style.backgroundColor = CometChatTheme.backgroundColor03`                        |
| cornerRadius                             | Corner radius for the composer container.               | `style.cornerRadius = CometChatCornerStyle?`                                      |
| borderWidth                              | Border width for the composer container.                | `style.borderWidth = 0`                                                           |
| borderColor                              | Border color for the composer container.                | `style.borderColor = .clear`                                                      |
| composeBoxBackgroundColor                | Background color for the compose box.                   | `style.composeBoxBackgroundColor = CometChatTheme.backgroundColor01`              |
| composeBoxBorderColor                    | Border color for the compose box.                       | `style.composeBoxBorderColor = CometChatTheme.borderColorDefault`                 |
| composeBoxBorderWidth                    | Border width for the compose box.                       | `style.composeBoxBorderWidth = 1`                                                 |
| composeBoxCornerRadius                   | Corner radius for the compose box.                      | `style.composeBoxCornerRadius = .init(cornerRadius: CometChatSpacing.Radius.r2)`  |
| composerSeparatorColor                   | Color for the separator in the compose box.             | `style.composerSeparatorColor = CometChatTheme.borderColorLight`                  |
| textFieldFont                            | Font for the input text field.                          | `style.textFieldFont = CometChatTypography.Body.regular`                          |
| textFieldColor                           | Text color for the input field.                         | `style.textFieldColor = CometChatTheme.textColorPrimary`                          |
| placeholderFont                          | Font for the placeholder text.                          | `style.placeholderFont = CometChatTypography.Body.regular`                        |
| placeholderColor                         | Color for the placeholder text.                         | `style.placeholderColor = CometChatTheme.textColorTertiary`                       |
| sendButtonImage                          | Icon for the send button.                               | `style.sendButtonImage = UIImage(named: "custom-send")`                           |
| sendButtonImageTint                      | Tint color for the send button image.                   | `style.sendButtonImageTint = CometChatTheme.white`                                |
| activeSendButtonBackgroundColor          | Background color for send button when active.           | `style.activeSendButtonBackgroundColor = CometChatTheme.primaryColor`             |
| inactiveSendButtonBackgroundColor        | Background color for send button when inactive.         | `style.inactiveSendButtonBackgroundColor = CometChatTheme.neutralColor300`        |
| attachmentImage                          | Icon for the attachment button.                         | `style.attachmentImage = UIImage(systemName: "plus.circle")`                      |
| attachmentImageTint                      | Tint color for the attachment image.                    | `style.attachmentImageTint = CometChatTheme.iconColorSecondary`                   |
| voiceRecordingImage                      | Icon for the voice recording button.                    | `style.voiceRecordingImage = UIImage(systemName: "mic")`                          |
| voiceRecordingImageTint                  | Tint color for the voice recording image.               | `style.voiceRecordingImageTint = CometChatTheme.iconColorSecondary`               |
| stickersImage                            | Icon for the stickers button.                           | `style.stickersImage = UIImage(named: "sticker-image")`                           |
| stickersImageTint                        | Tint color for the stickers image.                      | `style.stickersImageTint = CometChatTheme.iconColorSecondary`                     |
| stickersActiveImageTint                  | Tint color for the stickers image when active.          | `style.stickersActiveImageTint = CometChatTheme.primaryColor`                     |
| codeBlockBackgroundColor                 | Background color for code block mode.                   | `style.codeBlockBackgroundColor = UIColor(hex: "#F5F5F5")`                        |
| codeBlockBorderColor                     | Border color for code block mode.                       | `style.codeBlockBorderColor = UIColor(hex: "#E8E8E8")`                            |
| codeBlockBorderWidth                     | Border width for code block mode.                       | `style.codeBlockBorderWidth = 1`                                                  |
| previewTitleFont                         | Font for the title in the edit/reply preview.           | `style.previewTitleFont = CometChatTypography.Body.regular`                       |
| previewMessageFont                       | Font for the message text in the edit/reply preview.    | `style.previewMessageFont = CometChatTypography.Caption1.regular`                 |
| previewTitleColor                        | Text color for the title in the edit/reply preview.     | `style.previewTitleColor = CometChatTheme.textColorPrimary`                       |
| previewMessageColor                      | Text color for the message in the edit/reply preview.   | `style.previewMessageColor = CometChatTheme.textColorSecondary`                   |
| previewBackgroundColor                   | Background color for the edit/reply preview.            | `style.previewBackgroundColor = CometChatTheme.backgroundColor03`                 |
| previewCloseIcon                         | Icon for closing the edit/reply preview.                | `style.previewCloseIcon = UIImage(systemName: "xmark")`                           |
| previewCloseIconTint                     | Tint color for the close icon in the preview.           | `style.previewCloseIconTint = CometChatTheme.iconColorHighlight`                  |
| infoIcon                                 | Icon for the mention limit info banner.                 | `style.infoIcon = UIImage(systemName: "info.circle")`                             |
| infoIconTint                             | Tint color for the info icon.                           | `style.infoIconTint = CometChatTheme.errorColor`                                  |
| infoTextColor                            | Text color for the info text.                           | `style.infoTextColor = CometChatTheme.errorColor`                                 |
| infoTextFont                             | Font for the info text.                                 | `style.infoTextFont = CometChatTypography.Caption1.regular`                       |
| infoBackgroundColor                      | Background color for the info section.                  | `style.infoBackgroundColor = CometChatTheme.backgroundColor02`                    |
| richTextToolbarStyle                     | Style configuration for the rich text toolbar.          | `style.richTextToolbarStyle = RichTextToolbarStyle()`                             |
| agenticSendButtonImage                   | Icon for the send button in agentic mode.               | `style.agenticSendButtonImage = UIImage(systemName: "arrow.up")`                  |
| agenticSendButtonImageTint               | Tint color for the agentic send button image.           | `style.agenticSendButtonImageTint = CometChatTheme.neutralColor50`                |
| agenticActiveSendButtonBackgroundColor   | Background color for agentic send button when active.   | `style.agenticActiveSendButtonBackgroundColor = CometChatTheme.neutralColor900`   |
| agenticInactiveSendButtonBackgroundColor | Background color for agentic send button when inactive. | `style.agenticInactiveSendButtonBackgroundColor = CometChatTheme.neutralColor300` |

***

### Functionality

These are a set of small functional customizations that allow you to fine-tune the overall experience of the component. With these, you can change text, set custom icons, and toggle the visibility of UI elements.

Below is a list of customizations along with corresponding code snippets:

| Property                               | Description                                                                                                                                      | Code                                           |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| User                                   | Used to pass user object of which header specific details will be shown.                                                                         | `set(user: User)`                              |
| Group                                  | Used to pass group object of which header specific details will be shown.                                                                        | `set(group: Group)`                            |
| setParentMessageId                     | Sets the parent message ID for threaded replies.                                                                                                 | `set(parentMessageId: Int)`                    |
| setPlaceholder                         | Sets the placeholder text for the input field.                                                                                                   | `set(placeholder: "Type a message...")`        |
| setMaxLines                            | Maximum lines allowed to increase in the input field.                                                                                            | `set(maxLines: Int)`                           |
| setTextFormatter                       | Assigns the list of text formatters (e.g., mentions).                                                                                            | `set(textFormatter: [CometChatTextFormatter])` |
| setEnableRichTextFormatting            | Master switch to enable or disable rich text formatting (bold, italic, etc.). Default `true`.                                                    | `enableRichTextFormatting = true`              |
| setRichTextFormattingOptionsVisibility | Controls the visibility of the rich text formatting toolbar. Default `true`.                                                                     | `showRichTextFormattingOptions = true`         |
| setDisableTypingEvents                 | Used to disable/enable typing events, default false.                                                                                             | `disable(typingEvents: true)`                  |
| setDisableSoundForMessages             | Used to toggle sound for outgoing messages.                                                                                                      | `disable(soundForMessages: true)`              |
| setCustomSoundForMessages              | Used to give custom sounds to outgoing messages.                                                                                                 | `customSoundForMessage = URL`                  |
| setDisableMentions                     | Sets whether mentions in text should be disabled. Removes any formatters that are instances of `CometChatMentionsFormatter`.                     | `disable(mentions: true)`                      |
| setAttachmentButtonVisibility          | Hides the attachment button in the composer.                                                                                                     | `hideAttachmentButton = true`                  |
| setVoiceRecordingButtonVisibility      | Hides the voice recording button in the composer.                                                                                                | `hideVoiceRecordingButton = true`              |
| setStickerButtonVisibility             | Hides the sticker button in the composer.                                                                                                        | `hideStickersButton = true`                    |
| setSendButtonVisibility                | Hides the send button in the composer.                                                                                                           | `hideSendButton = true`                        |
| setEnableMultipleAttachments           | Multi-select attachment picking with a preview tray. Default `true`; `false` reverts to the legacy single-attachment, send-immediately behavior. | `enableMultipleAttachments = true`             |

***

## Multiple Attachments

The compact composer supports sending several attachments in one go. Tapping a media or file option opens a multi-select picker; the picks are staged in an **attachment tray** above the input box, upload immediately, and are sent together when the user taps send.

**How it works:**

* **Multi-select picking** — the photo/video picker and the document picker both allow selecting multiple items, capped to the app's per-message limit. Camera captures and audio files stage into the same tray.
* **Attachment tray** — each staged file shows as a tile (thumbnail for media, chip for files/audio) with a live upload progress ring, a ✕ to cancel or remove, and tap-to-retry on network failure.
* **Upload before send** — files upload as soon as they are staged; the send button stays disabled until every upload finishes. Text typed in the composer becomes the **caption** of the batch, with rich text formatting preserved.
* **One message per attachment type** — a mixed pick is split into separate messages in a fixed order (images → videos → audios → files) that render as grouped bubbles in the message list.
* **Clipboard paste** — images, videos, documents and audio files copied to the clipboard can be pasted straight into the composer and stage into the tray.
* **Voice notes stay standalone** — a mic recording always sends immediately as its own message and is never staged. The mic button hides while attachments are staged and returns when the tray empties.
* Attachments cannot be added while **editing** a message; the attachment button is disabled for the duration of the edit. Editing a media message edits its caption only.

### Limits and Validation

Limits are governed by the app's server settings (CometChat dashboard) — the composer reads them at runtime and they cannot be overridden client-side:

| Limit             | Setting                          | Behavior on violation                                                                                   |
| ----------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Files per message | `file.count.max` (default 10)    | Picker selection is capped; overflow picks are dropped with a "You can attach up to N files." snack bar |
| Per-file size     | `file.size.max` (default 100 MB) | The file stages as a red, non-retryable error tile; sending is blocked until it is removed              |
| File type         | Server-side validation           | The upload is refused by the server and the file becomes a red, non-retryable error tile                |

Tapping an error tile shows a snack bar with the reason ("File exceeds N MB.", "This file type isn't allowed."). The snack bar's appearance is themable through `CometChatErrorStateStyle`:

```swift theme={null}
CometChatErrorState.defaultStyle.backgroundColor = .systemRed
CometChatErrorState.defaultStyle.cornerRadius = 12
```

### Disabling Multiple Attachments

Set `enableMultipleAttachments` to `false` to restore the legacy behavior — single-item pickers that send immediately with no tray:

```swift theme={null}
compactComposer.enableMultipleAttachments = false
```

This is composer-side only: received multi-attachment messages still render with the grouped bubbles (see [Message List](/docs/ui-kit/ios/message-list)).

***

## Rich Text Formatting

The CompactMessageComposer includes a built-in rich text editor. `enableRichTextFormatting` and `showRichTextFormattingOptions` are `true` by default, so rich text formatting and the formatting toolbar are enabled out of the box.

* `enableRichTextFormatting` — Master switch that activates formatting. When set to `false`, even manually typed markdown syntax like `**text**` will be sent as plain text.
* `showRichTextFormattingOptions` — Controls the visibility of the formatting toolbar below the input field.

### Supported Format Types

| Format        | Description             | Markdown Syntax |
| ------------- | ----------------------- | --------------- |
| Bold          | Makes text bold         | `**text**`      |
| Italic        | Makes text italic       | `*text*`        |
| Underline     | Underlines text         | `<u>text</u>`   |
| Strikethrough | Strikes through text    | `~~text~~`      |
| Inline Code   | Formats as inline code  | `` `code` ``    |
| Code Block    | Creates a code block    | ` ```code``` `  |
| Blockquote    | Creates a blockquote    | `> text`        |
| Numbered List | Creates a numbered list | `1. item`       |
| Bullet List   | Creates a bullet list   | `- item`        |
| Link          | Creates a hyperlink     | `[text](url)`   |

### Configuration

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    // Disable rich text formatting
    compactComposer.enableRichTextFormatting = false

    // Hide the formatting toolbar
    compactComposer.showRichTextFormattingOptions = false
    ```
  </Tab>
</Tabs>

| enableRichTextFormatting | showRichTextFormattingOptions | Result                                               |
| ------------------------ | ----------------------------- | ---------------------------------------------------- |
| true (default)           | true (default)                | Toolbar visible below input, full formatting support |
| true                     | false                         | No toolbar, markdown syntax is still parsed on send  |
| false                    | —                             | Plain text, no formatting                            |

***

### RichTextToolbarStyle

**Global level styling**

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    CometChatCompactMessageComposer.style.richTextToolbarStyle.backgroundColor = UIColor(hex: "#F5F5F5")
    CometChatCompactMessageComposer.style.richTextToolbarStyle.iconTintColor = UIColor(hex: "#666666")
    CometChatCompactMessageComposer.style.richTextToolbarStyle.activeIconTintColor = UIColor(hex: "#F76808")
    CometChatCompactMessageComposer.style.richTextToolbarStyle.activeButtonBackgroundColor = UIColor(hex: "#FFF0E6")
    ```
  </Tab>
</Tabs>

The following properties are exposed by `RichTextToolbarStyle`:

| Property                    | Description                            | Code                                                                                |
| --------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------- |
| backgroundColor             | Background color of the toolbar.       | `toolbarStyle.backgroundColor = CometChatTheme.backgroundColor02`                   |
| borderColor                 | Border color of the toolbar.           | `toolbarStyle.borderColor = CometChatTheme.borderColorLight`                        |
| buttonSize                  | Size of format buttons.                | `toolbarStyle.buttonSize = 30`                                                      |
| buttonSpacing               | Spacing between format buttons.        | `toolbarStyle.buttonSpacing = CometChatSpacing.Spacing.s2`                          |
| iconTintColor               | Tint color for inactive format icons.  | `toolbarStyle.iconTintColor = CometChatTheme.iconColorSecondary`                    |
| activeIconTintColor         | Tint color for active format icons.    | `toolbarStyle.activeIconTintColor = CometChatTheme.primaryColor`                    |
| buttonBackgroundColor       | Background color for inactive buttons. | `toolbarStyle.buttonBackgroundColor = .clear`                                       |
| activeButtonBackgroundColor | Background color for active buttons.   | `toolbarStyle.activeButtonBackgroundColor = CometChatTheme.extendedPrimaryColor100` |

***

## Advanced

For advanced-level customization, you can set custom views to the component. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your views, layouts, and UI elements and then incorporate those into the component.

### setTextFormatters

Assigns the list of text formatters. If the provided list is not null, it sets the list. Otherwise, it assigns the default text formatters retrieved from the data source. To configure the existing Mentions look and feel check out [CometChatMentionsFormatter](/docs/ui-kit/ios/mentions-formatter-guide)

**Example**

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let composerTextStyle = MentionTextStyle()
        .set(textBackgroundColor: .white)
        .set(textColor: UIColor.black)
        .set(textFont: UIFont.systemFont(ofSize: 18, weight: .heavy))
        .set(loggedInUserTextColor: UIColor.systemTeal)
        .set(loggedInUserTextFont: UIFont.systemFont(ofSize: 18, weight: .bold))

    let customMentionFormatter = CometChatMentionsFormatter()
        .set(composerTextStyle: composerTextStyle)

    let compactComposer = CometChatCompactMessageComposer()
    compactComposer.set(textFormatter: [customMentionFormatter])
    ```
  </Tab>
</Tabs>

***

### setAttachmentOptions

By using `set(attachmentOptions:)`, you can set a list of custom `CometChatMessageComposerAction` for the CompactMessageComposer Component. This will override the existing list of `CometChatMessageComposerAction`.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    compactComposer.set(attachmentOptions: { user, group, controller in
        return [CometChatMessageComposerAction]
    })
    ```
  </Tab>
</Tabs>

**Example**

In this example, we are overriding the existing MessageComposerActions List with custom actions.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let compactComposer = CometChatCompactMessageComposer()

    compactComposer.set(attachmentOptions: { user, group, controller in
        let action1 = CometChatMessageComposerAction(
            id: "customAction1",
            text: "Custom Option 1",
            startIcon: UIImage(systemName: "camera"),
            startIconTint: .black,
            textColor: .black,
            onActionClick: {
                print("Custom Option 1 clicked!")
            }
        )

        let action2 = CometChatMessageComposerAction(
            id: "customAction2",
            text: "Custom Option 2",
            startIcon: UIImage(systemName: "doc"),
            startIconTint: .black,
            textColor: .black,
            onActionClick: {
                print("Custom Option 2 clicked!")
            }
        )

        return [action1, action2]
    })
    ```
  </Tab>
</Tabs>

***

### Edit & Reply Mode

The CompactMessageComposer supports editing and replying to messages. You can programmatically put the composer into edit or reply mode.

**Edit a message**

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    compactComposer.edit(message: textMessage)
    ```
  </Tab>
</Tabs>

**Reply to a message**

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    compactComposer.reply(message: baseMessage)
    ```
  </Tab>
</Tabs>

**Preview a message with a specific mode**

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    compactComposer.preview(message: baseMessage, mode: .edit)
    // or
    compactComposer.preview(message: baseMessage, mode: .reply)
    ```
  </Tab>
</Tabs>

***

### Complete Integration Example

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    import UIKit
    import CometChatUIKitSwift

    class ChatViewController: UIViewController {
        var user: User?

        override func viewDidLoad() {
            super.viewDidLoad()
            setupComposer()
        }

        private func setupComposer() {
            guard let user = user else { return }

            let compactComposer = CometChatCompactMessageComposer()
            compactComposer.set(user: user)
            compactComposer.set(controller: self)

            // Customize
            compactComposer.set(placeholder: "Type a message...")
            compactComposer.disable(typingEvents: false)

            // Callbacks
            compactComposer.set(onSendButtonClick: { message in
                print("Message sent: \(message)")
            })

            compactComposer.set(onError: { error in
                print("Error: \(error.errorDescription)")
            })

            // Layout
            compactComposer.translatesAutoresizingMaskIntoConstraints = false
            view.addSubview(compactComposer)

            NSLayoutConstraint.activate([
                compactComposer.leadingAnchor.constraint(equalTo: view.leadingAnchor),
                compactComposer.trailingAnchor.constraint(equalTo: view.trailingAnchor),
                compactComposer.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
            ])
        }
    }
    ```
  </Tab>
</Tabs>


# Components Overview
Source: https://www.cometchat.com/docs/ui-kit/ios/components-overview

Understand CometChat iOS UI Kit component types, base components, composite components, actions, events, filters, and customization.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "platform": "iOS UI Kit",
    "package": "CometChatUIKitSwift",
    "version": "5.1.9",
    "componentTypes": {
      "base": "Simple UI elements with no business logic",
      "components": "UI elements with built-in business logic",
      "composite": "Multiple components combined into complete features"
    },
    "baseComponents": [
      {"name": "CometChatAvatar", "purpose": "User/group profile images"},
      {"name": "CometChatBadge", "purpose": "Notification counts"},
      {"name": "CometChatStatusIndicator", "purpose": "Online/offline status"},
      {"name": "CometChatDate", "purpose": "Formatted timestamps"},
      {"name": "CometChatReceipt", "purpose": "Message delivery status"}
    ],
    "components": [
      {"name": "CometChatUsers", "purpose": "List of users"},
      {"name": "CometChatGroups", "purpose": "List of groups"},
      {"name": "CometChatConversations", "purpose": "Recent chats list"},
      {"name": "CometChatMessageList", "purpose": "Chat messages"},
      {"name": "CometChatMessageComposer", "purpose": "Message input"},
      {"name": "CometChatMessageHeader", "purpose": "Chat header"},
      {"name": "CometChatCallLogs", "purpose": "Call history"}
    ],
    "compositeComponents": [
      {"name": "CometChatMessages", "contains": ["MessageHeader", "MessageList", "MessageComposer"]},
      {"name": "CometChatUsersWithMessages", "contains": ["Users", "Messages"]},
      {"name": "CometChatGroupsWithMessages", "contains": ["Groups", "Messages"]},
      {"name": "CometChatConversationsWithMessages", "contains": ["Conversations", "Messages"]}
    ]
  }
  ```
</Accordion>

## Overview

CometChat UI Kit provides pre-built components that you can use to quickly build a chat experience. Components are organized into three types based on complexity.

***

## Component Types

### Base Components

Simple UI elements with no business logic. They display data you pass to them.

| Component                  | Purpose                   |
| -------------------------- | ------------------------- |
| `CometChatAvatar`          | User/group profile images |
| `CometChatBadge`           | Notification counts       |
| `CometChatStatusIndicator` | Online/offline status     |
| `CometChatDate`            | Formatted timestamps      |
| `CometChatReceipt`         | Message delivery status   |

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Avatar - displays user image
    let avatar = CometChatAvatar()
    avatar.setAvatar(avatarUrl: user.avatar, with: user.name)

    // Badge - shows unread count
    let badge = CometChatBadge()
    badge.set(count: 5)

    // Status indicator - shows online status
    let status = CometChatStatusIndicator()
    status.set(status: .online)
    ```
  </Tab>
</Tabs>

***

### Components

UI elements with built-in business logic. They fetch data, handle actions, and emit events.

| Component                  | Purpose           |
| -------------------------- | ----------------- |
| `CometChatUsers`           | List of users     |
| `CometChatGroups`          | List of groups    |
| `CometChatConversations`   | Recent chats list |
| `CometChatMessageList`     | Chat messages     |
| `CometChatMessageComposer` | Message input     |
| `CometChatMessageHeader`   | Chat header       |
| `CometChatCallLogs`        | Call history      |

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Users list - fetches and displays users automatically
    let users = CometChatUsers()
    users.set(onItemClick: { user, indexPath in
        print("Selected: \(user.name ?? "")")
    })

    // Conversations - shows recent chats
    let conversations = CometChatConversations()
    conversations.set(onItemClick: { conversation, indexPath in
        // Open chat
    })

    // Message list - displays messages for a user/group
    let messageList = CometChatMessageList()
    messageList.set(user: user)
    ```
  </Tab>
</Tabs>

***

### Composite Components

Combine multiple components into complete features.

| Component                            | Contains                                      |
| ------------------------------------ | --------------------------------------------- |
| `CometChatMessages`                  | MessageHeader + MessageList + MessageComposer |
| `CometChatUsersWithMessages`         | Users + Messages                              |
| `CometChatGroupsWithMessages`        | Groups + Messages                             |
| `CometChatConversationsWithMessages` | Conversations + Messages                      |

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Complete chat experience in one component
    let conversationsWithMessages = CometChatConversationsWithMessages()
    navigationController?.pushViewController(conversationsWithMessages, animated: true)

    // Or just the messages view
    let messages = CometChatMessages()
    messages.user = user  // or messages.group = group
    navigationController?.pushViewController(messages, animated: true)
    ```
  </Tab>
</Tabs>

***

## Actions

Actions define how components respond to user interactions.

### Predefined Actions

Built-in behaviors that work automatically:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // CometChatConversations has predefined actions:
    // - Tap conversation → Opens messages
    // - Long press → Shows options
    // - Swipe → Delete conversation

    let conversations = CometChatConversations()
    // These work automatically!
    ```
  </Tab>
</Tabs>

### Custom Actions

Override default behavior with your own logic:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift
    import CometChatSDK

    let conversations = CometChatConversations()

    // Override tap action
    conversations.set(onItemClick: { conversation, indexPath in
        // Your custom logic
        print("Tapped: \(conversation.conversationWith?.name ?? "")")
        
        // Navigate to custom screen instead of default
        let customChatVC = MyChatViewController()
        customChatVC.conversation = conversation
        self.navigationController?.pushViewController(customChatVC, animated: true)
    })

    // Override long press
    conversations.set(onItemLongClick: { conversation, indexPath in
        // Show custom options
        self.showCustomOptions(for: conversation)
    })

    // Handle errors
    conversations.set(onError: { error in
        print("Error: \(error.localizedDescription)")
    })

    // Handle empty state
    conversations.set(onEmpty: {
        print("No conversations")
    })
    ```
  </Tab>
</Tabs>

***

## Events

Events allow components to communicate without direct references. Subscribe to events from anywhere in your app.

### Available Events

| Event                  | Triggered When            |
| ---------------------- | ------------------------- |
| `ccMessageSent`        | Message is sent           |
| `ccMessageEdited`      | Message is edited         |
| `ccMessageDeleted`     | Message is deleted        |
| `ccMessageRead`        | Message is read           |
| `ccUserBlocked`        | User is blocked           |
| `ccUserUnblocked`      | User is unblocked         |
| `ccGroupCreated`       | Group is created          |
| `ccGroupDeleted`       | Group is deleted          |
| `ccGroupMemberAdded`   | Member added to group     |
| `ccGroupMemberRemoved` | Member removed from group |

### Subscribe to Events

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift
    import Combine

    class ChatManager {
        
        private var cancellables = Set<AnyCancellable>()
        
        func subscribeToEvents() {
            // Message sent event
            CometChatMessageEvents.ccMessageSent
                .sink { message in
                    print("Message sent: \(message.text ?? "")")
                    // Update UI, analytics, etc.
                }
                .store(in: &cancellables)
            
            // Message deleted event
            CometChatMessageEvents.ccMessageDeleted
                .sink { message in
                    print("Message deleted: \(message.id)")
                }
                .store(in: &cancellables)
            
            // User blocked event
            CometChatUserEvents.ccUserBlocked
                .sink { user in
                    print("Blocked: \(user.name ?? "")")
                }
                .store(in: &cancellables)
            
            // Group member added
            CometChatGroupEvents.ccGroupMemberAdded
                .sink { (action, addedBy, addedUser, group) in
                    print("\(addedUser.name ?? "") added to \(group.name ?? "")")
                }
                .store(in: &cancellables)
        }
        
        func unsubscribe() {
            cancellables.removeAll()
        }
    }
    ```
  </Tab>
</Tabs>

***

## Configurations

Customize nested components within composite components:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // CometChatMessages contains: MessageHeader, MessageList, MessageComposer
    // You can configure each one:

    let messages = CometChatMessages()
    messages.user = user

    // Configure MessageHeader
    let headerConfig = MessageHeaderConfiguration()
    headerConfig.hideBackButton = false
    headerConfig.set(subtitleView: { user, group in
        let label = UILabel()
        label.text = user?.status == .online ? "Online" : "Offline"
        label.textColor = user?.status == .online ? .systemGreen : .gray
        return label
    })
    messages.set(messageHeaderConfiguration: headerConfig)

    // Configure MessageList
    let listConfig = MessageListConfiguration()
    listConfig.set(emptyStateText: "No messages yet")
    listConfig.set(errorStateText: "Failed to load messages")
    messages.set(messageListConfiguration: listConfig)

    // Configure MessageComposer
    let composerConfig = MessageComposerConfiguration()
    composerConfig.set(placeholderText: "Type a message...")
    composerConfig.hideLiveReaction = true
    messages.set(messageComposerConfiguration: composerConfig)
    ```
  </Tab>
</Tabs>

***

## Component Hierarchy

```
CometChatConversationsWithMessages
├── CometChatConversations
│   ├── CometChatListItem
│   │   ├── CometChatAvatar
│   │   ├── CometChatBadge
│   │   ├── CometChatStatusIndicator
│   │   └── CometChatDate
│   └── CometChatListBase
└── CometChatMessages
    ├── CometChatMessageHeader
    │   ├── CometChatAvatar
    │   └── CometChatStatusIndicator
    ├── CometChatMessageList
    │   ├── CometChatMessageBubble
    │   ├── CometChatReceipt
    │   └── CometChatDate
    └── CometChatMessageComposer
        ├── CometChatMediaRecorder
        └── CometChatStickerKeyboard
```

***

## Quick Reference

### When to Use Each Type

| Need                              | Use                                      |
| --------------------------------- | ---------------------------------------- |
| Display user avatar               | `CometChatAvatar` (Base)                 |
| Show list of users                | `CometChatUsers` (Component)             |
| Complete chat with user selection | `CometChatUsersWithMessages` (Composite) |
| Custom chat UI                    | Individual Components                    |
| Quick integration                 | Composite Components                     |

### Common Patterns

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Pattern 1: Quick integration with composite
    let chat = CometChatConversationsWithMessages()
    navigationController?.pushViewController(chat, animated: true)

    // Pattern 2: Custom flow with components
    let users = CometChatUsers()
    users.set(onItemClick: { user, _ in
        let messages = CometChatMessages()
        messages.user = user
        self.navigationController?.pushViewController(messages, animated: true)
    })

    // Pattern 3: Fully custom with base components
    let customCell = UITableViewCell()
    let avatar = CometChatAvatar()
    avatar.setAvatar(avatarUrl: user.avatar, with: user.name)
    customCell.contentView.addSubview(avatar)
    ```
  </Tab>
</Tabs>

***

## Related

* [Component Styling](/docs/ui-kit/ios/component-styling) - Customize appearance
* [Color Resources](/docs/ui-kit/ios/color-resources) - Theme colors
* [Getting Started](/docs/ui-kit/ios/getting-started) - Initial setup


# Conversations
Source: https://www.cometchat.com/docs/ui-kit/ios/conversations

Display CometChat iOS UI Kit conversations with last messages, unread counts, typing indicators, presence, filters, and item callbacks.

The `CometChatConversations` component displays a list of all conversations (one-on-one and group chats) for the currently logged-in user. It shows the last message, unread count, typing indicators, and user presence in real-time.

<Frame>
  <img alt="CometChatConversations showing a list of recent conversations with user avatars, last message previews, timestamps, and unread message badges" />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatConversations",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "description": "Displays a list of all conversations for the logged-in user with real-time updates for messages, typing indicators, and presence.",
    "inherits": "UIViewController",
    "primaryOutput": {
      "callback": "onItemClick",
      "type": "(Conversation, IndexPath) -> Void"
    },
    "props": {
      "data": {
        "conversationRequestBuilder": {
          "type": "ConversationRequest.ConversationRequestBuilder?",
          "default": "nil",
          "note": "Custom request builder for filtering conversations"
        }
      },
      "callbacks": {
        "onItemClick": "(Conversation, IndexPath) -> Void",
        "onItemLongClick": "(Conversation, IndexPath) -> Void",
        "onBack": "() -> Void",
        "onSelection": "([Conversation]) -> Void",
        "onError": "(CometChatException) -> Void",
        "onEmpty": "() -> Void",
        "onLoad": "([Conversation]) -> Void"
      },
      "visibility": {
        "hideSearch": { "type": "Bool", "default": false },
        "hideReceipts": { "type": "Bool", "default": false },
        "hideUserStatus": { "type": "Bool", "default": false },
        "hideGroupType": { "type": "Bool", "default": false },
        "hideDeleteConversationOption": { "type": "Bool", "default": false },
        "hideNavigationBar": { "type": "Bool", "default": false },
        "hideBackButton": { "type": "Bool", "default": false }
      },
      "sound": {
        "disableSoundForMessages": { "type": "Bool", "default": false },
        "customSoundForMessages": { "type": "URL?", "default": "nil" }
      },
      "selection": {
        "selectionMode": { "type": "SelectionMode", "default": ".none" }
      },
      "viewSlots": {
        "listItemView": "(Conversation) -> UIView",
        "leadingView": "(Conversation) -> UIView",
        "titleView": "(Conversation) -> UIView",
        "subtitleView": "(Conversation) -> UIView",
        "tailView": "(Conversation) -> UIView",
        "emptyStateView": "() -> UIView",
        "errorStateView": "() -> UIView",
        "loadingStateView": "() -> UIView"
      },
      "formatting": {
        "datePattern": "(Conversation) -> String",
        "textFormatters": "[CometChatTextFormatter]"
      }
    },
    "events": [
      {
        "name": "ccConversationDelete",
        "payload": "Conversation",
        "description": "Fires when a conversation is deleted"
      }
    ],
    "sdkListeners": [
      "onMessageReceived",
      "onMessageEdited",
      "onMessageDeleted",
      "onTypingStarted",
      "onTypingEnded",
      "onUserOnline",
      "onUserOffline",
      "onGroupMemberJoined",
      "onGroupMemberLeft"
    ],
    "compositionExample": {
      "description": "Conversations list navigating to Messages",
      "components": ["CometChatConversations", "CometChatMessages"],
      "flow": "User taps conversation → onItemClick fires → Navigate to CometChatMessages with user/group"
    },
    "types": {
      "Conversation": {
        "conversationId": "String?",
        "conversationType": "ConversationType",
        "conversationWith": "AppEntity?",
        "lastMessage": "BaseMessage?",
        "unreadMessageCount": "Int"
      },
      "ConversationType": {
        "user": "One-on-one conversation",
        "group": "Group conversation",
        "both": "All conversation types"
      }
    }
  }
  ```
</Accordion>

| Field     | Value                    |
| --------- | ------------------------ |
| Component | `CometChatConversations` |
| Package   | `CometChatUIKitSwift`    |
| Inherits  | `UIViewController`       |

***

## Where It Fits

`CometChatConversations` serves as the main entry point for chat functionality. It displays all conversations and navigates to `CometChatMessages` when a conversation is selected.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ChatListViewController: UIViewController {
    
    private var conversationsController: CometChatConversations!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupConversations()
    }
    
    private func setupConversations() {
        conversationsController = CometChatConversations()
        
        // Handle conversation selection - navigate to messages
        conversationsController.set(onItemClick: { [weak self] conversation, indexPath in
            self?.openMessages(for: conversation)
        })
        
        navigationController?.pushViewController(conversationsController, animated: true)
    }
    
    private func openMessages(for conversation: Conversation) {
        let messagesVC = CometChatMessages()
        
        if let user = conversation.conversationWith as? User {
            messagesVC.set(user: user)
        } else if let group = conversation.conversationWith as? Group {
            messagesVC.set(group: group)
        }
        
        navigationController?.pushViewController(messagesVC, animated: true)
    }
}
```

<Frame>
  <img alt="CometChatConversations showing integration flow with conversation list navigating to messages screen" />
</Frame>

***

## Minimal Render

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()
navigationController?.pushViewController(conversations, animated: true)
```

<Frame>
  <img alt="CometChatConversations showing minimal render with default configuration displaying conversation list" />
</Frame>

***

## Filtering

Use `ConversationRequest.ConversationRequestBuilder` to filter which conversations appear in the list. The builder pattern allows chaining multiple filter conditions.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

// Create a custom request builder
let requestBuilder = ConversationRequest.ConversationRequestBuilder(limit: 30)
    .set(conversationType: .both)

let conversations = CometChatConversations(conversationRequestBuilder: requestBuilder)
```

### Filter Recipes

| Recipe                     | Code                                              |
| -------------------------- | ------------------------------------------------- |
| Show only one-on-one chats | `.set(conversationType: .user)`                   |
| Show only group chats      | `.set(conversationType: .group)`                  |
| Filter by tags             | `.withTags(true).set(tags: ["support", "sales"])` |
| Limit results              | `ConversationRequestBuilder(limit: 20)`           |
| Include user/group tags    | `.withUserAndGroupTags(true)`                     |

***

## Actions and Events

### Callback Props

#### onItemClick

Fires when a user taps on a conversation. Use this to navigate to the messages screen.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(onItemClick: { [weak self] conversation, indexPath in
    guard let self = self else { return }
    
    let messagesVC = CometChatMessages()
    
    if let user = conversation.conversationWith as? User {
        messagesVC.set(user: user)
    } else if let group = conversation.conversationWith as? Group {
        messagesVC.set(group: group)
    }
    
    self.navigationController?.pushViewController(messagesVC, animated: true)
})
```

#### onItemLongClick

Fires when a user long-presses on a conversation. Use this to show additional options like delete or mute.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(onItemLongClick: { [weak self] conversation, indexPath in
    guard let self = self else { return }
    
    let alert = UIAlertController(title: "Options", message: nil, preferredStyle: .actionSheet)
    
    alert.addAction(UIAlertAction(title: "Delete", style: .destructive) { [weak self] _ in
        self?.deleteConversation(conversation)
    })
    
    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
    self.present(alert, animated: true)
})

// Helper method to delete conversation using SDK
private func deleteConversation(_ conversation: Conversation) {
    CometChat.deleteConversation(
        conversationWith: conversation.conversationWith?.uid ?? "",
        conversationType: conversation.conversationType
    ) { success in
        print("Conversation deleted successfully")
    } onError: { error in
        print("Delete failed: \(error?.errorDescription ?? "")")
    }
}
```

#### onBack

Fires when the back button is pressed. Use this for custom navigation handling.

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

conversations.set(onBack: { [weak self] in
    self?.navigationController?.popViewController(animated: true)
})
```

#### onSelection

Fires when conversations are selected in selection mode. Returns the list of selected conversations.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()
conversations.selectionMode = .multiple

conversations.set(onSelection: { [weak self] selectedConversations in
    print("Selected \(selectedConversations.count) conversations")
})
```

#### onError

Fires when an error occurs while loading conversations.

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

conversations.set(onError: { error in
    print("Error loading conversations: \(error.errorDescription)")
})
```

#### onEmpty

Fires when the conversation list is empty.

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

conversations.set(onEmpty: {
    print("No conversations found")
})
```

#### onLoad

Fires when conversations are successfully loaded.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(onLoad: { conversations in
    print("Loaded \(conversations.count) conversations")
})
```

### Actions Reference

| Method                  | Description                             | Example                    |
| ----------------------- | --------------------------------------- | -------------------------- |
| `set(onItemClick:)`     | Triggered when a conversation is tapped | Navigate to messages       |
| `set(onItemLongClick:)` | Triggered on long press                 | Show options menu          |
| `set(onBack:)`          | Triggered when back button is pressed   | Custom navigation          |
| `set(onSelection:)`     | Triggered in selection mode             | Multi-select conversations |
| `set(onError:)`         | Triggered when an error occurs          | Show error alert           |
| `set(onEmpty:)`         | Triggered when list is empty            | Show empty state           |
| `set(onLoad:)`          | Triggered when conversations load       | Analytics tracking         |

### Global UI Events

| Event                  | Fires when                | Payload        |
| ---------------------- | ------------------------- | -------------- |
| `ccConversationDelete` | A conversation is deleted | `Conversation` |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

class MyViewController: UIViewController, CometChatConversationEventListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CometChatConversationEvents.addListener("my-listener", self)
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        CometChatConversationEvents.removeListener("my-listener")
    }
    
    func ccConversationDelete(conversation: Conversation) {
        print("Conversation deleted: \(conversation.conversationId ?? "")")
    }
}
```

### SDK Events (Real-Time, Automatic)

| SDK Listener          | Internal behavior                                          |
| --------------------- | ---------------------------------------------------------- |
| `onMessageReceived`   | Updates last message and moves conversation to top         |
| `onMessageEdited`     | Updates last message preview if edited message is latest   |
| `onMessageDeleted`    | Updates last message preview if deleted message was latest |
| `onTypingStarted`     | Shows typing indicator for the conversation                |
| `onTypingEnded`       | Hides typing indicator for the conversation                |
| `onUserOnline`        | Updates online status indicator for user conversations     |
| `onUserOffline`       | Updates offline status indicator for user conversations    |
| `onGroupMemberJoined` | Updates group member count                                 |
| `onGroupMemberLeft`   | Updates group member count                                 |

***

## Custom View Slots

| Slot               | Signature                  | Replaces                 |
| ------------------ | -------------------------- | ------------------------ |
| `listItemView`     | `(Conversation) -> UIView` | Entire conversation row  |
| `leadingView`      | `(Conversation) -> UIView` | Avatar / left section    |
| `titleView`        | `(Conversation) -> UIView` | Name / title text        |
| `subtitleView`     | `(Conversation) -> UIView` | Last message preview     |
| `tailView`         | `(Conversation) -> UIView` | Right side (time, badge) |
| `emptyStateView`   | `() -> UIView`             | Empty state display      |
| `errorStateView`   | `() -> UIView`             | Error state display      |
| `loadingStateView` | `() -> UIView`             | Loading state display    |

### listItemView

Replace the entire conversation row with a custom design.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(listItemView: { conversation in
    let customView = CustomConversationCell()
    customView.configure(with: conversation)
    return customView
})
```

```swift lines theme={null}
// CustomConversationCell.swift
class CustomConversationCell: UIView {
    
    private let avatarView = CometChatAvatar(image: UIImage())
    private let nameLabel = UILabel()
    private let messageLabel = UILabel()
    private let timeLabel = UILabel()
    
    override init(frame: CGRect) {
        super.init(frame: frame)
        setupUI()
    }
    
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
    
    private func setupUI() {
        nameLabel.font = UIFont.systemFont(ofSize: 16, weight: .semibold)
        messageLabel.font = UIFont.systemFont(ofSize: 14)
        messageLabel.textColor = UIColor.secondaryLabel
        timeLabel.font = UIFont.systemFont(ofSize: 12)
        timeLabel.textColor = UIColor.tertiaryLabel
        
        // Add subviews and constraints...
    }
    
    func configure(with conversation: Conversation) {
        if let user = conversation.conversationWith as? User {
            nameLabel.text = user.name
            avatarView.setAvatar(avatarUrl: user.avatar, with: user.name ?? "")
        } else if let group = conversation.conversationWith as? Group {
            nameLabel.text = group.name
            avatarView.setAvatar(avatarUrl: group.icon, with: group.name ?? "")
        }
        
        if let textMessage = conversation.lastMessage as? TextMessage {
            messageLabel.text = textMessage.text
        }
    }
}
```

### subtitleView

Customize just the subtitle area below the conversation name.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(subtitleView: { conversation in
    let label = UILabel()
    label.font = UIFont.systemFont(ofSize: 13)
    label.textColor = UIColor.secondaryLabel
    
    if let textMessage = conversation.lastMessage as? TextMessage {
        label.text = textMessage.text
    } else if conversation.lastMessage is MediaMessage {
        label.text = "📷 Photo"
    } else {
        label.text = "No messages yet"
    }
    
    return label
})
```

### leadingView

Customize the avatar / left section of the conversation row.

|           |                            |
| --------- | -------------------------- |
| Signature | `(Conversation) -> UIView` |
| Replaces  | Avatar / left section      |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(leadingView: { conversation in
    let containerView = UIView()
    containerView.translatesAutoresizingMaskIntoConstraints = false
    
    let avatarView = CometChatAvatar(image: UIImage())
    avatarView.translatesAutoresizingMaskIntoConstraints = false
    
    if let user = conversation.conversationWith as? User {
        avatarView.setAvatar(avatarUrl: user.avatar, with: user.name ?? "")
    } else if let group = conversation.conversationWith as? Group {
        avatarView.setAvatar(avatarUrl: group.icon, with: group.name ?? "")
    }
    
    containerView.addSubview(avatarView)
    
    // Add online indicator
    let statusIndicator = UIView()
    statusIndicator.backgroundColor = UIColor.systemGreen
    statusIndicator.layer.cornerRadius = 6
    statusIndicator.translatesAutoresizingMaskIntoConstraints = false
    containerView.addSubview(statusIndicator)
    
    NSLayoutConstraint.activate([
        avatarView.widthAnchor.constraint(equalToConstant: 48),
        avatarView.heightAnchor.constraint(equalToConstant: 48),
        avatarView.centerXAnchor.constraint(equalTo: containerView.centerXAnchor),
        avatarView.centerYAnchor.constraint(equalTo: containerView.centerYAnchor),
        statusIndicator.widthAnchor.constraint(equalToConstant: 12),
        statusIndicator.heightAnchor.constraint(equalToConstant: 12),
        statusIndicator.trailingAnchor.constraint(equalTo: avatarView.trailingAnchor),
        statusIndicator.bottomAnchor.constraint(equalTo: avatarView.bottomAnchor)
    ])
    
    return containerView
})
```

### titleView

Customize the title area that displays the conversation name.

|           |                            |
| --------- | -------------------------- |
| Signature | `(Conversation) -> UIView` |
| Replaces  | Name / title text area     |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(titleView: { conversation in
    let stackView = UIStackView()
    stackView.axis = .horizontal
    stackView.spacing = 8
    stackView.alignment = .center
    
    // Name label
    let nameLabel = UILabel()
    nameLabel.font = UIFont.systemFont(ofSize: 16, weight: .semibold)
    nameLabel.textColor = UIColor.label
    
    if let user = conversation.conversationWith as? User {
        nameLabel.text = user.name
    } else if let group = conversation.conversationWith as? Group {
        nameLabel.text = group.name
    }
    
    stackView.addArrangedSubview(nameLabel)
    
    // Add verified badge for specific users
    if let user = conversation.conversationWith as? User,
       user.metadata?["verified"] as? Bool == true {
        let badgeImage = UIImageView(image: UIImage(systemName: "checkmark.seal.fill"))
        badgeImage.tintColor = UIColor.systemBlue
        badgeImage.widthAnchor.constraint(equalToConstant: 16).isActive = true
        badgeImage.heightAnchor.constraint(equalToConstant: 16).isActive = true
        stackView.addArrangedSubview(badgeImage)
    }
    
    return stackView
})
```

### tailView

Customize the right side of the conversation row (time, unread badge). Note: The setter method is `set(trailView:)`.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(trailView: { conversation in
    let stackView = UIStackView()
    stackView.axis = .vertical
    stackView.alignment = .trailing
    stackView.spacing = 4
    
    // Time label
    let timeLabel = UILabel()
    timeLabel.font = UIFont.systemFont(ofSize: 12)
    timeLabel.textColor = UIColor.tertiaryLabel
    
    if let sentAt = conversation.lastMessage?.sentAt {
        let date = Date(timeIntervalSince1970: TimeInterval(sentAt))
        let formatter = DateFormatter()
        formatter.dateFormat = "h:mm a"
        timeLabel.text = formatter.string(from: date)
    }
    
    stackView.addArrangedSubview(timeLabel)
    
    // Unread badge
    if conversation.unreadMessageCount > 0 {
        let badge = UILabel()
        badge.text = "\(conversation.unreadMessageCount)"
        badge.font = UIFont.systemFont(ofSize: 12, weight: .bold)
        badge.textColor = UIColor.white
        badge.backgroundColor = UIColor.systemRed
        badge.textAlignment = .center
        badge.layer.cornerRadius = 10
        badge.clipsToBounds = true
        badge.widthAnchor.constraint(greaterThanOrEqualToConstant: 20).isActive = true
        badge.heightAnchor.constraint(equalToConstant: 20).isActive = true
        stackView.addArrangedSubview(badge)
    }
    
    return stackView
})
```

***

## Styling

### Style Hierarchy

1. Global styles (`CometChatConversation.style`) apply to all instances
2. Instance styles override global for specific instances

### Global Level Styling

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

// Apply global styles that affect all CometChatConversations instances
CometChatConversation.style.backgroundColor = UIColor.systemBackground
CometChatConversation.style.titleFont = UIFont.systemFont(ofSize: 17, weight: .bold)
CometChatConversation.style.titleColor = UIColor.label
CometChatConversation.style.listItemTitleTextColor = UIColor.label
CometChatConversation.style.listItemSubTitleTextColor = UIColor.secondaryLabel

// Custom avatar style
let avatarStyle = AvatarStyle()
avatarStyle.backgroundColor = UIColor(red: 0.41, green: 0.32, blue: 0.84, alpha: 1.0)
avatarStyle.cornerRadius = 8
CometChatConversation.style.avatarStyle = avatarStyle

// Custom badge style for unread count
let badgeStyle = BadgeStyle()
badgeStyle.backgroundColor = UIColor.systemRed
badgeStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 10)
CometChatConversation.style.badgeStyle = badgeStyle
```

### Instance Level Styling

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

// Create a custom style for a specific instance
var customStyle = ConversationsStyle()
customStyle.backgroundColor = UIColor(red: 0.95, green: 0.95, blue: 0.97, alpha: 1.0)
customStyle.titleColor = UIColor(red: 0.2, green: 0.2, blue: 0.2, alpha: 1.0)
customStyle.listItemBackground = UIColor.white
customStyle.listItemCornerRadius = CometChatCornerStyle(cornerRadius: 12)

let conversations = CometChatConversations()
conversations.style = customStyle
```

<Frame>
  <img alt="CometChatConversations with custom styling applied showing customized background, colors, and list item appearance" />
</Frame>

### Key Style Properties

| Property                    | Type                   | Default                                                | Description                     |
| --------------------------- | ---------------------- | ------------------------------------------------------ | ------------------------------- |
| `backgroundColor`           | `UIColor`              | `CometChatTheme.backgroundColor01`                     | Background color of the list    |
| `titleFont`                 | `UIFont?`              | `CometChatTypography.setFont(size: 17, weight: .bold)` | Font for the navigation title   |
| `titleColor`                | `UIColor?`             | `CometChatTheme.textColorPrimary`                      | Color for the navigation title  |
| `listItemTitleTextColor`    | `UIColor`              | `CometChatTheme.textColorPrimary`                      | Color for conversation names    |
| `listItemTitleFont`         | `UIFont`               | `CometChatTypography.Heading4.medium`                  | Font for conversation names     |
| `listItemSubTitleTextColor` | `UIColor`              | `CometChatTheme.textColorSecondary`                    | Color for last message preview  |
| `listItemSubTitleFont`      | `UIFont`               | `CometChatTypography.Body.regular`                     | Font for last message preview   |
| `listItemBackground`        | `UIColor`              | `.clear`                                               | Background color for list items |
| `listItemCornerRadius`      | `CometChatCornerStyle` | `CometChatCornerStyle(cornerRadius: 0)`                | Corner radius for list items    |
| `borderWidth`               | `CGFloat`              | `0`                                                    | Border width for the component  |
| `borderColor`               | `UIColor`              | `.clear`                                               | Border color for the component  |

### Customization Matrix

| What to change    | Where     | Property/API              | Example                             |
| ----------------- | --------- | ------------------------- | ----------------------------------- |
| Background color  | Style     | `backgroundColor`         | `UIColor.systemBackground`          |
| Title appearance  | Style     | `titleFont`, `titleColor` | `UIFont.boldSystemFont(ofSize: 18)` |
| List item look    | Style     | `listItemBackground`      | `UIColor(white: 0.95, alpha: 1.0)`  |
| Unread badge      | Style     | `badgeStyle`              | `BadgeStyle()` with custom colors   |
| Avatar appearance | Style     | `avatarStyle`             | `AvatarStyle()` with custom radius  |
| Hide search       | Property  | `hideSearch`              | `conversations.hideSearch = true`   |
| Hide receipts     | Property  | `hideReceipts`            | `conversations.hideReceipts = true` |
| Custom row        | View Slot | `set(listItemView:)`      | See Custom View Slots section       |

***

## Methods

### Swipe Action Methods

#### set(options:)

Sets custom swipe actions for conversation list items, replacing the default options.

```swift lines theme={null}
@discardableResult
public func set(options: ((_ conversation: Conversation?) -> [CometChatConversationOption])?) -> Self
```

| Parameter | Type                                                  | Description                                                              |
| --------- | ----------------------------------------------------- | ------------------------------------------------------------------------ |
| `options` | `((Conversation?) -> [CometChatConversationOption])?` | Closure that returns an array of swipe action options for a conversation |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.set(options: { conversation in
    var options = [CometChatConversationOption]()
    
    // Add delete option
    let deleteOption = CometChatConversationOption(
        id: "delete",
        title: "Delete",
        icon: UIImage(systemName: "trash"),
        backgroundColor: .systemRed
    ) { conv in
        // Handle delete action
        print("Delete conversation: \(conv?.conversationId ?? "")")
    }
    options.append(deleteOption)
    
    return options
})
```

#### add(options:)

Adds additional swipe actions to the existing default options.

```swift lines theme={null}
@discardableResult
public func add(options: ((_ conversation: Conversation?) -> [CometChatConversationOption])?) -> Self
```

| Parameter | Type                                                  | Description                                                    |
| --------- | ----------------------------------------------------- | -------------------------------------------------------------- |
| `options` | `((Conversation?) -> [CometChatConversationOption])?` | Closure that returns additional swipe action options to append |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

conversations.add(options: { conversation in
    var options = [CometChatConversationOption]()
    
    // Add mute option
    let muteOption = CometChatConversationOption(
        id: "mute",
        title: "Mute",
        icon: UIImage(systemName: "bell.slash"),
        backgroundColor: .systemOrange
    ) { conv in
        print("Mute conversation: \(conv?.conversationId ?? "")")
    }
    options.append(muteOption)
    
    return options
})
```

### Data Manipulation Methods

#### insert(conversation:at:)

Inserts a conversation at a specific index in the list.

```swift lines theme={null}
public func insert(conversation: Conversation, at index: Int)
```

| Parameter      | Type           | Description                                      |
| -------------- | -------------- | ------------------------------------------------ |
| `conversation` | `Conversation` | The conversation to insert                       |
| `index`        | `Int`          | The position at which to insert the conversation |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

// Insert a conversation at the top of the list
if let conversation = someConversation {
    conversations.insert(conversation: conversation, at: 0)
}
```

#### getSelectedConversations()

Returns the list of currently selected conversations when in selection mode.

```swift lines theme={null}
public func getSelectedConversations() -> [Conversation]
```

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()
conversations.selectionMode = .multiple

// Get selected conversations
let selectedConversations = conversations.getSelectedConversations()
print("Selected \(selectedConversations.count) conversations")
```

#### getConversationList()

Returns the complete list of conversations currently displayed.

```swift lines theme={null}
public func getConversationList() -> [Conversation]
```

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()

// Get all conversations in the list
let allConversations = conversations.getConversationList()
print("Total conversations: \(allConversations.count)")
```

### Connection Methods

#### connect()

Manually establishes the WebSocket connection for real-time updates. Use this when you need to reconnect after calling `disconnect()`.

```swift lines theme={null}
public func connect()
```

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

// Reconnect to receive real-time updates
conversations.connect()
```

#### disconnect()

Manually disconnects the WebSocket connection. Use this when you want to temporarily stop receiving real-time updates, such as when the view is not visible.

```swift lines theme={null}
public func disconnect()
```

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

// Disconnect when view is not visible
conversations.disconnect()

// Later, reconnect when view becomes visible again
conversations.connect()
```

### Text Formatter Methods

#### set(textFormatters:)

Sets custom text formatters for processing and displaying message text in conversation subtitles.

```swift lines theme={null}
@discardableResult
public func set(textFormatters: [CometChatTextFormatter]) -> Self
```

| Parameter        | Type                       | Description                                       |
| ---------------- | -------------------------- | ------------------------------------------------- |
| `textFormatters` | `[CometChatTextFormatter]` | Array of text formatters to apply to message text |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

// Create custom text formatters
let mentionFormatter = CometChatMentionTextFormatter()
let urlFormatter = CometChatURLTextFormatter()

conversations.set(textFormatters: [mentionFormatter, urlFormatter])
```

***

## Props

All props are optional. Sorted alphabetically.

### avatarStyle

Customizes the appearance of avatars in conversation list items.

|         |                 |
| ------- | --------------- |
| Type    | `AvatarStyle`   |
| Default | `AvatarStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

let avatarStyle = AvatarStyle()
avatarStyle.backgroundColor = UIColor.systemBlue
avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)
avatarStyle.borderWidth = 1
avatarStyle.borderColor = UIColor.systemGray4

conversations.set(avatarStyle: avatarStyle)
```

### badgeStyle

Customizes the appearance of unread message count badges.

|         |                |
| ------- | -------------- |
| Type    | `BadgeStyle`   |
| Default | `BadgeStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

let badgeStyle = BadgeStyle()
badgeStyle.backgroundColor = UIColor.systemRed
badgeStyle.textColor = UIColor.white
badgeStyle.textFont = UIFont.systemFont(ofSize: 12, weight: .bold)
badgeStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 10)

conversations.set(badgeStyle: badgeStyle)
```

### conversationRequestBuilder

Custom request builder for filtering which conversations appear.

|         |                                                   |
| ------- | ------------------------------------------------- |
| Type    | `ConversationRequest.ConversationRequestBuilder?` |
| Default | `nil`                                             |

### dateStyle

Customizes the appearance of date/time labels in conversation list items.

|         |               |
| ------- | ------------- |
| Type    | `DateStyle`   |
| Default | `DateStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

let dateStyle = DateStyle()
dateStyle.textColor = UIColor.secondaryLabel
dateStyle.textFont = UIFont.systemFont(ofSize: 12)

conversations.set(dateStyle: dateStyle)
```

### dateTimeFormatter

Custom formatter for date/time display in conversation list items.

|         |                               |
| ------- | ----------------------------- |
| Type    | `CometChatDateTimeFormatter?` |
| Default | `nil`                         |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

let dateTimeFormatter = CometChatDateTimeFormatter()
dateTimeFormatter.todayFormat = "h:mm a"
dateTimeFormatter.yesterdayFormat = "'Yesterday'"
dateTimeFormatter.otherFormat = "MMM d"

conversations.dateTimeFormatter = dateTimeFormatter
```

### customSoundForMessages

Custom sound URL for new message notifications.

|         |        |
| ------- | ------ |
| Type    | `URL?` |
| Default | `nil`  |

### disableSoundForMessages

Disables notification sounds for new messages.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### disableTyping

Disables typing indicators in the conversation list.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()
conversations.disableTyping = true
```

### hideBackButton

Hides the back button in the navigation bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideDeleteConversationOption

Hides the delete option in conversation actions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideGroupType

Hides the public/private group type icons.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideNavigationBar

Hides the entire navigation bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideReceipts

Hides read/delivered receipt indicators.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideSearch

Hides the search bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideUserStatus

Hides online/offline status indicators.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### onSearchClick

Callback triggered when the search button is clicked.

|         |                 |
| ------- | --------------- |
| Type    | `(() -> Void)?` |
| Default | `nil`           |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

conversations.set(onSearchClick: { [weak self] in
    // Handle search button click
    self?.presentSearchViewController()
})
```

### privateGroupIcon

Custom icon for private group conversations.

|         |            |
| ------- | ---------- |
| Type    | `UIImage?` |
| Default | `nil`      |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()
conversations.privateGroupIcon = UIImage(systemName: "lock.fill")
```

### protectedGroupIcon

Custom icon for password-protected group conversations.

|         |            |
| ------- | ---------- |
| Type    | `UIImage?` |
| Default | `nil`      |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()
conversations.protectedGroupIcon = UIImage(systemName: "lock.shield.fill")
```

### receiptStyle

Customizes the appearance of message receipt indicators (sent, delivered, read).

|         |                  |
| ------- | ---------------- |
| Type    | `ReceiptStyle`   |
| Default | `ReceiptStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

let receiptStyle = ReceiptStyle()
receiptStyle.sentIconTint = UIColor.systemGray
receiptStyle.deliveredIconTint = UIColor.systemGray
receiptStyle.readIconTint = UIColor.systemBlue

conversations.set(receiptStyle: receiptStyle)
```

### selectionMode

Sets the selection mode for multi-select functionality.

|         |                 |
| ------- | --------------- |
| Type    | `SelectionMode` |
| Default | `.none`         |

### statusIndicatorStyle

Customizes the appearance of online/offline status indicators.

|         |                          |
| ------- | ------------------------ |
| Type    | `StatusIndicatorStyle`   |
| Default | `StatusIndicatorStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

let statusIndicatorStyle = StatusIndicatorStyle()
statusIndicatorStyle.backgroundColor = UIColor.systemGreen
statusIndicatorStyle.borderWidth = 2
statusIndicatorStyle.borderColor = UIColor.white

conversations.set(statusIndicatorStyle: statusIndicatorStyle)
```

### textFormatters

Array of text formatters for customizing message text display.

|         |                            |
| ------- | -------------------------- |
| Type    | `[CometChatTextFormatter]` |
| Default | `[]`                       |

### typingIndicatorStyle

Customizes the appearance of typing indicators in conversation list items.

|         |                          |
| ------- | ------------------------ |
| Type    | `TypingIndicatorStyle`   |
| Default | `TypingIndicatorStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

let typingIndicatorStyle = TypingIndicatorStyle()
typingIndicatorStyle.textColor = UIColor.systemGray
typingIndicatorStyle.textFont = UIFont.italicSystemFont(ofSize: 14)

conversations.set(typingIndicatorStyle: typingIndicatorStyle)
```

***

## Events

| Event                  | Payload        | Fires when                              |
| ---------------------- | -------------- | --------------------------------------- |
| `ccConversationDelete` | `Conversation` | A conversation is deleted from the list |

***

## Date Time Formatter

Customize how timestamps appear in the conversation list using the `datePattern` callback.

### Global Level Formatting

```swift lines theme={null}
import CometChatUIKitSwift

// Set a global date pattern for all conversations instances
CometChatConversations.datePattern = { conversation in
    guard let sentAt = conversation.lastMessage?.sentAt else { return "" }
    
    let date = Date(timeIntervalSince1970: TimeInterval(sentAt))
    let formatter = DateFormatter()
    
    if Calendar.current.isDateInToday(date) {
        formatter.dateFormat = "h:mm a"
    } else if Calendar.current.isDateInYesterday(date) {
        return "Yesterday"
    } else {
        formatter.dateFormat = "MMM d"
    }
    
    return formatter.string(from: date)
}
```

### Instance Level Formatting

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

conversations.set(datePattern: { conversation in
    guard let sentAt = conversation.lastMessage?.sentAt else { return "" }
    
    let date = Date(timeIntervalSince1970: TimeInterval(sentAt))
    let formatter = DateFormatter()
    
    if Calendar.current.isDateInToday(date) {
        formatter.dateFormat = "HH:mm"  // 24-hour format
    } else if Calendar.current.isDateInYesterday(date) {
        return "Yesterday"
    } else if Calendar.current.isDate(date, equalTo: Date(), toGranularity: .weekOfYear) {
        formatter.dateFormat = "EEEE"  // Day name
    } else {
        formatter.dateFormat = "dd/MM/yy"
    }
    
    return formatter.string(from: date)
})
```

### Available Formatters

| Formatter     | Purpose                   | Default Format                        |
| ------------- | ------------------------- | ------------------------------------- |
| `datePattern` | Format for all timestamps | `h:mm a` for today, `MMM d` for older |

### Common Customizations

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

// 24-hour time format
conversations.set(datePattern: { conversation in
    guard let sentAt = conversation.lastMessage?.sentAt else { return "" }
    let date = Date(timeIntervalSince1970: TimeInterval(sentAt))
    let formatter = DateFormatter()
    formatter.dateFormat = "HH:mm"
    return formatter.string(from: date)
})

// Relative time (e.g., "2h ago")
conversations.set(datePattern: { conversation in
    guard let sentAt = conversation.lastMessage?.sentAt else { return "" }
    let date = Date(timeIntervalSince1970: TimeInterval(sentAt))
    let formatter = RelativeDateTimeFormatter()
    formatter.unitsStyle = .abbreviated
    return formatter.localizedString(for: date, relativeTo: Date())
})
```

***

## Mention Configuration

Configure how @all mentions appear in conversation list items. When a message contains an @all mention, the conversation subtitle displays the mention with a customizable label.

### setMentionAllLabel

Sets a custom label for @all mentions displayed in conversation list items.

```swift lines theme={null}
@discardableResult
public func setMentionAllLabel(_ id: String, _ label: String) -> Self
```

| Parameter | Type     | Description                                            |
| --------- | -------- | ------------------------------------------------------ |
| `id`      | `String` | The identifier for the @all mention (typically "all")  |
| `label`   | `String` | The display text shown to users when @all is mentioned |

```swift lines theme={null}
import CometChatUIKitSwift

let conversations = CometChatConversations()

// Set a custom label for @all mentions
conversations.setMentionAllLabel("all", "Everyone")
```

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class MentionConfiguredViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let conversations = CometChatConversations()
            .setMentionAllLabel("all", "Team Members")
            .set(onItemClick: { [weak self] conversation, indexPath in
                self?.openMessages(for: conversation)
            })
        
        navigationController?.pushViewController(conversations, animated: true)
    }
    
    private func openMessages(for conversation: Conversation) {
        let messagesVC = CometChatMessages()
        
        if let user = conversation.conversationWith as? User {
            messagesVC.set(user: user)
        } else if let group = conversation.conversationWith as? Group {
            messagesVC.set(group: group)
        }
        
        navigationController?.pushViewController(messagesVC, animated: true)
    }
}
```

***

## Common Patterns

### Tab bar integration

Full implementation with tab bar showing CometChatConversations in a real app:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class MainTabBarController: UITabBarController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupTabs()
    }
    
    private func setupTabs() {
        // Conversations Tab
        let conversationsVC = ConversationsContainerViewController()
        conversationsVC.tabBarItem = UITabBarItem(
            title: "Chats",
            image: UIImage(systemName: "message"),
            selectedImage: UIImage(systemName: "message.fill")
        )
        
        // Users Tab
        let usersVC = UINavigationController(rootViewController: CometChatUsers())
        usersVC.tabBarItem = UITabBarItem(
            title: "Users",
            image: UIImage(systemName: "person.2"),
            selectedImage: UIImage(systemName: "person.2.fill")
        )
        
        // Groups Tab
        let groupsVC = UINavigationController(rootViewController: CometChatGroups())
        groupsVC.tabBarItem = UITabBarItem(
            title: "Groups",
            image: UIImage(systemName: "person.3"),
            selectedImage: UIImage(systemName: "person.3.fill")
        )
        
        viewControllers = [conversationsVC, usersVC, groupsVC]
    }
}

class ConversationsContainerViewController: UINavigationController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let conversations = CometChatConversations()
        
        // Navigate to messages on tap
        conversations.set(onItemClick: { [weak self] conversation, _ in
            let messagesVC = CometChatMessages()
            
            if let user = conversation.conversationWith as? User {
                messagesVC.set(user: user)
            } else if let group = conversation.conversationWith as? Group {
                messagesVC.set(group: group)
            }
            
            self?.pushViewController(messagesVC, animated: true)
        })
        
        setViewControllers([conversations], animated: false)
    }
}
```

### Custom empty state with CTA

```swift lines theme={null}
let conversations = CometChatConversations()

conversations.set(emptyStateView: {
    let emptyView = UIView()
    
    let label = UILabel()
    label.text = "No conversations yet"
    label.textAlignment = .center
    label.textColor = .secondaryLabel
    
    let button = UIButton(type: .system)
    button.setTitle("Start a conversation", for: .normal)
    button.addTarget(self, action: #selector(startNewConversation), for: .touchUpInside)
    
    // Add subviews and constraints...
    return emptyView
})
```

### Hide all chrome — minimal list

```swift lines theme={null}
let conversations = CometChatConversations()
conversations.hideReceipts = true
conversations.hideUserStatus = true
conversations.hideGroupType = true
conversations.hideDeleteConversationOption = true
```

### Filter by conversation type

```swift lines theme={null}
// Only user conversations
let userOnlyBuilder = ConversationRequest.ConversationRequestBuilder(limit: 30)
    .set(conversationType: .user)

let conversations = CometChatConversations(conversationRequestBuilder: userOnlyBuilder)

// Only group conversations
let groupOnlyBuilder = ConversationRequest.ConversationRequestBuilder(limit: 30)
    .set(conversationType: .group)

let groupConversations = CometChatConversations(conversationRequestBuilder: groupOnlyBuilder)
```

***

## Related Components

* [Messages](/docs/ui-kit/ios/message-list) - Display messages in a conversation
* [Users](/docs/ui-kit/ios/users) - List all users to start new conversations
* [Groups](/docs/ui-kit/ios/groups) - List all groups
* [Message Composer](/docs/ui-kit/ios/message-composer) - Send messages in a conversation
* [Conversation With Messages](/docs/ui-kit/ios/conversations) - Combined conversations and messages view


# Events
Source: https://www.cometchat.com/docs/ui-kit/ios/events

Listen and respond to user actions and state changes in CometChat UI Kit

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "category": "events",
    "subscriptionPattern": {
      "addListener": "CometChat{Category}Events.addListener(listenerId, self)",
      "removeListener": "CometChat{Category}Events.removeListener(listenerId)"
    },
    "eventCategories": [
      {
        "name": "userEvents",
        "listenerClass": "CometChatUserEvents",
        "protocol": "CometChatUserEventListener",
        "events": [
          {"name": "ccUserBlocked", "payload": "User", "description": "User was blocked"},
          {"name": "ccUserUnblocked", "payload": "User", "description": "User was unblocked"}
        ]
      },
      {
        "name": "groupEvents",
        "listenerClass": "CometChatGroupEvents",
        "protocol": "CometChatGroupEventListener",
        "events": [
          {"name": "ccGroupCreated", "payload": "Group", "description": "New group created"},
          {"name": "ccGroupDeleted", "payload": "Group", "description": "Group deleted"},
          {"name": "ccGroupMemberJoined", "payload": "(User, Group)", "description": "User joined group"},
          {"name": "ccGroupLeft", "payload": "(ActionMessage, User, Group)", "description": "User left group"},
          {"name": "ccGroupMemberKicked", "payload": "(ActionMessage, User, User, Group)", "description": "Member kicked"},
          {"name": "ccGroupMemberBanned", "payload": "(ActionMessage, User, User, Group)", "description": "Member banned"},
          {"name": "ccOwnershipChanged", "payload": "(Group, GroupMember)", "description": "Ownership transferred"}
        ]
      },
      {
        "name": "conversationEvents",
        "listenerClass": "CometChatConversationEvents",
        "protocol": "CometChatConversationEventListener",
        "events": [
          {"name": "ccConversationDeleted", "payload": "Conversation", "description": "Conversation deleted"},
          {"name": "ccUpdateConversation", "payload": "Conversation", "description": "Conversation updated"}
        ]
      },
      {
        "name": "messageEvents",
        "listenerClass": "CometChatMessageEvents",
        "protocol": "CometChatMessageEventListener",
        "events": [
          {"name": "onMessageSent", "payload": "(BaseMessage, MessageStatus)", "description": "Message sent"},
          {"name": "onMessageEdit", "payload": "(BaseMessage, MessageStatus)", "description": "Message edited"},
          {"name": "onMessageDelete", "payload": "(BaseMessage, MessageStatus)", "description": "Message deleted"},
          {"name": "onMessageRead", "payload": "BaseMessage", "description": "Message read"},
          {"name": "onMessageReact", "payload": "(BaseMessage, Reaction)", "description": "Reaction added"}
        ]
      },
      {
        "name": "callEvents",
        "listenerClass": "CometChatCallEvents",
        "protocol": "CometChatCallEventListener",
        "events": [
          {"name": "onCallInitiated", "payload": "Call", "description": "Outgoing call started"},
          {"name": "onCallEnded", "payload": "Call", "description": "Call ended"},
          {"name": "onIncomingCallAccepted", "payload": "Call", "description": "Incoming call accepted"},
          {"name": "onOutgoingCallAccepted", "payload": "Call", "description": "Outgoing call accepted"}
        ]
      },
      {
        "name": "cardEvents",
        "listenerClass": "CometChatCardEvents",
        "protocol": "CometChatCardEventListener",
        "events": [
          {"name": "ccCardActionClicked", "payload": "(BaseMessage, CometChatCardActionEvent)", "description": "Action element tapped inside a card bubble"}
        ]
      }
    ]
  }
  ```
</Accordion>

Events allow different parts of your app to communicate without direct dependencies. When a user performs an action (like blocking someone, deleting a conversation, or sending a message), events are emitted so other components can react accordingly.

## How Events Work

1. **Subscribe** to events using `addListener` in `viewDidLoad`
2. **React** to events in your listener callback methods
3. **Unsubscribe** using `removeListener` in `viewWillDisappear`

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class MyViewController: UIViewController {
    
    private let listenerId = "my-unique-listener"
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Subscribe to events
        CometChatUserEvents.addListener(listenerId, self)
        CometChatGroupEvents.addListener(listenerId, self)
        CometChatConversationEvents.addListener(listenerId, self)
        CometChatMessageEvents.addListener(listenerId, self)
        CometChatCallEvents.addListener(listenerId, self)
        CometChatCardEvents.addListener(listenerId, self)
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        
        // Unsubscribe to prevent memory leaks
        CometChatUserEvents.removeListener(listenerId)
        CometChatGroupEvents.removeListener(listenerId)
        CometChatConversationEvents.removeListener(listenerId)
        CometChatMessageEvents.removeListener(listenerId)
        CometChatCallEvents.removeListener(listenerId)
        CometChatCardEvents.removeListener(listenerId)
    }
}
```

## User Events

Listen for user-related actions like blocking and unblocking.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class UserEventsViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CometChatUserEvents.addListener("user-listener", self)
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        CometChatUserEvents.removeListener("user-listener")
    }
}

extension UserEventsViewController: CometChatUserEventListener {
    
    func ccUserBlocked(user: User) {
        print("Blocked: \(user.name ?? "")")
        // Update UI - hide user from lists, disable messaging
    }
    
    func ccUserUnblocked(user: User) {
        print("Unblocked: \(user.name ?? "")")
        // Update UI - show user in lists, enable messaging
    }
}
```

### Emit User Events

Notify other components when you block/unblock a user:

```swift lines theme={null}
// After blocking a user
CometChatUserEvents.ccUserBlocked(user: blockedUser)

// After unblocking a user
CometChatUserEvents.ccUserUnblocked(user: unblockedUser)
```

### User Events Reference

| Event             | Description                          |
| ----------------- | ------------------------------------ |
| `ccUserBlocked`   | User was blocked by logged-in user   |
| `ccUserUnblocked` | User was unblocked by logged-in user |

## Group Events

Listen for group-related actions like creating groups, adding members, and role changes.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class GroupEventsViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CometChatGroupEvents.addListener("group-listener", self)
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        CometChatGroupEvents.removeListener("group-listener")
    }
}

extension GroupEventsViewController: CometChatGroupEventListener {
    
    // Group lifecycle
    func onGroupCreate(group: Group) {
        print("Group created: \(group.name ?? "")")
    }
    
    func onGroupDelete(group: Group) {
        print("Group deleted: \(group.name ?? "")")
    }
    
    func onCreateGroupClick() {
        print("Create group button tapped")
    }
    
    // Member join/leave
    func onGroupMemberJoin(joinedUser: User, joinedGroup: Group) {
        print("\(joinedUser.name ?? "") joined \(joinedGroup.name ?? "")")
    }
    
    func onGroupMemberLeave(leftUser: User, leftGroup: Group) {
        print("\(leftUser.name ?? "") left \(leftGroup.name ?? "")")
    }
    
    func onGroupMemberAdd(group: Group, members: [GroupMember], addedBy: User) {
        print("\(members.count) members added to \(group.name ?? "")")
    }
    
    // Moderation
    func onGroupMemberKick(kickedUser: User, kickedGroup: Group) {
        print("\(kickedUser.name ?? "") kicked from \(kickedGroup.name ?? "")")
    }
    
    func onGroupMemberBan(bannedUser: User, bannedGroup: Group) {
        print("\(bannedUser.name ?? "") banned from \(bannedGroup.name ?? "")")
    }
    
    func onGroupMemberUnban(unbannedUserUser: User, unbannedUserGroup: Group) {
        print("\(unbannedUserUser.name ?? "") unbanned")
    }
    
    // Role changes
    func onGroupMemberChangeScope(updatedBy: User, updatedUser: User, scopeChangedTo: CometChat.MemberScope, scopeChangedFrom: CometChat.MemberScope, group: Group) {
        print("\(updatedUser.name ?? "") role: \(scopeChangedFrom) → \(scopeChangedTo)")
    }
    
    func onOwnershipChange(group: Group?, member: GroupMember?) {
        print("Ownership transferred to \(member?.name ?? "")")
    }
}
```

### Emit Group Events

Notify other components about group actions:

```swift lines theme={null}
// Group created
CometChatGroupEvents.emitOnGroupCreate(group: newGroup)

// Group deleted
CometChatGroupEvents.emitOnGroupDelete(group: deletedGroup)

// Member joined
CometChatGroupEvents.emitOnGroupMemberJoin(joinedUser: user, joinedGroup: group)

// Member left
CometChatGroupEvents.emitOnGroupMemberLeave(leftUser: user, leftGroup: group)

// Members added
CometChatGroupEvents.emitOnGroupMemberAdd(group: group, members: newMembers, addedBy: currentUser)

// Member kicked
CometChatGroupEvents.emitOnGroupMemberKick(kickedUser: user, kickedGroup: group, kickedBy: admin)

// Member banned
CometChatGroupEvents.emitOnGroupMemberBan(bannedUser: user, bannedGroup: group, bannedBy: admin)

// Member unbanned
CometChatGroupEvents.emitOnGroupMemberUnban(unbannedUserUser: user, unbannedUserGroup: group, unbannedBy: admin)

// Role changed
CometChatGroupEvents.emitOnGroupMemberChangeScope(
    updatedBy: admin,
    updatedUser: member,
    scopeChangedTo: .admin,
    scopeChangedFrom: .participant,
    group: group
)
```

### Group Events Reference

| Event                      | Description                 |
| -------------------------- | --------------------------- |
| `onGroupCreate`            | New group created           |
| `onGroupDelete`            | Group deleted               |
| `onCreateGroupClick`       | Create group button tapped  |
| `onGroupMemberJoin`        | User joined a group         |
| `onGroupMemberLeave`       | User left a group           |
| `onGroupMemberAdd`         | Members added to group      |
| `onGroupMemberKick`        | Member kicked from group    |
| `onGroupMemberBan`         | Member banned from group    |
| `onGroupMemberUnban`       | Member unbanned             |
| `onGroupMemberChangeScope` | Member role changed         |
| `onOwnershipChange`        | Group ownership transferred |

## Conversation Events

Listen for conversation-level actions like delete and update.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ConversationEventsViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CometChatConversationEvents.addListener("conversation-listener", self)
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        CometChatConversationEvents.removeListener("conversation-listener")
    }
}

extension ConversationEventsViewController: CometChatConversationEventListener {
    
    func ccConversationDeleted(conversation: Conversation) {
        print("Conversation deleted: \(conversation.conversationId ?? "")")
        // Remove from local list, update UI
    }
    
    func ccUpdateConversation(conversation: Conversation) {
        print("Conversation updated: \(conversation.conversationId ?? "")")
        // Refresh conversation data in UI
    }
}
```

### Emit Conversation Events

```swift lines theme={null}
// Conversation deleted
CometChatConversationEvents.ccConversationDelete(conversation: deletedConversation)

// Conversation updated
CometChatConversationEvents.ccUpdateConversation(conversation: updatedConversation)
```

### Conversation Events Reference

| Event                   | Description              |
| ----------------------- | ------------------------ |
| `ccConversationDeleted` | Conversation was deleted |
| `ccUpdateConversation`  | Conversation was updated |

## Message Events

Listen for message-related actions like send, edit, delete, and reactions.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class MessageEventsViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CometChatMessageEvents.addListener("message-listener", self)
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        CometChatMessageEvents.removeListener("message-listener")
    }
}

extension MessageEventsViewController: CometChatMessageEventListener {
    
    // Message lifecycle
    func onMessageSent(message: BaseMessage, status: MessageStatus) {
        switch status {
        case .inProgress:
            print("Sending...")
        case .success:
            print("Message sent: \(message.id)")
        case .error:
            print("Send failed")
        @unknown default:
            break
        }
    }
    
    func onMessageEdit(message: BaseMessage, status: MessageStatus) {
        print("Message edited: \(message.id)")
    }
    
    func onMessageDelete(message: BaseMessage, status: MessageStatus) {
        print("Message deleted: \(message.id)")
    }
    
    func onMessageRead(message: BaseMessage) {
        print("Message read: \(message.id)")
    }
    
    func onMessageReply(message: BaseMessage, status: MessageStatus) {
        print("Reply sent to: \(message.id)")
    }
    
    // Reactions
    func onMessageReact(message: BaseMessage, reaction: CometChatMessageReaction) {
        print("Reaction: \(reaction.reaction ?? "")")
    }
    
    func onLiveReaction(reaction: TransientMessage) {
        print("Live reaction received")
    }
    
    // Thread updates
    func onParentMessageUpdate(message: BaseMessage) {
        print("Thread parent updated: \(message.id)")
    }
    
    // Navigation
    func onViewInformation(user: User) {
        print("View user info: \(user.name ?? "")")
    }
    
    func onViewInformation(group: Group) {
        print("View group info: \(group.name ?? "")")
    }
    
    // Calls from message screen
    func onVoiceCall(user: User) {
        print("Voice call to: \(user.name ?? "")")
    }
    
    func onVideoCall(user: User) {
        print("Video call to: \(user.name ?? "")")
    }
    
    func onVoiceCall(group: Group) {
        print("Group voice call: \(group.name ?? "")")
    }
    
    func onVideoCall(group: Group) {
        print("Group video call: \(group.name ?? "")")
    }
    
    // Errors
    func onMessageError(error: CometChatException) {
        print("Error: \(error.errorDescription)")
    }
}
```

### Emit Message Events

```swift lines theme={null}
// Message sent (with status)
CometChatMessageEvents.emitOnMessageSent(message: sentMessage, status: .success)

// Message edited
CometChatMessageEvents.emitOnMessageEdit(message: editedMessage, status: .success)

// Message deleted
CometChatMessageEvents.emitOnMessageDelete(message: deletedMessage)

// Message read
CometChatMessageEvents.emitOnMessageRead(message: readMessage)

// Live reaction
CometChatMessageEvents.emitOnLiveReaction(reaction: transientMessage)

// View user/group info
CometChatMessageEvents.emitOnViewInformation(user: selectedUser)

// Thread parent updated
CometChatMessageEvents.emitOnParentMessageUpdate(message: parentMessage)
```

### Message Events Reference

| Event                   | Description                                  |
| ----------------------- | -------------------------------------------- |
| `onMessageSent`         | Message sent (inProgress, success, or error) |
| `onMessageEdit`         | Message edited                               |
| `onMessageDelete`       | Message deleted                              |
| `onMessageRead`         | Message marked as read                       |
| `onMessageReply`        | Reply sent to a message                      |
| `onMessageReact`        | Reaction added to message                    |
| `onLiveReaction`        | Live reaction sent                           |
| `onParentMessageUpdate` | Thread parent message updated                |
| `onViewInformation`     | Info button tapped (user or group)           |
| `onVoiceCall`           | Voice call initiated                         |
| `onVideoCall`           | Video call initiated                         |
| `onMessageError`        | Message operation failed                     |

## Card Events

Listen for taps on interactive elements (buttons, links) inside card bubbles. The UI Kit renders card bubbles automatically (`CometChatCardBubble`) and emits `ccCardActionClicked` when a user taps an action inside one — so a single listener handles every card action across your app. The source `message` is a `CardMessage` for standalone [card messages](/docs/sdk/ios/campaigns#card-messages) and an `AIAssistantMessage` for cards embedded in AI agent replies.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK
import CometChatCardsSwift

class CardEventsViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        CometChatCardEvents.addListener("card-listener", self)
    }

    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        CometChatCardEvents.removeListener("card-listener")
    }
}

extension CardEventsViewController: CometChatCardEventListener {

    func ccCardActionClicked(message: BaseMessage, action: CometChatCardActionEvent) {
        // `message` is a CardMessage (standalone) or AIAssistantMessage (agent card)
        print("Action: \(action.action), element: \(action.elementId), message: \(message.id)")
        // Handle the tap — navigate, open a URL, call an API, etc.
    }
}
```

`CometChatCardActionEvent` (from `CometChatCardsSwift`) carries:

| Property    | Type                  | Description                                             |
| ----------- | --------------------- | ------------------------------------------------------- |
| `action`    | `CometChatCardAction` | The action the tapped element is configured to perform. |
| `elementId` | `String`              | Identifier of the card element that was tapped.         |
| `cardJson`  | `String`              | The raw card schema JSON of the rendered card.          |

### Card Events Reference

| Event                 | Description                                                                                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ccCardActionClicked` | Triggered when a user taps an action element inside a card bubble. Provides the source `message` (`CardMessage` or `AIAssistantMessage`) and a `CometChatCardActionEvent`. |

## Call Events

Listen for call-related actions like initiating, accepting, and ending calls.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class CallEventsViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CometChatCallEvents.addListener("call-listener", self)
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        CometChatCallEvents.removeListener("call-listener")
    }
}

extension CallEventsViewController: CometChatCallEventListener {
    
    // Outgoing calls
    func onCallInitiated(call: Call) {
        print("Calling: \(call.receiverUid)")
    }
    
    func onOutgoingCallAccepted(call: Call) {
        print("Call accepted by recipient")
    }
    
    func onOutgoingCallRejected(call: Call) {
        print("Call rejected by recipient")
    }
    
    // Incoming calls
    func onIncomingCallAccepted(call: Call) {
        print("You accepted the call")
    }
    
    func onIncomingCallRejected(call: Call) {
        print("You rejected the call")
    }
    
    // Call ended
    func onCallEnded(call: Call) {
        print("Call ended")
    }
}
```

### Emit Call Events

```swift lines theme={null}
// Call initiated
CometChatCallEvents.emitOnCallInitiated(call: outgoingCall)

// Call ended
CometChatCallEvents.emitOnCallEnded(call: endedCall)

// Incoming call accepted
CometChatCallEvents.emitOnIncomingCallAccepted(call: acceptedCall)

// Incoming call rejected
CometChatCallEvents.emitOnIncomingCallRejected(call: rejectedCall)

// Outgoing call accepted
CometChatCallEvents.emitOnOutgoingCallAccepted(call: acceptedCall)

// Outgoing call rejected
CometChatCallEvents.emitOnOutgoingCallRejected(call: rejectedCall)
```

### Call Events Reference

| Event                    | Description                   |
| ------------------------ | ----------------------------- |
| `onCallInitiated`        | Outgoing call started         |
| `onOutgoingCallAccepted` | Recipient accepted the call   |
| `onOutgoingCallRejected` | Recipient rejected the call   |
| `onIncomingCallAccepted` | You accepted an incoming call |
| `onIncomingCallRejected` | You rejected an incoming call |
| `onCallEnded`            | Call ended (any reason)       |

## Complete Example: App-Wide Event Manager

Create a centralized event manager to handle events across your entire app:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

// MARK: - Singleton Event Manager
class ChatEventManager {
    
    static let shared = ChatEventManager()
    private let listenerId = "app-event-manager"
    
    private init() {}
    
    func startListening() {
        CometChatUserEvents.addListener(listenerId, self)
        CometChatGroupEvents.addListener(listenerId, self)
        CometChatConversationEvents.addListener(listenerId, self)
        CometChatMessageEvents.addListener(listenerId, self)
        CometChatCallEvents.addListener(listenerId, self)
    }
    
    func stopListening() {
        CometChatUserEvents.removeListener(listenerId)
        CometChatGroupEvents.removeListener(listenerId)
        CometChatConversationEvents.removeListener(listenerId)
        CometChatMessageEvents.removeListener(listenerId)
        CometChatCallEvents.removeListener(listenerId)
    }
}

// MARK: - User Events
extension ChatEventManager: CometChatUserEventListener {
    func onUserBlock(user: User) {
        NotificationCenter.default.post(name: .userBlocked, object: user)
    }
    
    func onUserUnblock(user: User) {
        NotificationCenter.default.post(name: .userUnblocked, object: user)
    }
}

// MARK: - Group Events
extension ChatEventManager: CometChatGroupEventListener {
    func onGroupCreate(group: Group) {
        NotificationCenter.default.post(name: .groupCreated, object: group)
    }
    
    func onGroupDelete(group: Group) {
        NotificationCenter.default.post(name: .groupDeleted, object: group)
    }
    
    func onGroupMemberJoin(joinedUser: User, joinedGroup: Group) {
        NotificationCenter.default.post(name: .memberJoined, object: nil, 
            userInfo: ["user": joinedUser, "group": joinedGroup])
    }
    
    func onGroupMemberLeave(leftUser: User, leftGroup: Group) {
        NotificationCenter.default.post(name: .memberLeft, object: nil,
            userInfo: ["user": leftUser, "group": leftGroup])
    }
    
    // Implement other required methods...
    func onGroupMemberAdd(group: Group, members: [GroupMember], addedBy: User) {}
    func onGroupMemberKick(kickedUser: User, kickedGroup: Group) {}
    func onGroupMemberBan(bannedUser: User, bannedGroup: Group) {}
    func onGroupMemberUnban(unbannedUserUser: User, unbannedUserGroup: Group) {}
    func onGroupMemberChangeScope(updatedBy: User, updatedUser: User, scopeChangedTo: CometChat.MemberScope, scopeChangedFrom: CometChat.MemberScope, group: Group) {}
    func onOwnershipChange(group: Group?, member: GroupMember?) {}
    func onCreateGroupClick() {}
}

// MARK: - Conversation Events
extension ChatEventManager: CometChatConversationEventListener {
    func ccConversationDeleted(conversation: Conversation) {
        NotificationCenter.default.post(name: .conversationDeleted, object: conversation)
    }
    
    func ccUpdateConversation(conversation: Conversation) {
        NotificationCenter.default.post(name: .conversationUpdated, object: conversation)
    }
}

// MARK: - Message Events
extension ChatEventManager: CometChatMessageEventListener {
    func onMessageSent(message: BaseMessage, status: MessageStatus) {
        if status == .success {
            NotificationCenter.default.post(name: .messageSent, object: message)
        }
    }
    
    // Implement other required methods...
    func onMessageEdit(message: BaseMessage, status: MessageStatus) {}
    func onMessageDelete(message: BaseMessage, status: MessageStatus) {}
    func onMessageRead(message: BaseMessage) {}
    func onLiveReaction(reaction: TransientMessage) {}
    func onMessageReact(message: BaseMessage, reaction: CometChatMessageReaction) {}
    func onParentMessageUpdate(message: BaseMessage) {}
    func onViewInformation(user: User) {}
    func onViewInformation(group: Group) {}
    func onVoiceCall(user: User) {}
    func onVideoCall(user: User) {}
    func onVoiceCall(group: Group) {}
    func onVideoCall(group: Group) {}
    func onMessageError(error: CometChatException) {}
    func onMessageReply(message: BaseMessage, status: MessageStatus) {}
}

// MARK: - Call Events
extension ChatEventManager: CometChatCallEventListener {
    func onCallInitiated(call: Call) {
        NotificationCenter.default.post(name: .callStarted, object: call)
    }
    
    func onCallEnded(call: Call) {
        NotificationCenter.default.post(name: .callEnded, object: call)
    }
    
    func onIncomingCallAccepted(call: Call) {}
    func onIncomingCallRejected(call: Call) {}
    func onOutgoingCallAccepted(call: Call) {}
    func onOutgoingCallRejected(call: Call) {}
}

// MARK: - Notification Names
extension Notification.Name {
    static let userBlocked = Notification.Name("userBlocked")
    static let userUnblocked = Notification.Name("userUnblocked")
    static let groupCreated = Notification.Name("groupCreated")
    static let groupDeleted = Notification.Name("groupDeleted")
    static let memberJoined = Notification.Name("memberJoined")
    static let memberLeft = Notification.Name("memberLeft")
    static let conversationDeleted = Notification.Name("conversationDeleted")
    static let conversationUpdated = Notification.Name("conversationUpdated")
    static let messageSent = Notification.Name("messageSent")
    static let callStarted = Notification.Name("callStarted")
    static let callEnded = Notification.Name("callEnded")
}
```

### Using the Event Manager

```swift lines theme={null}
// AppDelegate.swift
class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        // Start listening for events app-wide
        ChatEventManager.shared.startListening()
        
        return true
    }
}

// Any ViewController
class MyViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Listen for specific events via NotificationCenter
        NotificationCenter.default.addObserver(
            self,
            selector: #selector(handleUserBlocked),
            name: .userBlocked,
            object: nil
        )
    }
    
    @objc private func handleUserBlocked(_ notification: Notification) {
        guard let user = notification.object as? User else { return }
        print("User blocked: \(user.name ?? "")")
        // Update your UI
    }
    
    deinit {
        NotificationCenter.default.removeObserver(self)
    }
}
```

## Best Practices

1. **Always remove listeners** - Call `removeListener` in `viewWillDisappear` to prevent memory leaks

2. **Use unique listener IDs** - Avoid conflicts between components by using descriptive, unique IDs

3. **Update UI on main thread** - Dispatch UI updates to the main thread when handling events

4. **Don't emit unnecessarily** - Only emit events when state actually changes

5. **Use a central manager** - For app-wide event handling, create a singleton manager

***

## Next Steps

<CardGroup>
  <Card title="Methods" href="/ui-kit/ios/methods">
    Reference for UI Kit wrapper methods.
  </Card>

  <Card title="Message List" href="/ui-kit/ios/message-list">
    Display and customize chat messages.
  </Card>

  <Card title="Conversations" href="/ui-kit/ios/conversations">
    Manage conversation lists.
  </Card>

  <Card title="Groups" href="/ui-kit/ios/groups">
    Work with group chat functionality.
  </Card>
</CardGroup>

***


# Group Members
Source: https://www.cometchat.com/docs/ui-kit/ios/group-members

Display and manage CometChat iOS UI Kit group members with roles, search, kick, ban, scope changes, and permission-based actions.

The `CometChatGroupMembers` component displays all members of a group with their roles (owner, admin, moderator, participant). It supports member management actions like kick, ban, and role changes based on the logged-in user's permissions.

<Frame>
  <img alt="CometChatGroupMembers showing a list of group members with their avatars, names, and role badges indicating owner, admin, moderator, and participant status" />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatGroupMembers",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "description": "Displays all members of a group with their roles and supports member management actions like kick, ban, and role changes.",
    "inherits": "UIViewController",
    "primaryOutput": {
      "callback": "onItemClick",
      "type": "(GroupMember, IndexPath) -> Void"
    },
    "props": {
      "data": {
        "group": {
          "type": "Group",
          "required": true,
          "note": "The group whose members to display"
        },
        "groupMembersRequestBuilder": {
          "type": "GroupMembersRequest.GroupMembersRequestBuilder?",
          "default": "nil",
          "note": "Custom request builder for filtering members"
        }
      },
      "callbacks": {
        "onItemClick": "(GroupMember, IndexPath) -> Void",
        "onItemLongClick": "(GroupMember, IndexPath) -> Void",
        "onBack": "() -> Void",
        "onSelection": "([GroupMember]) -> Void",
        "onSelectedItemProceed": "([GroupMember]) -> Void",
        "onError": "(CometChatException) -> Void",
        "onEmpty": "() -> Void",
        "onLoad": "([GroupMember]) -> Void"
      },
      "visibility": {
        "hideSearch": { "type": "Bool", "default": false },
        "hideNavigationBar": { "type": "Bool", "default": false },
        "hideBackIcon": { "type": "Bool", "default": false },
        "hideUserStatus": { "type": "Bool", "default": false },
        "hideKickMemberOption": { "type": "Bool", "default": false },
        "hideBanMemberOption": { "type": "Bool", "default": false },
        "hideScopeChangeOption": { "type": "Bool", "default": false },
        "hideErrorView": { "type": "Bool", "default": false },
        "hideLoadingState": { "type": "Bool", "default": false }
      },
      "selection": {
        "selectionMode": { "type": "SelectionMode", "default": ".none" }
      },
      "styling": {
        "avatarStyle": { "type": "AvatarStyle", "default": "AvatarStyle()" },
        "statusIndicatorStyle": { "type": "StatusIndicatorStyle", "default": "StatusIndicatorStyle()" }
      },
      "viewSlots": {
        "listItemView": "(GroupMember?) -> UIView",
        "leadingView": "(GroupMember?) -> UIView",
        "titleView": "(GroupMember?) -> UIView",
        "subtitleView": "(GroupMember?) -> UIView",
        "trailView": "(GroupMember?) -> UIView",
        "emptyStateView": "UIView",
        "errorStateView": "UIView",
        "loadingStateView": "UIView"
      }
    },
    "methods": {
      "swipeActions": {
        "set(options:)": "((Group, GroupMember?) -> [CometChatGroupMemberOption])? - Sets custom swipe actions",
        "add(options:)": "((Group, GroupMember?) -> [CometChatGroupMemberOption])? - Adds additional swipe actions"
      },
      "dataManipulation": {
        "add(groupMember:)": "GroupMember - Adds a member to the list",
        "update(groupMember:)": "GroupMember - Updates a member in the list",
        "remove(groupMember:)": "GroupMember - Removes a member from the list",
        "insert(groupMember:at:)": "GroupMember, Int - Inserts a member at a specific index",
        "clearList()": "Void - Removes all members from the list",
        "size()": "Int - Returns the number of members in the list"
      }
    },
    "events": [
      {
        "name": "ccGroupMemberKicked",
        "payload": "{ user: User, group: Group }",
        "description": "Fires when a member is kicked"
      },
      {
        "name": "ccGroupMemberBanned",
        "payload": "{ user: User, group: Group }",
        "description": "Fires when a member is banned"
      },
      {
        "name": "ccGroupMemberScopeChanged",
        "payload": "{ user: User, group: Group, scope: MemberScope }",
        "description": "Fires when a member's scope is changed"
      }
    ],
    "sdkListeners": [
      "onGroupMemberKicked",
      "onGroupMemberBanned",
      "onGroupMemberUnbanned",
      "onGroupMemberScopeChanged",
      "onMemberAddedToGroup"
    ],
    "compositionExample": {
      "description": "GroupMembers is typically accessed from group details or settings",
      "components": ["CometChatGroups", "CometChatGroupMembers", "CometChatMessages"],
      "flow": "User opens group → views members → taps member → starts direct chat"
    },
    "types": {
      "GroupMember": {
        "uid": "String",
        "name": "String",
        "avatar": "String?",
        "scope": "MemberScope",
        "joinedAt": "Int"
      },
      "MemberScope": {
        "owner": "Group owner with full permissions",
        "admin": "Administrator with management permissions",
        "moderator": "Moderator with limited management",
        "participant": "Regular member"
      }
    }
  }
  ```
</Accordion>

| Field     | Value                   |
| --------- | ----------------------- |
| Component | `CometChatGroupMembers` |
| Package   | `CometChatUIKitSwift`   |
| Inherits  | `UIViewController`      |

***

## Where It Fits

`CometChatGroupMembers` displays all members of a specific group. It's typically accessed from group details or settings screens.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class GroupDetailViewController: UIViewController {
    
    var group: Group!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupGroupMembers()
    }
    
    private func setupGroupMembers() {
        let groupMembers = CometChatGroupMembers(group: group)
        
        // Handle member tap - start direct chat
        groupMembers.set(onItemClick: { [weak self] member, indexPath in
            self?.startDirectChat(with: member)
        })
        
        let navController = UINavigationController(rootViewController: groupMembers)
        present(navController, animated: true)
    }
    
    private func startDirectChat(with member: GroupMember) {
        let messagesVC = CometChatMessages()
        messagesVC.set(user: member)
        navigationController?.pushViewController(messagesVC, animated: true)
    }
}
```

<Frame>
  <img alt="CometChatGroupMembers displaying group members in a navigation context with search functionality and member details" />
</Frame>

***

## Minimal Render

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)
let navController = UINavigationController(rootViewController: groupMembers)
present(navController, animated: true)
```

<Frame>
  <img alt="CometChatGroupMembers showing minimal render with default configuration displaying member list" />
</Frame>

***

## Filtering

Use `GroupMembersRequest.GroupMembersRequestBuilder` to filter which members appear in the list.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

// Create a custom request builder
let requestBuilder = GroupMembersRequest.GroupMembersRequestBuilder(guid: group.guid)
    .set(limit: 30)
    .set(scopes: ["admin", "moderator"])

let groupMembers = CometChatGroupMembers(
    group: group,
    groupMembersRequestBuilder: requestBuilder
)
```

### Filter Recipes

| Recipe                | Code                                   |
| --------------------- | -------------------------------------- |
| Admins only           | `.set(scopes: ["admin"])`              |
| Admins and moderators | `.set(scopes: ["admin", "moderator"])` |
| Search by name        | `.set(searchKeyword: "john")`          |
| Limit results         | `.set(limit: 20)`                      |

***

## Actions and Events

### Callback Props

#### onItemClick

Fires when a user taps on a member. Use this to start a direct chat or view profile.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

groupMembers.set(onItemClick: { [weak self] member, indexPath in
    guard let self = self else { return }
    
    let messagesVC = CometChatMessages()
    messagesVC.set(user: member)
    self.navigationController?.pushViewController(messagesVC, animated: true)
})
```

#### onItemLongClick

Fires when a user long-presses on a member. Use this to show member options.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

groupMembers.set(onItemLongClick: { [weak self] member, indexPath in
    guard let self = self else { return }
    
    let alert = UIAlertController(title: member.name, message: nil, preferredStyle: .actionSheet)
    
    alert.addAction(UIAlertAction(title: "Message", style: .default) { _ in
        // Start direct chat
    })
    
    alert.addAction(UIAlertAction(title: "View Profile", style: .default) { _ in
        // View profile
    })
    
    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
    self.present(alert, animated: true)
})
```

#### onBack

Fires when the back button is pressed.

```swift lines theme={null}
import CometChatUIKitSwift

let groupMembers = CometChatGroupMembers(group: group)

groupMembers.set(onBack: { [weak self] in
    self?.navigationController?.popViewController(animated: true)
})
```

#### onSelection

Fires when members are selected in selection mode.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)
groupMembers.selectionMode = .multiple

groupMembers.set(onSelection: { [weak self] selectedMembers in
    print("Selected \(selectedMembers.count) members")
})
```

#### onError

Fires when an error occurs while loading members.

```swift lines theme={null}
import CometChatUIKitSwift

let groupMembers = CometChatGroupMembers(group: group)

groupMembers.set(onError: { error in
    print("Error loading members: \(error.errorDescription)")
})
```

#### onEmpty

Fires when the member list is empty.

```swift lines theme={null}
import CometChatUIKitSwift

let groupMembers = CometChatGroupMembers(group: group)

groupMembers.set(onEmpty: {
    print("No members found")
})
```

#### onLoad

Fires when members are successfully loaded.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

groupMembers.set(onLoad: { members in
    print("Loaded \(members.count) members")
})
```

### Actions Reference

| Method                  | Description                           | Example              |
| ----------------------- | ------------------------------------- | -------------------- |
| `set(onItemClick:)`     | Triggered when a member is tapped     | Start direct chat    |
| `set(onItemLongClick:)` | Triggered on long press               | Show options menu    |
| `set(onBack:)`          | Triggered when back button is pressed | Custom navigation    |
| `set(onSelection:)`     | Triggered in selection mode           | Multi-select members |
| `set(onError:)`         | Triggered when an error occurs        | Show error alert     |
| `set(onEmpty:)`         | Triggered when list is empty          | Show empty state     |
| `set(onLoad:)`          | Triggered when members load           | Analytics tracking   |

### Global UI Events

| Event                       | Fires when                 | Payload                    |
| --------------------------- | -------------------------- | -------------------------- |
| `ccGroupMemberKicked`       | A member is kicked         | `User, Group`              |
| `ccGroupMemberBanned`       | A member is banned         | `User, Group`              |
| `ccGroupMemberScopeChanged` | A member's role is changed | `User, Group, MemberScope` |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

class MyViewController: UIViewController, CometChatGroupEventListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CometChatGroupEvents.addListener("my-listener", self)
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        CometChatGroupEvents.removeListener("my-listener")
    }
    
    func onGroupMemberKick(kickedUser: User, kickedGroup: Group) {
        print("\(kickedUser.name ?? "") was kicked from \(kickedGroup.name ?? "")")
    }
    
    func onGroupMemberBan(bannedUser: User, bannedGroup: Group) {
        print("\(bannedUser.name ?? "") was banned from \(bannedGroup.name ?? "")")
    }
    
    func onGroupMemberChangeScope(updatedBy: User, updatedUser: User, scopeChangedTo: CometChat.MemberScope, scopeChangedFrom: CometChat.MemberScope, group: Group) {
        print("\(updatedUser.name ?? "") role changed to \(scopeChangedTo)")
    }
}
```

### SDK Events (Real-Time, Automatic)

| SDK Listener                | Internal behavior         |
| --------------------------- | ------------------------- |
| `onGroupMemberKicked`       | Removes member from list  |
| `onGroupMemberBanned`       | Removes member from list  |
| `onGroupMemberUnbanned`     | Updates member info       |
| `onGroupMemberScopeChanged` | Updates member role badge |
| `onMemberAddedToGroup`      | Adds new member to list   |

***

## Custom View Slots

| Slot               | Setter Method        | Signature                  | Replaces                |
| ------------------ | -------------------- | -------------------------- | ----------------------- |
| `listItemView`     | `set(listItemView:)` | `(GroupMember?) -> UIView` | Entire member row       |
| `leadingView`      | `set(leadingView:)`  | `(GroupMember?) -> UIView` | Avatar / left section   |
| `titleView`        | `set(titleView:)`    | `(GroupMember?) -> UIView` | Name / title text       |
| `subtitleView`     | `set(subtitleView:)` | `(GroupMember?) -> UIView` | Role / subtitle text    |
| `trailView`        | `set(trailView:)`    | `(GroupMember?) -> UIView` | Right side (role badge) |
| `emptyStateView`   | -                    | `UIView`                   | Empty state display     |
| `errorStateView`   | -                    | `UIView`                   | Error state display     |
| `loadingStateView` | -                    | `UIView`                   | Loading state display   |

### set(titleView:)

Replaces the default title view (member name) with a custom implementation.

|           |                            |
| --------- | -------------------------- |
| Signature | `(GroupMember?) -> UIView` |
| Replaces  | Member name / title text   |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

groupMembers.set(titleView: { member in
    let containerView = UIView()
    
    let nameLabel = UILabel()
    nameLabel.font = UIFont.systemFont(ofSize: 16, weight: .semibold)
    nameLabel.textColor = UIColor.label
    nameLabel.text = member?.name ?? "Unknown"
    nameLabel.translatesAutoresizingMaskIntoConstraints = false
    
    let roleLabel = UILabel()
    roleLabel.font = UIFont.systemFont(ofSize: 10, weight: .medium)
    roleLabel.textColor = UIColor.white
    roleLabel.textAlignment = .center
    roleLabel.layer.cornerRadius = 4
    roleLabel.clipsToBounds = true
    roleLabel.translatesAutoresizingMaskIntoConstraints = false
    
    // Set role badge color based on scope
    switch member?.scope {
    case .owner:
        roleLabel.text = " Owner "
        roleLabel.backgroundColor = UIColor.systemOrange
    case .admin:
        roleLabel.text = " Admin "
        roleLabel.backgroundColor = UIColor.systemPurple
    case .moderator:
        roleLabel.text = " Mod "
        roleLabel.backgroundColor = UIColor.systemBlue
    default:
        roleLabel.text = ""
        roleLabel.backgroundColor = .clear
    }
    
    containerView.addSubview(nameLabel)
    containerView.addSubview(roleLabel)
    
    NSLayoutConstraint.activate([
        nameLabel.leadingAnchor.constraint(equalTo: containerView.leadingAnchor),
        nameLabel.centerYAnchor.constraint(equalTo: containerView.centerYAnchor),
        
        roleLabel.leadingAnchor.constraint(equalTo: nameLabel.trailingAnchor, constant: 8),
        roleLabel.centerYAnchor.constraint(equalTo: containerView.centerYAnchor)
    ])
    
    return containerView
})
```

### set(leadingView:)

Replaces the default leading view (avatar) with a custom implementation.

|           |                            |
| --------- | -------------------------- |
| Signature | `(GroupMember?) -> UIView` |
| Replaces  | Avatar / left section      |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

groupMembers.set(leadingView: { member in
    let containerView = UIView()
    containerView.translatesAutoresizingMaskIntoConstraints = false
    
    // Create avatar
    let avatar = CometChatAvatar(image: UIImage())
    avatar.setAvatar(avatarUrl: member?.avatar, with: member?.name ?? "")
    avatar.translatesAutoresizingMaskIntoConstraints = false
    
    // Create role badge overlay
    let badgeView = UIView()
    badgeView.layer.cornerRadius = 10
    badgeView.layer.borderWidth = 2
    badgeView.layer.borderColor = UIColor.white.cgColor
    badgeView.translatesAutoresizingMaskIntoConstraints = false
    
    // Set badge color based on scope
    switch member?.scope {
    case .owner:
        badgeView.backgroundColor = UIColor.systemOrange
    case .admin:
        badgeView.backgroundColor = UIColor.systemPurple
    case .moderator:
        badgeView.backgroundColor = UIColor.systemBlue
    default:
        badgeView.backgroundColor = UIColor.systemGray
    }
    
    let badgeIcon = UIImageView(image: UIImage(systemName: "star.fill"))
    badgeIcon.tintColor = .white
    badgeIcon.translatesAutoresizingMaskIntoConstraints = false
    badgeView.addSubview(badgeIcon)
    
    containerView.addSubview(avatar)
    containerView.addSubview(badgeView)
    
    NSLayoutConstraint.activate([
        avatar.topAnchor.constraint(equalTo: containerView.topAnchor),
        avatar.leadingAnchor.constraint(equalTo: containerView.leadingAnchor),
        avatar.widthAnchor.constraint(equalToConstant: 40),
        avatar.heightAnchor.constraint(equalToConstant: 40),
        
        badgeView.widthAnchor.constraint(equalToConstant: 20),
        badgeView.heightAnchor.constraint(equalToConstant: 20),
        badgeView.bottomAnchor.constraint(equalTo: avatar.bottomAnchor, constant: 2),
        badgeView.trailingAnchor.constraint(equalTo: avatar.trailingAnchor, constant: 2),
        
        badgeIcon.centerXAnchor.constraint(equalTo: badgeView.centerXAnchor),
        badgeIcon.centerYAnchor.constraint(equalTo: badgeView.centerYAnchor),
        badgeIcon.widthAnchor.constraint(equalToConstant: 12),
        badgeIcon.heightAnchor.constraint(equalToConstant: 12)
    ])
    
    return containerView
})
```

### subtitleView

Customize the subtitle area below the member name.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

groupMembers.set(subtitleView: { member in
    let label = UILabel()
    label.font = UIFont.systemFont(ofSize: 12)
    label.textColor = UIColor.secondaryLabel
    
    guard let member = member else { return label }
    
    let date = Date(timeIntervalSince1970: Double(member.joinedAt))
    let formatter = DateFormatter()
    formatter.dateStyle = .medium
    label.text = "Joined: \(formatter.string(from: date))"
    
    return label
})
```

### tailView

Customize the right side of the member row (role badge). Note: The setter method is `set(trailView:)`.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

groupMembers.set(trailView: { member in
    let badge = UILabel()
    badge.font = UIFont.systemFont(ofSize: 10, weight: .semibold)
    badge.textAlignment = .center
    badge.layer.cornerRadius = 10
    badge.clipsToBounds = true
    
    guard let member = member else { return badge }
    
    switch member.scope {
    case .owner:
        badge.text = "Owner"
        badge.textColor = UIColor.systemOrange
        badge.backgroundColor = UIColor.systemOrange.withAlphaComponent(0.2)
    case .admin:
        badge.text = "Admin"
        badge.textColor = UIColor.systemPurple
        badge.backgroundColor = UIColor.systemPurple.withAlphaComponent(0.2)
    case .moderator:
        badge.text = "Mod"
        badge.textColor = UIColor.systemBlue
        badge.backgroundColor = UIColor.systemBlue.withAlphaComponent(0.2)
    default:
        badge.text = "Member"
        badge.textColor = UIColor.systemGray
        badge.backgroundColor = UIColor.systemGray.withAlphaComponent(0.2)
    }
    
    return badge
})
```

***

## Styling

### Style Hierarchy

1. Global styles (`CometChatGroupMembers.style`) apply to all instances
2. Instance styles override global for specific instances

### Global Level Styling

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

// Apply global styles
CometChatGroupMembers.style.backgroundColor = UIColor.systemBackground
CometChatGroupMembers.style.titleColor = UIColor.label
CometChatGroupMembers.style.titleFont = UIFont.systemFont(ofSize: 20, weight: .bold)
CometChatGroupMembers.style.listItemTitleTextColor = UIColor.label

// Custom avatar style
let avatarStyle = AvatarStyle()
avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 20)
CometChatGroupMembers.avatarStyle = avatarStyle
```

### Instance Level Styling

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

var customStyle = GroupMembersStyle()
customStyle.backgroundColor = UIColor(red: 0.95, green: 0.95, blue: 0.97, alpha: 1.0)
customStyle.titleColor = UIColor.darkGray
customStyle.listItemBackground = UIColor.white

let groupMembers = CometChatGroupMembers(group: group)
groupMembers.style = customStyle
```

<Frame>
  <img alt="CometChatGroupMembers with custom styling showing modified background color, title appearance, and list item styling" />
</Frame>

### Key Style Properties

| Property                    | Type      | Default                               | Description            |
| --------------------------- | --------- | ------------------------------------- | ---------------------- |
| `backgroundColor`           | `UIColor` | `CometChatTheme.backgroundColor01`    | Background color       |
| `titleColor`                | `UIColor` | `CometChatTheme.textColorPrimary`     | Navigation title color |
| `titleFont`                 | `UIFont`  | `CometChatTypography.Heading4.medium` | Navigation title font  |
| `listItemTitleTextColor`    | `UIColor` | `CometChatTheme.textColorPrimary`     | Member name color      |
| `listItemTitleFont`         | `UIFont`  | `CometChatTypography.Heading4.medium` | Member name font       |
| `listItemSubTitleTextColor` | `UIColor` | `CometChatTheme.textColorSecondary`   | Subtitle color         |
| `listItemBackground`        | `UIColor` | `.clear`                              | List item background   |

### Customization Matrix

| What to change    | Where     | Property/API              | Example                                    |
| ----------------- | --------- | ------------------------- | ------------------------------------------ |
| Background color  | Style     | `backgroundColor`         | `UIColor.systemBackground`                 |
| Title appearance  | Style     | `titleColor`, `titleFont` | Custom colors and fonts                    |
| List item look    | Style     | `listItemBackground`      | `UIColor.white`                            |
| Avatar appearance | Style     | `avatarStyle`             | `AvatarStyle()` with custom radius         |
| Hide search       | Property  | `hideSearch`              | `groupMembers.hideSearch = true`           |
| Hide kick option  | Property  | `hideKickMemberOption`    | `groupMembers.hideKickMemberOption = true` |
| Custom row        | View Slot | `set(listItemView:)`      | See Custom View Slots                      |

***

## Props

All props are optional except `group`. Sorted alphabetically.

### avatarStyle

Customizes the appearance of member avatars in the list.

|         |                 |
| ------- | --------------- |
| Type    | `AvatarStyle`   |
| Default | `AvatarStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let groupMembers = CometChatGroupMembers(group: group)

let avatarStyle = AvatarStyle()
avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 20)
avatarStyle.backgroundColor = UIColor.systemBlue.withAlphaComponent(0.1)

groupMembers.avatarStyle = avatarStyle
```

### group (required)

The group whose members to display.

|          |         |
| -------- | ------- |
| Type     | `Group` |
| Required | `true`  |

### groupMembersRequestBuilder

Custom request builder for filtering members.

|         |                                                   |
| ------- | ------------------------------------------------- |
| Type    | `GroupMembersRequest.GroupMembersRequestBuilder?` |
| Default | `nil`                                             |

### hideBackIcon

Hides the back button in the navigation bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideBanMemberOption

Hides the ban member option in swipe actions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideErrorView

Hides the error state view.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideKickMemberOption

Hides the kick member option in swipe actions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideLoadingState

Hides the loading state indicator.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideNavigationBar

Hides the entire navigation bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideScopeChangeOption

Hides the role change option in swipe actions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideSearch

Hides the search bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideUserStatus

Hides online/offline status indicators.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### selectionMode

Sets the selection mode for multi-select functionality.

|         |                 |
| ------- | --------------- |
| Type    | `SelectionMode` |
| Default | `.none`         |

### statusIndicatorStyle

Customizes the appearance of online/offline status indicators.

|         |                          |
| ------- | ------------------------ |
| Type    | `StatusIndicatorStyle`   |
| Default | `StatusIndicatorStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let groupMembers = CometChatGroupMembers(group: group)

let statusIndicatorStyle = StatusIndicatorStyle()
statusIndicatorStyle.backgroundColor = UIColor.systemGreen
statusIndicatorStyle.borderWidth = 2
statusIndicatorStyle.borderColor = UIColor.white

groupMembers.statusIndicatorStyle = statusIndicatorStyle
```

***

## Events

| Event                       | Payload                    | Fires when                 |
| --------------------------- | -------------------------- | -------------------------- |
| `ccGroupMemberKicked`       | `User, Group`              | A member is kicked         |
| `ccGroupMemberBanned`       | `User, Group`              | A member is banned         |
| `ccGroupMemberScopeChanged` | `User, Group, MemberScope` | A member's role is changed |

***

## Methods

### Swipe Action Methods

#### set(options:)

Sets custom swipe actions for group member list items, replacing the default options. These options appear when the user swipes on a member cell.

```swift lines theme={null}
@discardableResult
public func set(options: ((_ group: Group, _ member: GroupMember?) -> [CometChatGroupMemberOption])?) -> Self
```

| Parameter | Type                                                       | Description                                                        |
| --------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
| `options` | `((Group, GroupMember?) -> [CometChatGroupMemberOption])?` | Closure that returns an array of swipe action options for a member |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

groupMembers.set(options: { group, member in
    var options = [CometChatGroupMemberOption]()
    
    // Add message option
    let messageOption = CometChatGroupMemberOption(
        id: "message",
        title: "Message",
        icon: UIImage(systemName: "message"),
        backgroundColor: .systemBlue,
        onClick: { member, group, section, option, controller in
            let messages = CometChatMessages()
            messages.set(user: member)
            controller.navigationController?.pushViewController(messages, animated: true)
        }
    )
    options.append(messageOption)
    
    // Add remove option
    let removeOption = CometChatGroupMemberOption(
        id: "remove",
        title: "Remove",
        icon: UIImage(systemName: "trash"),
        backgroundColor: .systemRed,
        onClick: { member, group, section, option, controller in
            print("Remove member: \(member.name ?? "")")
        }
    )
    options.append(removeOption)
    
    return options
})
```

#### add(options:)

Adds additional swipe actions to the existing default options.

```swift lines theme={null}
@discardableResult
public func add(options: ((_ group: Group, _ member: GroupMember?) -> [CometChatGroupMemberOption])?) -> Self
```

| Parameter | Type                                                       | Description                                                    |
| --------- | ---------------------------------------------------------- | -------------------------------------------------------------- |
| `options` | `((Group, GroupMember?) -> [CometChatGroupMemberOption])?` | Closure that returns additional swipe action options to append |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

groupMembers.add(options: { group, member in
    var options = [CometChatGroupMemberOption]()
    
    // Add promote option
    let promoteOption = CometChatGroupMemberOption(
        id: "promote",
        title: "Promote",
        icon: UIImage(systemName: "arrow.up.circle"),
        backgroundColor: .systemGreen,
        onClick: { member, group, section, option, controller in
            print("Promote member: \(member.name ?? "")")
        }
    )
    options.append(promoteOption)
    
    return options
})
```

### Data Manipulation Methods

#### add(groupMember:)

Adds a new group member to the list.

```swift lines theme={null}
@discardableResult
public func add(groupMember: GroupMember) -> Self
```

| Parameter     | Type          | Description                         |
| ------------- | ------------- | ----------------------------------- |
| `groupMember` | `GroupMember` | The group member to add to the list |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

// Add a member programmatically
let newMember = GroupMember(uid: "user-123", groupMemberScope: .participant)
newMember.name = "John Doe"
groupMembers.add(groupMember: newMember)
```

#### update(groupMember:)

Updates an existing group member in the list.

```swift lines theme={null}
@discardableResult
public func update(groupMember: GroupMember) -> Self
```

| Parameter     | Type          | Description                               |
| ------------- | ------------- | ----------------------------------------- |
| `groupMember` | `GroupMember` | The group member with updated information |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

// Update a member's information
if var existingMember = memberToUpdate {
    existingMember.scope = .admin
    groupMembers.update(groupMember: existingMember)
}
```

#### remove(groupMember:)

Removes a group member from the list.

```swift lines theme={null}
@discardableResult
public func remove(groupMember: GroupMember) -> Self
```

| Parameter     | Type          | Description                              |
| ------------- | ------------- | ---------------------------------------- |
| `groupMember` | `GroupMember` | The group member to remove from the list |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

// Remove a member from the UI
groupMembers.remove(groupMember: memberToRemove)
```

#### insert(groupMember:at:)

Inserts a group member at a specific index in the list.

```swift lines theme={null}
@discardableResult
public func insert(groupMember: GroupMember, at index: Int) -> Self
```

| Parameter     | Type          | Description                                |
| ------------- | ------------- | ------------------------------------------ |
| `groupMember` | `GroupMember` | The group member to insert                 |
| `index`       | `Int`         | The position at which to insert the member |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

// Insert a member at the top of the list
let newMember = GroupMember(uid: "user-456", groupMemberScope: .participant)
newMember.name = "Jane Smith"
groupMembers.insert(groupMember: newMember, at: 0)
```

#### clearList()

Removes all group members from the list.

```swift lines theme={null}
public func clearList()
```

```swift lines theme={null}
import CometChatUIKitSwift

let groupMembers = CometChatGroupMembers(group: group)

// Clear all members from the list
groupMembers.clearList()
```

#### size()

Returns the number of group members currently in the list.

```swift lines theme={null}
public func size() -> Int
```

```swift lines theme={null}
import CometChatUIKitSwift

let groupMembers = CometChatGroupMembers(group: group)

// Get the count of members
let memberCount = groupMembers.size()
print("Total members: \(memberCount)")
```

***

## Selection Properties

### onSelectedItemProceed

Callback that fires when the user proceeds with selected members in selection mode. This is typically triggered when the user taps a "Done" or "Proceed" button after selecting members.

|         |                              |
| ------- | ---------------------------- |
| Type    | `(([GroupMember]) -> Void)?` |
| Default | `nil`                        |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)
groupMembers.selectionMode = .multiple

groupMembers.set(onSelectedItemProceed: { [weak self] selectedMembers in
    print("Proceeding with \(selectedMembers.count) selected members")
    
    for member in selectedMembers {
        print("Selected: \(member.name ?? "")")
    }
    
    // Perform action with selected members
    self?.handleSelectedMembers(selectedMembers)
})
```

***

## Custom Swipe Options

Add custom actions when swiping on a member:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let groupMembers = CometChatGroupMembers(group: group)

let deleteOption = CometChatGroupMemberOption(
    id: "delete",
    title: "Remove",
    icon: UIImage(systemName: "trash"),
    backgroundColor: .systemRed,
    onClick: { member, group, section, option, controller in
        print("Remove \(member.name ?? "")")
        // Implement remove logic
    }
)

let messageOption = CometChatGroupMemberOption(
    id: "message",
    title: "Message",
    icon: UIImage(systemName: "message"),
    backgroundColor: .systemBlue,
    onClick: { member, group, section, option, controller in
        let messages = CometChatMessages()
        messages.set(user: member)
        controller.navigationController?.pushViewController(messages, animated: true)
    }
)

groupMembers.setOptions(options: { group, member in
    return [messageOption, deleteOption]
})
```

<Frame>
  <img alt="CometChatGroupMembers showing custom swipe options with Remove and Message action buttons revealed on a member row" />
</Frame>

***

## Custom Menu Buttons

Add buttons to the navigation bar:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class GroupMembersViewController: UIViewController {
    
    var group: Group!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupGroupMembers()
    }
    
    private func setupGroupMembers() {
        let groupMembers = CometChatGroupMembers(group: group)
        
        let addButton = UIBarButtonItem(
            image: UIImage(systemName: "person.badge.plus"),
            style: .plain,
            target: self,
            action: #selector(addMemberTapped)
        )
        
        groupMembers.set(menus: [addButton])
        
        let navController = UINavigationController(rootViewController: groupMembers)
        present(navController, animated: true)
    }
    
    @objc func addMemberTapped() {
        // Show add member screen
        let addMembers = CometChatAddMembers(group: group)
        navigationController?.pushViewController(addMembers, animated: true)
    }
}
```

<Frame>
  <img alt="CometChatGroupMembers showing custom navigation bar menu with an add member button in the top right corner" />
</Frame>

***

## Common Patterns

### Admins and moderators only

```swift lines theme={null}
let adminBuilder = GroupMembersRequest.GroupMembersRequestBuilder(guid: group.guid)
    .set(scopes: ["admin", "moderator"])

let groupMembers = CometChatGroupMembers(group: group, groupMembersRequestBuilder: adminBuilder)
```

### Hide management options for participants

```swift lines theme={null}
let groupMembers = CometChatGroupMembers(group: group)
groupMembers.hideKickMemberOption = true
groupMembers.hideBanMemberOption = true
groupMembers.hideScopeChangeOption = true
```

### Custom empty state

```swift lines theme={null}
let groupMembers = CometChatGroupMembers(group: group)

groupMembers.set(emptyStateView: {
    let label = UILabel()
    label.text = "No members in this group"
    label.textAlignment = .center
    return label
})
```

### Multi-select members

```swift lines theme={null}
let groupMembers = CometChatGroupMembers(group: group)
groupMembers.selectionMode = .multiple

groupMembers.set(onSelection: { selectedMembers in
    print("Selected \(selectedMembers.count) members")
    // Kick selected members, change scope, etc.
})
```

***

## Related Components

* [Groups](/docs/ui-kit/ios/groups) - List all groups
* [Messages](/docs/ui-kit/ios/message-list) - Display messages in a group
* [Add Members](/docs/ui-kit/ios/group-members) - Add new members to a group
* [Banned Members](/docs/ui-kit/ios/group-members) - View banned members
* [Transfer Ownership](/docs/ui-kit/ios/guide-group-ownership) - Transfer group ownership


# Groups
Source: https://www.cometchat.com/docs/ui-kit/ios/groups

Display CometChat iOS UI Kit groups with avatars, member counts, group type indicators, search, filtering, join, and conversation actions.

The `CometChatGroups` component displays a searchable list of all available groups. It shows group names, avatars, member counts, and group type indicators (public/private/password-protected). Users can browse, join, and interact with group conversations.

<Frame>
  <img alt="CometChatGroups showing a searchable list of groups with avatars, names, member counts, and group type indicators" />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatGroups",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "description": "Displays a searchable list of all available groups with avatars, names, member counts, and group type indicators.",
    "inherits": "UIViewController",
    "primaryOutput": {
      "callback": "onItemClick",
      "type": "(Group, IndexPath) -> Void"
    },
    "props": {
      "data": {
        "groupsRequestBuilder": {
          "type": "GroupsRequest.GroupsRequestBuilder?",
          "default": "nil",
          "note": "Custom request builder for filtering groups"
        },
        "searchRequestBuilder": {
          "type": "GroupsRequest.GroupsRequestBuilder?",
          "default": "nil",
          "note": "Custom request builder for search"
        }
      },
      "callbacks": {
        "onItemClick": "(Group, IndexPath) -> Void",
        "onItemLongClick": "(Group, IndexPath) -> Void",
        "onBack": "() -> Void",
        "onSelection": "([Group]) -> Void",
        "onSelectedItemProceed": "([Group]) -> Void",
        "onError": "(CometChatException) -> Void",
        "onEmpty": "() -> Void",
        "onLoad": "([Group]) -> Void"
      },
      "visibility": {
        "hideSearch": { "type": "Bool", "default": false },
        "hideNavigationBar": { "type": "Bool", "default": false },
        "hideBackButton": { "type": "Bool", "default": false },
        "hideGroupType": { "type": "Bool", "default": false },
        "hideSectionHeader": { "type": "Bool", "default": false },
        "hideErrorView": { "type": "Bool", "default": false },
        "hideLoadingState": { "type": "Bool", "default": false }
      },
      "selection": {
        "selectionMode": { "type": "SelectionMode", "default": ".none" },
        "selectionLimit": { "type": "Int", "default": 0 },
        "selectedCellCount": { "type": "Int", "default": 0 }
      },
      "styling": {
        "avatarStyle": { "type": "AvatarStyle", "default": "AvatarStyle()" },
        "statusIndicatorStyle": { "type": "StatusIndicatorStyle", "default": "StatusIndicatorStyle()" }
      },
      "viewSlots": {
        "listItemView": "(Group) -> UIView",
        "leadingView": "(Group) -> UIView",
        "titleView": "(Group?) -> UIView",
        "subtitleView": "(Group?) -> UIView",
        "trailingView": "(Group?) -> UIView",
        "emptyStateView": "() -> UIView",
        "errorStateView": "() -> UIView",
        "loadingStateView": "() -> UIView"
      }
    },
    "events": [
      {
        "name": "ccGroupCreated",
        "payload": "Group",
        "description": "Fires when a group is created"
      },
      {
        "name": "ccGroupDeleted",
        "payload": "Group",
        "description": "Fires when a group is deleted"
      },
      {
        "name": "ccGroupMemberJoined",
        "payload": "{ user: User, group: Group }",
        "description": "Fires when a user joins a group"
      },
      {
        "name": "ccGroupMemberLeft",
        "payload": "{ user: User, group: Group }",
        "description": "Fires when a user leaves a group"
      }
    ],
    "sdkListeners": [
      "onGroupMemberJoined",
      "onGroupMemberLeft",
      "onGroupMemberKicked",
      "onGroupMemberBanned",
      "onGroupMemberUnbanned",
      "onGroupMemberScopeChanged",
      "onMemberAddedToGroup"
    ],
    "compositionExample": {
      "description": "Groups list for browsing and joining group conversations",
      "components": ["CometChatGroups", "CometChatMessages"],
      "flow": "User taps on a group → onItemClick fires → Navigate to CometChatMessages with selected group"
    },
    "types": {
      "Group": {
        "guid": "String",
        "name": "String",
        "icon": "String?",
        "membersCount": "Int",
        "groupType": "GroupType",
        "scope": "MemberScope?"
      },
      "GroupType": {
        "public": "Anyone can join",
        "private": "Invite only",
        "password": "Password protected"
      }
    }
  }
  ```
</Accordion>

| Field     | Value                 |
| --------- | --------------------- |
| Component | `CometChatGroups`     |
| Package   | `CometChatUIKitSwift` |
| Inherits  | `UIViewController`    |

***

## Where It Fits

`CometChatGroups` displays all available groups for browsing and joining. It's typically used as a standalone screen or within a tab view controller.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class GroupsViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupGroups()
    }
    
    private func setupGroups() {
        let groupsController = CometChatGroups()
        
        // Handle group selection - open group chat
        groupsController.set(onItemClick: { [weak self] group, indexPath in
            self?.openGroupChat(group)
        })
        
        let navController = UINavigationController(rootViewController: groupsController)
        present(navController, animated: true)
    }
    
    private func openGroupChat(_ group: Group) {
        let messagesVC = CometChatMessages()
        messagesVC.set(group: group)
        navigationController?.pushViewController(messagesVC, animated: true)
    }
}
```

<Frame>
  <img alt="CometChatGroups showing integration with navigation controller and group selection handling" />
</Frame>

***

## Minimal Render

```swift lines theme={null}
import CometChatUIKitSwift

let groups = CometChatGroups()
let navController = UINavigationController(rootViewController: groups)
present(navController, animated: true)
```

<Frame>
  <img alt="CometChatGroups showing minimal render with default configuration displaying group list" />
</Frame>

***

## Filtering

Use `GroupsRequest.GroupsRequestBuilder` to filter which groups appear in the list. The builder pattern allows chaining multiple filter conditions.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

// Create a custom request builder
let groupsRequestBuilder = GroupsRequest.GroupsRequestBuilder(limit: 30)
    .set(joinedOnly: true)

let groups = CometChatGroups(groupsRequestBuilder: groupsRequestBuilder)
```

### Filter Recipes

| Recipe             | Code                                       |
| ------------------ | ------------------------------------------ |
| Joined groups only | `.set(joinedOnly: true)`                   |
| Search by name     | `.set(searchKeyword: "design")`            |
| Filter by tags     | `.set(tags: ["engineering", "marketing"])` |
| Include tag info   | `.set(withTags: true)`                     |
| Limit results      | `GroupsRequestBuilder(limit: 20)`          |

***

## Actions and Events

### Callback Props

#### onItemClick

Fires when a user taps on a group in the list. Use this to open the group chat.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()

groups.set(onItemClick: { [weak self] group, indexPath in
    guard let self = self else { return }
    
    let messagesVC = CometChatMessages()
    messagesVC.set(group: group)
    self.navigationController?.pushViewController(messagesVC, animated: true)
})
```

#### onItemLongClick

Fires when a user long-presses on a group. Use this to show additional options.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()

groups.set(onItemLongClick: { [weak self] group, indexPath in
    guard let self = self else { return }
    
    let alert = UIAlertController(title: group.name, message: nil, preferredStyle: .actionSheet)
    
    alert.addAction(UIAlertAction(title: "View Details", style: .default) { _ in
        // View group details
    })
    
    alert.addAction(UIAlertAction(title: "Leave Group", style: .destructive) { _ in
        // Leave group
    })
    
    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
    self.present(alert, animated: true)
})
```

#### onBack

Fires when the back button is pressed.

```swift lines theme={null}
import CometChatUIKitSwift

let groups = CometChatGroups()

groups.set(onBack: { [weak self] in
    self?.navigationController?.popViewController(animated: true)
})
```

#### onSelection

Fires when groups are selected in selection mode.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()
groups.selectionMode = .multiple

groups.set(onSelection: { [weak self] selectedGroups in
    print("Selected \(selectedGroups.count) groups")
})
```

#### onSelectedItemProceed

Fires when the user confirms their selection by tapping the proceed/submit button. Use this to handle the final selection action.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()
groups.selectionMode = .multiple
groups.selectionLimit = 5

groups.onSelectedItemProceed = { [weak self] selectedGroups in
    guard let self = self else { return }
    
    // Handle the selected groups
    for group in selectedGroups {
        print("Selected group: \(group.name ?? "")")
    }
    
    // Proceed with the selection
    self.processSelectedGroups(selectedGroups)
}
```

#### onError

Fires when an error occurs while loading groups.

```swift lines theme={null}
import CometChatUIKitSwift

let groups = CometChatGroups()

groups.set(onError: { error in
    print("Error loading groups: \(error.errorDescription)")
})
```

#### onEmpty

Fires when the group list is empty.

```swift lines theme={null}
import CometChatUIKitSwift

let groups = CometChatGroups()

groups.set(onEmpty: {
    print("No groups found")
})
```

#### onLoad

Fires when groups are successfully loaded.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()

groups.set(onLoad: { groups in
    print("Loaded \(groups.count) groups")
})
```

### Actions Reference

| Method                  | Description                           | Example                 |
| ----------------------- | ------------------------------------- | ----------------------- |
| `set(onItemClick:)`     | Triggered when a group is tapped      | Open group chat         |
| `set(onItemLongClick:)` | Triggered on long press               | Show options menu       |
| `set(onBack:)`          | Triggered when back button is pressed | Custom navigation       |
| `set(onSelection:)`     | Triggered in selection mode           | Multi-select groups     |
| `onSelectedItemProceed` | Triggered when selection is confirmed | Process selected groups |
| `set(onError:)`         | Triggered when an error occurs        | Show error alert        |
| `set(onEmpty:)`         | Triggered when list is empty          | Show empty state        |
| `set(onLoad:)`          | Triggered when groups load            | Analytics tracking      |

### Global UI Events

| Event                 | Fires when            | Payload       |
| --------------------- | --------------------- | ------------- |
| `ccGroupCreated`      | A group is created    | `Group`       |
| `ccGroupDeleted`      | A group is deleted    | `Group`       |
| `ccGroupMemberJoined` | A user joins a group  | `User, Group` |
| `ccGroupMemberLeft`   | A user leaves a group | `User, Group` |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

class MyViewController: UIViewController, CometChatGroupEventListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CometChatGroupEvents.addListener("my-listener", self)
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        CometChatGroupEvents.removeListener("my-listener")
    }
    
    func onGroupCreate(group: Group) {
        print("Group created: \(group.name ?? "")")
    }
    
    func onGroupDelete(group: Group) {
        print("Group deleted: \(group.name ?? "")")
    }
    
    func onGroupMemberJoin(joinedUser: User, joinedGroup: Group) {
        print("\(joinedUser.name ?? "") joined \(joinedGroup.name ?? "")")
    }
    
    func onGroupMemberLeave(leftUser: User, leftGroup: Group) {
        print("\(leftUser.name ?? "") left \(leftGroup.name ?? "")")
    }
}
```

### SDK Events (Real-Time, Automatic)

| SDK Listener                | Internal behavior    |
| --------------------------- | -------------------- |
| `onGroupMemberJoined`       | Updates member count |
| `onGroupMemberLeft`         | Updates member count |
| `onGroupMemberKicked`       | Updates member count |
| `onGroupMemberBanned`       | Updates member count |
| `onGroupMemberUnbanned`     | Updates group info   |
| `onGroupMemberScopeChanged` | Updates member scope |
| `onMemberAddedToGroup`      | Updates member count |

***

## Custom View Slots

| Slot               | Signature            | Replaces                |
| ------------------ | -------------------- | ----------------------- |
| `listItemView`     | `(Group) -> UIView`  | Entire group row        |
| `leadingView`      | `(Group) -> UIView`  | Avatar / left section   |
| `titleView`        | `(Group?) -> UIView` | Name / title text       |
| `subtitleView`     | `(Group?) -> UIView` | Member count / subtitle |
| `trailingView`     | `(Group?) -> UIView` | Right side content      |
| `emptyStateView`   | `() -> UIView`       | Empty state display     |
| `errorStateView`   | `() -> UIView`       | Error state display     |
| `loadingStateView` | `() -> UIView`       | Loading state display   |

### listItemView

Replace the entire group row with a custom design.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()

groups.set(listItemView: { group in
    let customView = CustomGroupCell()
    customView.configure(with: group)
    return customView
})
```

<Frame>
  <img alt="CometChatGroups with custom listItemView showing customized group row with avatar, title, member count, and join button" />
</Frame>

You can create a `CustomGroupCell` as a custom `UIView`:

```swift lines theme={null}
import UIKit
import CometChatSDK

class CustomGroupCell: UIView {
    
    private let avatarImageView: UIImageView = {
        let imageView = UIImageView()
        imageView.translatesAutoresizingMaskIntoConstraints = false
        imageView.contentMode = .scaleAspectFill
        imageView.layer.cornerRadius = 20
        imageView.clipsToBounds = true
        imageView.backgroundColor = .systemGray5
        return imageView
    }()
    
    private let titleLabel: UILabel = {
        let label = UILabel()
        label.translatesAutoresizingMaskIntoConstraints = false
        label.font = .systemFont(ofSize: 16, weight: .semibold)
        label.textColor = .label
        return label
    }()
    
    private let membersLabel: UILabel = {
        let label = UILabel()
        label.translatesAutoresizingMaskIntoConstraints = false
        label.font = .systemFont(ofSize: 14)
        label.textColor = .secondaryLabel
        return label
    }()
    
    private let joinButton: UIButton = {
        let button = UIButton(type: .system)
        button.translatesAutoresizingMaskIntoConstraints = false
        button.setTitle("JOIN", for: .normal)
        button.titleLabel?.font = .systemFont(ofSize: 12, weight: .bold)
        button.layer.cornerRadius = 12
        button.layer.borderWidth = 1
        button.layer.borderColor = UIColor.systemBlue.cgColor
        return button
    }()
    
    override init(frame: CGRect) {
        super.init(frame: frame)
        setupView()
    }
    
    required init?(coder: NSCoder) {
        super.init(coder: coder)
        setupView()
    }
    
    private func setupView() {
        addSubview(avatarImageView)
        addSubview(titleLabel)
        addSubview(membersLabel)
        addSubview(joinButton)
        
        NSLayoutConstraint.activate([
            avatarImageView.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 16),
            avatarImageView.centerYAnchor.constraint(equalTo: centerYAnchor),
            avatarImageView.widthAnchor.constraint(equalToConstant: 40),
            avatarImageView.heightAnchor.constraint(equalToConstant: 40),
            
            titleLabel.leadingAnchor.constraint(equalTo: avatarImageView.trailingAnchor, constant: 12),
            titleLabel.topAnchor.constraint(equalTo: topAnchor, constant: 12),
            titleLabel.trailingAnchor.constraint(lessThanOrEqualTo: joinButton.leadingAnchor, constant: -8),
            
            membersLabel.leadingAnchor.constraint(equalTo: avatarImageView.trailingAnchor, constant: 12),
            membersLabel.topAnchor.constraint(equalTo: titleLabel.bottomAnchor, constant: 4),
            membersLabel.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -12),
            
            joinButton.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -16),
            joinButton.centerYAnchor.constraint(equalTo: centerYAnchor),
            joinButton.widthAnchor.constraint(equalToConstant: 60),
            joinButton.heightAnchor.constraint(equalToConstant: 24)
        ])
    }
    
    func configure(with group: Group) {
        titleLabel.text = group.name
        membersLabel.text = "\(group.membersCount) members"
        
        if let iconURL = group.icon, let url = URL(string: iconURL) {
            URLSession.shared.dataTask(with: url) { [weak self] data, _, _ in
                if let data = data, let image = UIImage(data: data) {
                    DispatchQueue.main.async {
                        self?.avatarImageView.image = image
                    }
                }
            }.resume()
        }
        
        let isJoined = group.hasJoined
        joinButton.setTitle(isJoined ? "JOINED" : "JOIN", for: .normal)
        joinButton.setTitleColor(isJoined ? .systemGray : .systemBlue, for: .normal)
        joinButton.layer.borderColor = isJoined ? UIColor.systemGray.cgColor : UIColor.systemBlue.cgColor
    }
}
```

### leadingView

Customize the leading view (avatar area) of a group cell.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()

groups.set(leadingView: { group in
    let view = CustomLeadingView()
    return view
})
```

<Frame>
  <img alt="CometChatGroups with custom leadingView showing customized avatar area with icon and join button" />
</Frame>

You can create a `CustomLeadingView` as a custom `UIView`:

```swift lines theme={null}
import UIKit

class CustomLeadingView: UIView {

    private let iconImageView: UIImageView = {
        let imageView = UIImageView(image: UIImage(systemName: "person.2.fill"))
        imageView.tintColor = .white
        imageView.contentMode = .scaleAspectFit
        return imageView
    }()

    private let joinButton: UIButton = {
        let button = UIButton()
        button.setTitle("Join", for: .normal)
        button.setTitleColor(.white, for: .normal)
        button.titleLabel?.font = UIFont.systemFont(ofSize: 14, weight: .bold)
        button.backgroundColor = .orange
        button.layer.cornerRadius = 8
        return button
    }()

    override init(frame: CGRect) {
        super.init(frame: frame)
        setupView()
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    private func setupView() {
        backgroundColor = .purple
        layer.cornerRadius = 12

        addSubview(iconImageView)
        addSubview(joinButton)

        iconImageView.translatesAutoresizingMaskIntoConstraints = false
        joinButton.translatesAutoresizingMaskIntoConstraints = false
    }
}
```

### titleView

Customize the title view of a group cell.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()

groups.set(titleView: { group in
    let view = CustomTitleView()
    return view
})
```

<Frame>
  <img alt="CometChatGroups with custom titleView showing group name with public badge indicator" />
</Frame>

You can create a `CustomTitleView` as a custom `UIView`:

```swift lines theme={null}
import UIKit

class CustomTitleView: UIView {

    private let titleLabel: UILabel = {
        let label = UILabel()
        label.text = "Artistic Design"
        label.font = UIFont.systemFont(ofSize: 16, weight: .medium)
        label.textColor = .black
        return label
    }()

    private let publicBadge: UIView = {
        let view = UIView()
        view.backgroundColor = .blue
        view.layer.cornerRadius = 10

        let icon = UIImageView(image: UIImage(systemName: "person.3.fill"))
        icon.tintColor = .white
        icon.contentMode = .scaleAspectFit

        let label = UILabel()
        label.text = "Public"
        label.font = UIFont.systemFont(ofSize: 12, weight: .bold)
        label.textColor = .white

        let stackView = UIStackView(arrangedSubviews: [icon, label])
        stackView.spacing = 4
        stackView.alignment = .center
        stackView.translatesAutoresizingMaskIntoConstraints = false

        view.addSubview(stackView)

        NSLayoutConstraint.activate([
            stackView.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            stackView.centerYAnchor.constraint(equalTo: view.centerYAnchor),
            view.widthAnchor.constraint(equalToConstant: 60),
            view.heightAnchor.constraint(equalToConstant: 20)
        ])
        
        return view
    }()

    override init(frame: CGRect) {
        super.init(frame: frame)
        setupView()
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    private func setupView() {
        addSubview(titleLabel)
        addSubview(publicBadge)

        titleLabel.translatesAutoresizingMaskIntoConstraints = false
        publicBadge.translatesAutoresizingMaskIntoConstraints = false

        NSLayoutConstraint.activate([
            titleLabel.leadingAnchor.constraint(equalTo: leadingAnchor),
            titleLabel.centerYAnchor.constraint(equalTo: centerYAnchor),

            publicBadge.leadingAnchor.constraint(equalTo: titleLabel.trailingAnchor, constant: 6),
            publicBadge.centerYAnchor.constraint(equalTo: centerYAnchor)
        ])
    }
}
```

### subtitleView

Customize the subtitle area below the group name.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()

groups.set(subtitleView: { group in
    let view = CustomSubtitleView(membersCount: group.membersCount)
    return view
})
```

<Frame>
  <img alt="CometChatGroups with custom subtitleView showing member count and group description text" />
</Frame>

You can create a `CustomSubtitleView` as a custom `UIView`:

```swift lines theme={null}
import UIKit

class CustomSubtitleView: UILabel {
    
    init(membersCount: Int) {
        super.init(frame: .zero)
        self.text = "\(membersCount) members • Group description"
        self.textColor = UIColor.gray
        self.font = UIFont.systemFont(ofSize: 14)
        self.numberOfLines = 1
    }
    
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
}
```

### trailingView

Customize the trailing view (right side) of a group cell.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()

groups.set(trailView: { group in
    let view = CustomTrailView()
    return view
})
```

<Frame>
  <img alt="CometChatGroups with custom trailingView showing joined status badge on the right side" />
</Frame>

You can create a `CustomTrailView` as a custom `UIView`:

```swift lines theme={null}
import UIKit

class CustomTrailView: UIView {

    private let joinedLabel: UILabel = {
        let label = UILabel()
        label.text = "JOINED"
        label.font = UIFont.systemFont(ofSize: 14, weight: .bold)
        label.textColor = UIColor.purple
        return label
    }()

    override init(frame: CGRect) {
        super.init(frame: frame)
        setupView()
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    private func setupView() {
        backgroundColor = UIColor.purple.withAlphaComponent(0.1)
        layer.cornerRadius = 16

        addSubview(joinedLabel)
        joinedLabel.translatesAutoresizingMaskIntoConstraints = false

        NSLayoutConstraint.activate([
            joinedLabel.centerXAnchor.constraint(equalTo: centerXAnchor),
            joinedLabel.centerYAnchor.constraint(equalTo: centerYAnchor),
            widthAnchor.constraint(equalToConstant: 80),
            heightAnchor.constraint(equalToConstant: 32)
        ])
    }
}
```

### loadingStateView

Customize the loading state view displayed while data is being fetched.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let groups = CometChatGroups()

let loadingIndicator = UIActivityIndicatorView(style: .medium)
loadingIndicator.startAnimating()
groups.set(loadingView: loadingIndicator)
```

### errorStateView

Customize the error state view displayed when an error occurs.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let groups = CometChatGroups()

let errorLabel = UILabel()
errorLabel.text = "Something went wrong!"
errorLabel.textColor = .red
groups.set(errorView: errorLabel)
```

### emptyStateView

Customize the empty state view displayed when no groups are available.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let groups = CometChatGroups()

let emptyLabel = UILabel()
emptyLabel.text = "No groups found"
emptyLabel.textColor = .gray
emptyLabel.textAlignment = .center
groups.set(emptyView: emptyLabel)
```

***

## Options

### set(options:)

Define custom swipe options for each group. This method allows you to return an array of `CometChatGroupOption` based on the group object. These options appear when the user swipes on a group cell.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()

groups.set(options: { group in
    // Create a custom delete option
    let deleteOption = CometChatGroupOption(
        id: "delete",
        title: "Delete",
        icon: UIImage(systemName: "trash"),
        backgroundColor: .systemRed,
        onClick: { group, section, option, controller in
            // Handle delete action
            print("Delete group: \(group.name ?? "")")
        }
    )
    
    // Create a custom mute option
    let muteOption = CometChatGroupOption(
        id: "mute",
        title: "Mute",
        icon: UIImage(systemName: "bell.slash"),
        backgroundColor: .systemOrange,
        onClick: { group, section, option, controller in
            // Handle mute action
            print("Mute group: \(group.name ?? "")")
        }
    )
    
    return [deleteOption, muteOption]
})
```

### add(options:)

Dynamically add additional swipe options to groups while preserving the default options. This method lets you return additional `CometChatGroupOption` elements that will be appended to the existing options.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()

groups.add(options: { group in
    // Add a custom archive option
    let archiveOption = CometChatGroupOption(
        id: "archive",
        title: "Archive",
        icon: UIImage(systemName: "archivebox"),
        backgroundColor: .systemBlue,
        onClick: { group, section, option, controller in
            // Handle archive action
            print("Archive group: \(group.name ?? "")")
        }
    )
    
    return [archiveOption]
})
```

***

## Data Manipulation Methods

### showJoiningGroupAlert(for:)

Displays an alert dialog when a user attempts to join a password-protected group. This method shows a prompt for the user to enter the group password.

```swift lines theme={null}
public func showJoiningGroupAlert(for group: Group)
```

| Parameter | Type    | Description                          |
| --------- | ------- | ------------------------------------ |
| `group`   | `Group` | The password-protected group to join |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let groups = CometChatGroups()

// Show joining alert for a password-protected group
groups.set(onItemClick: { [weak self] group, indexPath in
    if group.groupType == .password && !group.hasJoined {
        self?.groups.showJoiningGroupAlert(for: group)
    } else {
        // Navigate to group chat
    }
})
```

### hideJoiningGroupAlert(completion:)

Dismisses the joining group alert dialog programmatically. Use this when you need to close the alert without user interaction.

```swift lines theme={null}
public func hideJoiningGroupAlert(completion: (() -> Void)? = nil)
```

| Parameter    | Type            | Description                                          |
| ------------ | --------------- | ---------------------------------------------------- |
| `completion` | `(() -> Void)?` | Optional closure called after the alert is dismissed |

```swift lines theme={null}
import CometChatUIKitSwift

let groups = CometChatGroups()

// Hide the joining alert with a completion handler
groups.hideJoiningGroupAlert {
    print("Alert dismissed")
}
```

***

## Styling

### Style Hierarchy

1. Global styles (`CometChatGroups.style`) apply to all instances
2. Instance styles override global for specific instances

### Global Level Styling

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

// Apply global styles that affect all CometChatGroups instances
CometChatGroups.style.backgroundColor = UIColor.systemBackground
CometChatGroups.style.titleColor = UIColor.label
CometChatGroups.style.titleFont = UIFont.systemFont(ofSize: 34, weight: .bold)
CometChatGroups.style.listItemTitleTextColor = UIColor.label
CometChatGroups.style.listItemSubTitleTextColor = UIColor.secondaryLabel

// Custom avatar style
let avatarStyle = AvatarStyle()
avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)
CometChatGroups.avatarStyle = avatarStyle
```

### Instance Level Styling

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

// Create a custom style for a specific instance
var customStyle = GroupsStyle()
customStyle.backgroundColor = UIColor(red: 0.95, green: 0.95, blue: 0.97, alpha: 1.0)
customStyle.titleColor = UIColor.darkGray
customStyle.listItemBackground = UIColor.white

let groups = CometChatGroups()
groups.style = customStyle
```

### Key Style Properties

| Property                    | Type      | Default                               | Description                |
| --------------------------- | --------- | ------------------------------------- | -------------------------- |
| `backgroundColor`           | `UIColor` | `CometChatTheme.backgroundColor01`    | Background color           |
| `titleColor`                | `UIColor` | `CometChatTheme.textColorPrimary`     | Navigation title color     |
| `titleFont`                 | `UIFont`  | `CometChatTypography.Heading4.medium` | Navigation title font      |
| `listItemTitleTextColor`    | `UIColor` | `CometChatTheme.textColorPrimary`     | Group name color           |
| `listItemTitleFont`         | `UIFont`  | `CometChatTypography.Heading4.medium` | Group name font            |
| `listItemSubTitleTextColor` | `UIColor` | `CometChatTheme.textColorSecondary`   | Member count color         |
| `listItemSubTitleFont`      | `UIFont`  | `CometChatTypography.Body.regular`    | Member count font          |
| `listItemBackground`        | `UIColor` | `.clear`                              | List item background       |
| `privateGroupBadgeColor`    | `UIColor` | `CometChatTheme.iconColorSecondary`   | Private group badge color  |
| `passwordGroupBadgeColor`   | `UIColor` | `CometChatTheme.iconColorSecondary`   | Password group badge color |

### Customization Matrix

| What to change    | Where     | Property/API              | Example                            |
| ----------------- | --------- | ------------------------- | ---------------------------------- |
| Background color  | Style     | `backgroundColor`         | `UIColor.systemBackground`         |
| Title appearance  | Style     | `titleColor`, `titleFont` | Custom colors and fonts            |
| List item look    | Style     | `listItemBackground`      | `UIColor.white`                    |
| Avatar appearance | Style     | `avatarStyle`             | `AvatarStyle()` with custom radius |
| Group type badges | Style     | `privateGroupBadgeColor`  | Custom badge colors                |
| Hide search       | Property  | `hideSearch`              | `groups.hideSearch = true`         |
| Hide group type   | Property  | `hideGroupType`           | `groups.hideGroupType = true`      |
| Custom row        | View Slot | `set(listItemView:)`      | See Custom View Slots              |

***

## Props

All props are optional. Sorted alphabetically.

### avatarStyle

Customizes the appearance of avatars in group list items.

|         |                 |
| ------- | --------------- |
| Type    | `AvatarStyle`   |
| Default | `AvatarStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let groups = CometChatGroups()

let avatarStyle = AvatarStyle()
avatarStyle.backgroundColor = UIColor.systemBlue
avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)
avatarStyle.borderWidth = 1
avatarStyle.borderColor = UIColor.systemGray4

groups.set(avatarStyle: avatarStyle)
```

### groupsRequestBuilder

Custom request builder for filtering groups.

|         |                                       |
| ------- | ------------------------------------- |
| Type    | `GroupsRequest.GroupsRequestBuilder?` |
| Default | `nil`                                 |

### hideBackButton

Hides the back button in the navigation bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideErrorView

Hides the error state view.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideGroupType

Hides the public/private/password group type icons.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideLoadingState

Hides the loading state indicator.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideNavigationBar

Hides the entire navigation bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideSearch

Hides the search bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideSectionHeader

Hides the alphabetical section headers.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### searchRequestBuilder

Custom request builder for search functionality.

|         |                                       |
| ------- | ------------------------------------- |
| Type    | `GroupsRequest.GroupsRequestBuilder?` |
| Default | `nil`                                 |

### selectedCellCount

Returns the count of currently selected groups when in selection mode.

|         |       |
| ------- | ----- |
| Type    | `Int` |
| Default | `0`   |

```swift lines theme={null}
import CometChatUIKitSwift

let groups = CometChatGroups()
groups.selectionMode = .multiple

// Get the count of selected groups
let selectedCount = groups.selectedCellCount
print("Selected \(selectedCount) groups")
```

### selectionLimit

Sets the maximum number of groups that can be selected in selection mode. When the limit is reached, further selections are disabled.

|         |                 |
| ------- | --------------- |
| Type    | `Int`           |
| Default | `0` (unlimited) |

```swift lines theme={null}
import CometChatUIKitSwift

let groups = CometChatGroups()
groups.selectionMode = .multiple

// Limit selection to 5 groups
groups.selectionLimit = 5

// Handle selection confirmation
groups.onSelectedItemProceed = { selectedGroups in
    print("Selected \(selectedGroups.count) groups")
    
    // Process the selected groups
    for group in selectedGroups {
        print("Group: \(group.name ?? "")")
    }
}
```

### selectionMode

Sets the selection mode for multi-select functionality.

|         |                 |
| ------- | --------------- |
| Type    | `SelectionMode` |
| Default | `.none`         |

### statusIndicatorStyle

Customizes the appearance of group type status indicators.

|         |                          |
| ------- | ------------------------ |
| Type    | `StatusIndicatorStyle`   |
| Default | `StatusIndicatorStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let groups = CometChatGroups()

let statusIndicatorStyle = StatusIndicatorStyle()
statusIndicatorStyle.backgroundColor = UIColor.systemGreen
statusIndicatorStyle.borderWidth = 2
statusIndicatorStyle.borderColor = UIColor.white

groups.set(statusIndicatorStyle: statusIndicatorStyle)
```

***

## Events

| Event                 | Payload       | Fires when            |
| --------------------- | ------------- | --------------------- |
| `ccGroupCreated`      | `Group`       | A group is created    |
| `ccGroupDeleted`      | `Group`       | A group is deleted    |
| `ccGroupMemberJoined` | `User, Group` | A user joins a group  |
| `ccGroupMemberLeft`   | `User, Group` | A user leaves a group |

***

## Common Patterns

### Public groups only

```swift lines theme={null}
let publicBuilder = GroupsRequest.GroupsRequestBuilder(limit: 30)
    .set(groupType: .public)

let groups = CometChatGroups()
groups.set(groupsRequestBuilder: publicBuilder)
```

### Joined groups only

```swift lines theme={null}
let joinedBuilder = GroupsRequest.GroupsRequestBuilder(limit: 30)
    .set(joinedOnly: true)

let groups = CometChatGroups()
groups.set(groupsRequestBuilder: joinedBuilder)
```

### Custom empty state with CTA

```swift lines theme={null}
let groups = CometChatGroups()

groups.set(emptyStateView: {
    let emptyView = UIView()
    
    let label = UILabel()
    label.text = "No groups found"
    label.textAlignment = .center
    
    let button = UIButton(type: .system)
    button.setTitle("Create a group", for: .normal)
    
    // Add subviews and constraints...
    return emptyView
})
```

### Hide all chrome — minimal list

```swift lines theme={null}
let groups = CometChatGroups()
groups.hideSearch = true
groups.hideGroupType = true
groups.hideSectionHeader = true
```

### Multi-select groups

```swift lines theme={null}
let groups = CometChatGroups()
groups.selectionMode = .multiple

groups.set(onSelection: { selectedGroups in
    print("Selected \(selectedGroups.count) groups")
})
```

***

## Related Components

* [Messages](/docs/ui-kit/ios/message-list) - Display messages in a group
* [Conversations](/docs/ui-kit/ios/conversations) - List all conversations
* [Users](/docs/ui-kit/ios/users) - List all users
* [Group Members](/docs/ui-kit/ios/group-members) - Manage group members
* [Groups With Messages](/docs/ui-kit/ios/groups) - Combined groups and messages view


# AI Agent Integration
Source: https://www.cometchat.com/docs/ui-kit/ios/guide-ai-agent

Add CometChat iOS UI Kit AI agents with chat history, contextual responses, streaming messages, suggested prompts, and custom styling.

Integrate AI agents into your iOS app to provide intelligent conversational experiences with chat history, contextual responses, and seamless handoffs.

<Note>
  **1:1 and group conversations.** AI Agents work in both one-on-one and group conversations. In a 1:1 chat, the end user talks directly with the agent user. In a group, the agent participates as a member — its messages are delivered and attributed like any other member's message. If the group contains only one user and one agent, the agent responds automatically. In groups with more than two members, the agent only responds when @mentioned.
</Note>

<Frame>
  <img />
</Frame>

## Prerequisites

Before implementing AI agents, ensure you have:

* Completed [Getting Started](/docs/ui-kit/ios/getting-started) setup
* CometChat UIKit v5+ installed
* AI features enabled in your [CometChat Dashboard](https://app.cometchat.com)
* User logged in with `CometChatUIKit.login()`

## Overview

The AI Agent integration provides:

* **Intelligent Responses** - Context-aware AI conversations
* **Chat History** - Browse and resume previous AI sessions
* **Streaming Responses** - Real-time message streaming
* **Custom Styling** - Match your app's design
* **Suggested Messages** - Quick-start prompts for users

## Basic Implementation

Create a simple AI chat screen:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class AIAgentChatViewController: UIViewController {
    
    private var user: User?
    private var messageHeader: CometChatMessageHeader!
    private var messageList: CometChatMessageList!
    private var messageComposer: CometChatMessageComposer!
    
    convenience init(user: User) {
        self.init()
        self.user = user
    }
    
    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .systemBackground
        setupUI()
    }
    
    private func setupUI() {
        guard let user = user else { return }
        
        // Message Header
        messageHeader = CometChatMessageHeader()
        messageHeader.set(user: user)
        messageHeader.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(messageHeader)
        
        // Message List
        messageList = CometChatMessageList()
        messageList.set(user: user)
        messageList.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(messageList)
        
        // Message Composer
        messageComposer = CometChatMessageComposer()
        messageComposer.set(user: user)
        messageComposer.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(messageComposer)
        
        setupConstraints()
    }
    
    private func setupConstraints() {
        NSLayoutConstraint.activate([
            messageHeader.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
            messageHeader.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            messageHeader.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            messageHeader.heightAnchor.constraint(equalToConstant: 60),
            
            messageList.topAnchor.constraint(equalTo: messageHeader.bottomAnchor),
            messageList.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            messageList.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            messageList.bottomAnchor.constraint(equalTo: messageComposer.topAnchor),
            
            messageComposer.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            messageComposer.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            messageComposer.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
        ])
    }
}
```

## Production Implementation

Complete AI agent chat with history, navigation, and error handling:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ProductionAIAgentViewController: UIViewController {
    
    // MARK: - Properties
    private var user: User?
    private var group: Group?
    private var parentMessage: BaseMessage?
    private var isHistoryMode: Bool = false
    
    private var messageHeader: CometChatMessageHeader!
    private var messageList: CometChatMessageList!
    private var messageComposer: CometChatMessageComposer!
    
    // MARK: - Initialization
    convenience init(user: User, parentMessage: BaseMessage? = nil, isHistory: Bool = false) {
        self.init()
        self.user = user
        self.parentMessage = parentMessage
        self.isHistoryMode = isHistory
    }
    
    convenience init(group: Group, parentMessage: BaseMessage? = nil, isHistory: Bool = false) {
        self.init()
        self.group = group
        self.parentMessage = parentMessage
        self.isHistoryMode = isHistory
    }
    
    // MARK: - Lifecycle
    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .systemBackground
        setupMessageHeader()
        setupMessageList()
        setupMessageComposer()
        setupConstraints()
    }
    
    // MARK: - Setup
    private func setupMessageHeader() {
        messageHeader = CometChatMessageHeader()
        messageHeader.translatesAutoresizingMaskIntoConstraints = false
        
        if let user = user {
            messageHeader.set(user: user)
        } else if let group = group {
            messageHeader.set(group: group)
        }
        
        // Back button handler
        messageHeader.set(onBack: { [weak self] in
            self?.navigationController?.popViewController(animated: true)
        })
        
        // Chat history button handler
        messageHeader.onAiChatHistoryClicked = { [weak self] user in
            self?.openChatHistory()
        }
        
        view.addSubview(messageHeader)
    }
    
    private func setupMessageList() {
        messageList = CometChatMessageList()
        messageList.translatesAutoresizingMaskIntoConstraints = false
        messageList.hideThreadView = true
        
        if let user = user {
            messageList.set(user: user)
        } else if let group = group {
            messageList.set(group: group)
        }
        
        // If resuming from history, set parent message
        if let parentMessage = parentMessage {
            messageList.set(parentMessage: parentMessage)
        }
        
        view.addSubview(messageList)
    }
    
    private func setupMessageComposer() {
        messageComposer = CometChatMessageComposer()
        messageComposer.translatesAutoresizingMaskIntoConstraints = false
        
        if let user = user {
            messageComposer.set(user: user)
        } else if let group = group {
            messageComposer.set(group: group)
        }
        
        // If resuming from history, set parent message
        if let parentMessage = parentMessage {
            messageComposer.set(parentMessage: parentMessage)
        }
        
        view.addSubview(messageComposer)
    }
    
    private func setupConstraints() {
        NSLayoutConstraint.activate([
            messageHeader.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
            messageHeader.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            messageHeader.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            messageHeader.heightAnchor.constraint(equalToConstant: 60),
            
            messageList.topAnchor.constraint(equalTo: messageHeader.bottomAnchor),
            messageList.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            messageList.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            messageList.bottomAnchor.constraint(equalTo: messageComposer.topAnchor),
            
            messageComposer.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            messageComposer.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            messageComposer.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
        ])
    }
    
    // MARK: - Chat History
    private func openChatHistory() {
        let chatHistoryVC = CometChatAIAssistanceChatHistory()
        
        if let user = user {
            chatHistoryVC.set(user: user)
        } else if let group = group {
            chatHistoryVC.set(group: group)
        }
        
        // Handle new chat button
        chatHistoryVC.onNewChatButtonClicked = { [weak self] user in
            self?.startNewChat()
        }
        
        // Handle message selection to resume conversation
        chatHistoryVC.onMessageClicked = { [weak self] message in
            self?.resumeConversation(from: message)
        }
        
        // Handle close
        chatHistoryVC.onClose = { [weak self] in
            self?.navigationController?.popViewController(animated: true)
        }
        
        navigationController?.pushViewController(chatHistoryVC, animated: true)
    }
    
    private func startNewChat() {
        let newChatVC: ProductionAIAgentViewController
        
        if let user = user {
            newChatVC = ProductionAIAgentViewController(user: user)
        } else if let group = group {
            newChatVC = ProductionAIAgentViewController(group: group)
        } else {
            return
        }
        
        navigationController?.pushViewController(newChatVC, animated: true)
    }
    
    private func resumeConversation(from message: BaseMessage) {
        let resumeVC: ProductionAIAgentViewController
        
        if let user = user {
            resumeVC = ProductionAIAgentViewController(user: user, parentMessage: message, isHistory: true)
        } else if let group = group {
            resumeVC = ProductionAIAgentViewController(group: group, parentMessage: message, isHistory: true)
        } else {
            return
        }
        
        navigationController?.pushViewController(resumeVC, animated: true)
    }
}
```

## Launching AI Agent Chat

Start an AI agent conversation from your app:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ChatListViewController: UIViewController {
    
    func openAIAgentChat(agentUID: String) {
        // Fetch the AI agent user
        CometChat.getUser(UID: agentUID) { [weak self] user in
            DispatchQueue.main.async {
                // Check if user is an AI agent (role contains "agentic")
                if user.role?.lowercased().contains("agentic") == true {
                    let aiChatVC = ProductionAIAgentViewController(user: user)
                    self?.navigationController?.pushViewController(aiChatVC, animated: true)
                } else {
                    // Regular user chat
                    let messages = CometChatMessages()
                    messages.set(user: user)
                    self?.navigationController?.pushViewController(messages, animated: true)
                }
            }
        } onError: { error in
            print("Error fetching user: \(error?.errorDescription ?? "")")
        }
    }
    
    func detectAndOpenChat(for user: User) {
        // Detect if user is an AI agent
        let isAIAgent = user.role?.lowercased().contains("agentic") == true
        
        if isAIAgent {
            let aiChatVC = ProductionAIAgentViewController(user: user)
            navigationController?.pushViewController(aiChatVC, animated: true)
        } else {
            let messages = CometChatMessages()
            messages.set(user: user)
            navigationController?.pushViewController(messages, animated: true)
        }
    }
}
```

## Styling

<Note>
  By default, all mobile UI Kits inherit font size from the operating system's accessibility settings. However, on iOS, developers have the option to override this behavior and set custom font sizes programmatically using the `textFont` property on style objects or by configuring `CometChatTypography` globally.
</Note>

Customize the AI chat bubble appearance:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

class AIAgentStylingExample {
    
    func applyGlobalStyles() {
        // Configure AI bubble style
        var aiBubbleStyle = AIAssistantBubbleStyle()
        aiBubbleStyle.backgroundColor = .clear
        aiBubbleStyle.borderWidth = 1
        aiBubbleStyle.borderColor = .systemBlue
        aiBubbleStyle.textColor = .label
        aiBubbleStyle.textFont = UIFont.systemFont(ofSize: 14)
        aiBubbleStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 12)
        
        // Apply globally
        CometChatAIAssistantBubble.style = aiBubbleStyle
    }
    
    func applyInstanceStyles() -> ProductionAIAgentViewController {
        let aiChatVC = ProductionAIAgentViewController(user: User())
        
        // Custom message list style
        let messageListStyle = MessageListStyle()
        messageListStyle.backgroundColor = UIColor.systemBackground
        
        // Custom composer style
        let composerStyle = MessageComposerStyle()
        composerStyle.backgroundColor = UIColor.secondarySystemBackground
        composerStyle.borderColor = UIColor.separator
        composerStyle.borderWidth = 1
        
        return aiChatVC
    }
}
```

### Style Properties

| Property          | Description             |
| ----------------- | ----------------------- |
| `backgroundColor` | Bubble background color |
| `borderWidth`     | Bubble border width     |
| `borderColor`     | Bubble border color     |
| `textColor`       | Message text color      |
| `textFont`        | Message text font       |
| `cornerRadius`    | Bubble corner radius    |

## Customization Options

### Empty State View

Customize the view shown when there are no messages:

```swift lines theme={null}
let emptyView = UIView()
let label = UILabel()
label.text = "Start a conversation with AI"
label.textAlignment = .center
label.textColor = .secondaryLabel
emptyView.addSubview(label)

messageList.set(emptyStateView: emptyView)
```

### Streaming Speed

Adjust how fast AI responses stream:

```swift lines theme={null}
// Configure streaming speed (characters per second)
messageList.set(streamingSpeed: 50)
```

### Suggested Messages

Provide quick-start prompts for users:

```swift lines theme={null}
let suggestions = [
    "What can you help me with?",
    "Tell me about your capabilities",
    "How do I get started?"
]

messageComposer.set(suggestedMessages: suggestions)
```

### AI Assistant Tools

Configure custom tools for the AI agent:

```swift lines theme={null}
messageComposer.set(aiAssistantTools: { message in
    // Return custom tools based on context
    return [
        AITool(name: "search", description: "Search knowledge base"),
        AITool(name: "calculate", description: "Perform calculations")
    ]
})
```

## Chat History Component

The `CometChatAIAssistanceChatHistory` component displays previous AI conversations:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ChatHistoryViewController: UIViewController {
    
    private var user: User?
    
    convenience init(user: User) {
        self.init()
        self.user = user
    }
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupChatHistory()
    }
    
    private func setupChatHistory() {
        guard let user = user else { return }
        
        let chatHistory = CometChatAIAssistanceChatHistory()
        chatHistory.set(user: user)
        
        // New chat button
        chatHistory.onNewChatButtonClicked = { [weak self] user in
            let newChat = ProductionAIAgentViewController(user: user)
            self?.navigationController?.pushViewController(newChat, animated: true)
        }
        
        // Resume conversation
        chatHistory.onMessageClicked = { [weak self] message in
            let resumeChat = ProductionAIAgentViewController(
                user: user,
                parentMessage: message,
                isHistory: true
            )
            self?.navigationController?.pushViewController(resumeChat, animated: true)
        }
        
        // Close handler
        chatHistory.onClose = { [weak self] in
            self?.dismiss(animated: true)
        }
        
        addChild(chatHistory)
        view.addSubview(chatHistory.view)
        chatHistory.view.frame = view.bounds
        chatHistory.didMove(toParent: self)
    }
}
```

## Implementation Flow

| Step | Action                                           |
| ---- | ------------------------------------------------ |
| 1    | User selects AI agent from chat list             |
| 2    | Detect agent by checking user role for "agentic" |
| 3    | Launch `ProductionAIAgentViewController`         |
| 4    | Configure header, message list, and composer     |
| 5    | User sends message, AI responds with streaming   |
| 6    | Access chat history via header button            |

## Components Reference

| Component                          | Purpose                            |
| ---------------------------------- | ---------------------------------- |
| `CometChatMessageHeader`           | Navigation and chat history access |
| `CometChatMessageList`             | Display messages with AI responses |
| `CometChatMessageComposer`         | Send messages to AI agent          |
| `CometChatAIAssistanceChatHistory` | Browse previous AI conversations   |
| `CometChatAIAssistantBubble`       | AI message bubble styling          |

## Related Guides

<CardGroup>
  <Card title="AI Features" icon="sparkles" href="/ui-kit/ios/ai-features">
    Overview of all AI-powered features
  </Card>

  <Card title="AI Chat History" icon="clock-rotate-left" href="/ui-kit/ios/ai-assistant-chat-history">
    Browse and resume AI conversations
  </Card>

  <Card title="Message List" icon="list" href="/ui-kit/ios/message-list">
    Display and customize chat messages
  </Card>
</CardGroup>


# Block/Unblock User
Source: https://www.cometchat.com/docs/ui-kit/ios/guide-block-unblock-user

Build CometChat iOS UI Kit user profile actions for messaging, audio/video calls, block and unblock, and delete conversation flows.

Build a user profile screen with avatar display, messaging, audio/video calls, and block/unblock functionality using CometChat UIKit.

## Prerequisites

Before implementing this feature, ensure you have:

* Completed [Getting Started](/docs/ui-kit/ios/getting-started) setup
* CometChat UIKit v5+ installed
* User logged in with `CometChatUIKit.login()`
* Navigation controller configured

## Overview

The user details screen provides:

* **Profile Display** - Avatar, name, and online status
* **Messaging** - Start one-on-one chats
* **Calling** - Audio and video call buttons
* **Block/Unblock** - Manage user relationships
* **Delete Conversation** - Remove chat history

## Basic Implementation

Create a simple user details screen:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class UserDetailsViewController: UIViewController {
    
    private var user: User?
    
    convenience init(user: User) {
        self.init()
        self.user = user
    }
    
    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .systemBackground
        setupUI()
    }
    
    private func setupUI() {
        guard let user = user else { return }
        
        // Avatar
        let avatar = CometChatAvatar()
        avatar.set(user: user)
        avatar.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(avatar)

        // Name label
        let nameLabel = UILabel()
        nameLabel.text = user.name
        nameLabel.font = .systemFont(ofSize: 24, weight: .bold)
        nameLabel.textAlignment = .center
        nameLabel.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(nameLabel)
        
        // Status label
        let statusLabel = UILabel()
        statusLabel.text = user.status == .online ? "Online" : "Offline"
        statusLabel.textColor = user.status == .online ? .systemGreen : .secondaryLabel
        statusLabel.font = .systemFont(ofSize: 14)
        statusLabel.textAlignment = .center
        statusLabel.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(statusLabel)
        
        // Message button
        let messageButton = UIButton(type: .system)
        messageButton.setTitle("Message", for: .normal)
        messageButton.setImage(UIImage(systemName: "message.fill"), for: .normal)
        messageButton.addTarget(self, action: #selector(openChat), for: .touchUpInside)
        messageButton.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(messageButton)
        
        // Block button
        let blockButton = UIButton(type: .system)
        blockButton.setTitle("Block User", for: .normal)
        blockButton.setTitleColor(.systemRed, for: .normal)
        blockButton.addTarget(self, action: #selector(blockUser), for: .touchUpInside)
        blockButton.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(blockButton)
        
        NSLayoutConstraint.activate([
            avatar.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 40),
            avatar.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            avatar.widthAnchor.constraint(equalToConstant: 100),
            avatar.heightAnchor.constraint(equalToConstant: 100),
            
            nameLabel.topAnchor.constraint(equalTo: avatar.bottomAnchor, constant: 16),
            nameLabel.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            
            statusLabel.topAnchor.constraint(equalTo: nameLabel.bottomAnchor, constant: 8),
            statusLabel.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            
            messageButton.topAnchor.constraint(equalTo: statusLabel.bottomAnchor, constant: 32),
            messageButton.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            
            blockButton.topAnchor.constraint(equalTo: messageButton.bottomAnchor, constant: 24),
            blockButton.centerXAnchor.constraint(equalTo: view.centerXAnchor)
        ])
    }
    
    @objc private func openChat() {
        guard let user = user else { return }
        let messages = CometChatMessages()
        messages.set(user: user)
        navigationController?.pushViewController(messages, animated: true)
    }
    
    @objc private func blockUser() {
        guard let user = user else { return }
        CometChat.blockUsers([user.uid ?? ""]) { [weak self] _ in
            DispatchQueue.main.async {
                self?.showAlert(title: "Blocked", message: "\(user.name ?? "User") has been blocked")
            }
        } onError: { error in
            print("Block error: \(error?.errorDescription ?? "")")
        }
    }
    
    private func showAlert(title: String, message: String) {
        let alert = UIAlertController(title: title, message: message, preferredStyle: .alert)
        alert.addAction(UIAlertAction(title: "OK", style: .default))
        present(alert, animated: true)
    }
}
```

## Production Implementation

Complete user details screen with all features and event handling:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK
#if canImport(CometChatCallsSDK)
import CometChatCallsSDK
#endif

class ProductionUserDetailsViewController: UIViewController {
    
    // MARK: - Properties
    private var user: User?
    private var isBlocked: Bool = false
    private let listenerID = "user-details-listener"
    
    // MARK: - UI Components
    private let scrollView = UIScrollView()
    private let contentView = UIView()
    private let avatar = CometChatAvatar()
    private let nameLabel = UILabel()
    private let statusLabel = UILabel()
    private let buttonStackView = UIStackView()
    private let messageButton = UIButton(type: .system)
    private let audioCallButton = UIButton(type: .system)
    private let videoCallButton = UIButton(type: .system)
    private let blockButton = UIButton(type: .system)
    private let deleteButton = UIButton(type: .system)
    
    // MARK: - Initialization
    convenience init(user: User) {
        self.init()
        self.user = user
    }
    
    // MARK: - Lifecycle
    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .systemBackground
        setupUI()
        configureWithUser()
        checkBlockStatus()
        addEventListeners()
    }
    
    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        setupNavigationBar()
    }
    
    deinit {
        removeEventListeners()
    }

    // MARK: - Setup
    private func setupNavigationBar() {
        title = "User Details"
        navigationController?.navigationBar.prefersLargeTitles = false
    }
    
    private func setupUI() {
        // Scroll View
        scrollView.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(scrollView)
        
        contentView.translatesAutoresizingMaskIntoConstraints = false
        scrollView.addSubview(contentView)
        
        // Avatar
        avatar.translatesAutoresizingMaskIntoConstraints = false
        contentView.addSubview(avatar)
        
        // Name Label
        nameLabel.font = .systemFont(ofSize: 24, weight: .bold)
        nameLabel.textAlignment = .center
        nameLabel.translatesAutoresizingMaskIntoConstraints = false
        contentView.addSubview(nameLabel)
        
        // Status Label
        statusLabel.font = .systemFont(ofSize: 14)
        statusLabel.textAlignment = .center
        statusLabel.translatesAutoresizingMaskIntoConstraints = false
        contentView.addSubview(statusLabel)
        
        // Button Stack
        buttonStackView.axis = .horizontal
        buttonStackView.spacing = 24
        buttonStackView.distribution = .equalSpacing
        buttonStackView.translatesAutoresizingMaskIntoConstraints = false
        contentView.addSubview(buttonStackView)
        
        // Message Button
        configureButton(messageButton, title: "Message", icon: "message.fill", action: #selector(openChat))
        buttonStackView.addArrangedSubview(messageButton)
        
        // Call Buttons (conditional)
        #if canImport(CometChatCallsSDK)
        configureButton(audioCallButton, title: "Audio", icon: "phone.fill", action: #selector(startAudioCall))
        configureButton(videoCallButton, title: "Video", icon: "video.fill", action: #selector(startVideoCall))
        buttonStackView.addArrangedSubview(audioCallButton)
        buttonStackView.addArrangedSubview(videoCallButton)
        #endif
        
        // Block Button
        blockButton.setTitle("Block User", for: .normal)
        blockButton.setTitleColor(.systemRed, for: .normal)
        blockButton.titleLabel?.font = .systemFont(ofSize: 16, weight: .medium)
        blockButton.addTarget(self, action: #selector(toggleBlock), for: .touchUpInside)
        blockButton.translatesAutoresizingMaskIntoConstraints = false
        contentView.addSubview(blockButton)
        
        // Delete Button
        deleteButton.setTitle("Delete Conversation", for: .normal)
        deleteButton.setTitleColor(.systemRed, for: .normal)
        deleteButton.titleLabel?.font = .systemFont(ofSize: 16, weight: .medium)
        deleteButton.addTarget(self, action: #selector(deleteConversation), for: .touchUpInside)
        deleteButton.translatesAutoresizingMaskIntoConstraints = false
        contentView.addSubview(deleteButton)
        
        setupConstraints()
    }
    
    private func configureButton(_ button: UIButton, title: String, icon: String, action: Selector) {
        button.setTitle(title, for: .normal)
        button.setImage(UIImage(systemName: icon), for: .normal)
        button.titleLabel?.font = .systemFont(ofSize: 12)
        button.tintColor = .systemBlue
        button.configuration = .plain()
        button.configuration?.imagePlacement = .top
        button.configuration?.imagePadding = 8
        button.addTarget(self, action: action, for: .touchUpInside)
    }
    
    private func setupConstraints() {
        NSLayoutConstraint.activate([
            scrollView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
            scrollView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            scrollView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            scrollView.bottomAnchor.constraint(equalTo: view.bottomAnchor),
            
            contentView.topAnchor.constraint(equalTo: scrollView.topAnchor),
            contentView.leadingAnchor.constraint(equalTo: scrollView.leadingAnchor),
            contentView.trailingAnchor.constraint(equalTo: scrollView.trailingAnchor),
            contentView.bottomAnchor.constraint(equalTo: scrollView.bottomAnchor),
            contentView.widthAnchor.constraint(equalTo: scrollView.widthAnchor),
            
            avatar.topAnchor.constraint(equalTo: contentView.topAnchor, constant: 40),
            avatar.centerXAnchor.constraint(equalTo: contentView.centerXAnchor),
            avatar.widthAnchor.constraint(equalToConstant: 100),
            avatar.heightAnchor.constraint(equalToConstant: 100),
            
            nameLabel.topAnchor.constraint(equalTo: avatar.bottomAnchor, constant: 16),
            nameLabel.leadingAnchor.constraint(equalTo: contentView.leadingAnchor, constant: 20),
            nameLabel.trailingAnchor.constraint(equalTo: contentView.trailingAnchor, constant: -20),
            
            statusLabel.topAnchor.constraint(equalTo: nameLabel.bottomAnchor, constant: 8),
            statusLabel.centerXAnchor.constraint(equalTo: contentView.centerXAnchor),
            
            buttonStackView.topAnchor.constraint(equalTo: statusLabel.bottomAnchor, constant: 32),
            buttonStackView.centerXAnchor.constraint(equalTo: contentView.centerXAnchor),
            
            blockButton.topAnchor.constraint(equalTo: buttonStackView.bottomAnchor, constant: 48),
            blockButton.centerXAnchor.constraint(equalTo: contentView.centerXAnchor),
            
            deleteButton.topAnchor.constraint(equalTo: blockButton.bottomAnchor, constant: 16),
            deleteButton.centerXAnchor.constraint(equalTo: contentView.centerXAnchor),
            deleteButton.bottomAnchor.constraint(equalTo: contentView.bottomAnchor, constant: -40)
        ])
    }

    // MARK: - Configuration
    private func configureWithUser() {
        guard let user = user else { return }
        
        avatar.set(user: user)
        nameLabel.text = user.name
        updateStatusLabel(user: user)
    }
    
    private func updateStatusLabel(user: User) {
        if isBlocked {
            statusLabel.text = "Blocked"
            statusLabel.textColor = .systemRed
        } else {
            statusLabel.text = user.status == .online ? "Online" : "Offline"
            statusLabel.textColor = user.status == .online ? .systemGreen : .secondaryLabel
        }
    }
    
    private func checkBlockStatus() {
        guard let uid = user?.uid else { return }
        
        let request = BlockedUserRequest.BlockedUserRequestBuilder()
            .set(limit: 100)
            .build()
        
        request.fetchNext { [weak self] blockedUsers in
            let isBlocked = blockedUsers?.contains { $0.uid == uid } ?? false
            DispatchQueue.main.async {
                self?.isBlocked = isBlocked
                self?.updateBlockButton()
                self?.updateStatusLabel(user: self?.user ?? User())
            }
        } onError: { error in
            print("Error checking block status: \(error?.errorDescription ?? "")")
        }
    }
    
    private func updateBlockButton() {
        let title = isBlocked ? "Unblock User" : "Block User"
        blockButton.setTitle(title, for: .normal)
    }
    
    // MARK: - Actions
    @objc private func openChat() {
        guard let user = user else { return }
        
        if isBlocked {
            showAlert(title: "User Blocked", message: "Unblock this user to send messages")
            return
        }
        
        let messages = CometChatMessages()
        messages.set(user: user)
        navigationController?.pushViewController(messages, animated: true)
    }
    
    #if canImport(CometChatCallsSDK)
    @objc private func startAudioCall() {
        guard let user = user else { return }
        
        if isBlocked {
            showAlert(title: "User Blocked", message: "Unblock this user to make calls")
            return
        }
        
        let call = Call(receiverId: user.uid ?? "", callType: .audio, receiverType: .user)
        CometChat.initiateCall(call: call) { call in
            print("Audio call initiated: \(call?.sessionID ?? "")")
        } onError: { [weak self] error in
            self?.showAlert(title: "Call Failed", message: error?.errorDescription ?? "Unable to start call")
        }
    }
    
    @objc private func startVideoCall() {
        guard let user = user else { return }
        
        if isBlocked {
            showAlert(title: "User Blocked", message: "Unblock this user to make calls")
            return
        }
        
        let call = Call(receiverId: user.uid ?? "", callType: .video, receiverType: .user)
        CometChat.initiateCall(call: call) { call in
            print("Video call initiated: \(call?.sessionID ?? "")")
        } onError: { [weak self] error in
            self?.showAlert(title: "Call Failed", message: error?.errorDescription ?? "Unable to start call")
        }
    }
    #endif
    
    @objc private func toggleBlock() {
        if isBlocked {
            unblockUser()
        } else {
            showBlockConfirmation()
        }
    }
    
    private func showBlockConfirmation() {
        let alert = UIAlertController(
            title: "Block User",
            message: "Are you sure you want to block \(user?.name ?? "this user")? They won't be able to send you messages or call you.",
            preferredStyle: .alert
        )
        
        alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
        alert.addAction(UIAlertAction(title: "Block", style: .destructive) { [weak self] _ in
            self?.blockUser()
        })
        
        present(alert, animated: true)
    }
    
    private func blockUser() {
        guard let uid = user?.uid else { return }
        
        CometChat.blockUsers([uid]) { [weak self] blockedUsers in
            DispatchQueue.main.async {
                self?.isBlocked = true
                self?.updateBlockButton()
                self?.updateStatusLabel(user: self?.user ?? User())
                
                // Emit event for other components
                if let user = self?.user {
                    CometChatUserEvents.ccUserBlocked(user: user)
                }
            }
        } onError: { [weak self] error in
            self?.showAlert(title: "Error", message: error?.errorDescription ?? "Failed to block user")
        }
    }
    
    private func unblockUser() {
        guard let uid = user?.uid else { return }
        
        CometChat.unblockUsers([uid]) { [weak self] unblockedUsers in
            DispatchQueue.main.async {
                self?.isBlocked = false
                self?.updateBlockButton()
                self?.updateStatusLabel(user: self?.user ?? User())
                
                // Emit event for other components
                if let user = self?.user {
                    CometChatUserEvents.ccUserUnblocked(user: user)
                }
            }
        } onError: { [weak self] error in
            self?.showAlert(title: "Error", message: error?.errorDescription ?? "Failed to unblock user")
        }
    }
    
    @objc private func deleteConversation() {
        let alert = UIAlertController(
            title: "Delete Conversation",
            message: "Are you sure you want to delete this conversation? This action cannot be undone.",
            preferredStyle: .alert
        )
        
        alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
        alert.addAction(UIAlertAction(title: "Delete", style: .destructive) { [weak self] _ in
            self?.performDeleteConversation()
        })
        
        present(alert, animated: true)
    }
    
    private func performDeleteConversation() {
        guard let uid = user?.uid else { return }
        
        CometChat.deleteConversation(conversationWith: uid, conversationType: .user) { [weak self] _ in
            DispatchQueue.main.async {
                self?.showAlert(title: "Deleted", message: "Conversation has been deleted")
            }
        } onError: { [weak self] error in
            self?.showAlert(title: "Error", message: error?.errorDescription ?? "Failed to delete conversation")
        }
    }
    
    private func showAlert(title: String, message: String) {
        let alert = UIAlertController(title: title, message: message, preferredStyle: .alert)
        alert.addAction(UIAlertAction(title: "OK", style: .default))
        present(alert, animated: true)
    }

    // MARK: - Event Listeners
    private func addEventListeners() {
        CometChat.addUserListener(listenerID, self)
        CometChatUserEvents.addListener(listenerID, self)
    }
    
    private func removeEventListeners() {
        CometChat.removeUserListener(listenerID)
        CometChatUserEvents.removeListener(listenerID)
    }
}

// MARK: - CometChatUserDelegate
extension ProductionUserDetailsViewController: CometChatUserDelegate {
    
    func onUserOnline(user: User) {
        guard user.uid == self.user?.uid else { return }
        DispatchQueue.main.async {
            self.user = user
            self.updateStatusLabel(user: user)
        }
    }
    
    func onUserOffline(user: User) {
        guard user.uid == self.user?.uid else { return }
        DispatchQueue.main.async {
            self.user = user
            self.updateStatusLabel(user: user)
        }
    }
}

// MARK: - CometChatUserEventListener
extension ProductionUserDetailsViewController: CometChatUserEventListener {
    
    func ccUserBlocked(user: User) {
        guard user.uid == self.user?.uid else { return }
        DispatchQueue.main.async {
            self.isBlocked = true
            self.updateBlockButton()
            self.updateStatusLabel(user: user)
        }
    }
    
    func ccUserUnblocked(user: User) {
        guard user.uid == self.user?.uid else { return }
        DispatchQueue.main.async {
            self.isBlocked = false
            self.updateBlockButton()
            self.updateStatusLabel(user: user)
        }
    }
}
```

## Launching User Details

Open the user details screen from your app:

```swift lines theme={null}
import UIKit
import CometChatSDK

class UsersListViewController: UIViewController {
    
    func showUserDetails(for user: User) {
        let detailsVC = ProductionUserDetailsViewController(user: user)
        navigationController?.pushViewController(detailsVC, animated: true)
    }
    
    // From a users list
    func openFromUsersList() {
        let users = CometChatUsers()
        users.set(onItemClick: { [weak self] user, _ in
            self?.showUserDetails(for: user)
        })
        navigationController?.pushViewController(users, animated: true)
    }
    
    // From a conversation
    func openFromConversation(_ conversation: Conversation) {
        if let user = conversation.conversationWith as? User {
            showUserDetails(for: user)
        }
    }
}
```

## Block/Unblock API Reference

### Block Users

```swift lines theme={null}
// Block single user
CometChat.blockUsers(["user-uid"]) { blockedUsers in
    print("Blocked \(blockedUsers?.count ?? 0) users")
} onError: { error in
    print("Error: \(error?.errorDescription ?? "")")
}

// Block multiple users
CometChat.blockUsers(["user1", "user2", "user3"]) { blockedUsers in
    print("Blocked users: \(blockedUsers?.map { $0.uid ?? "" } ?? [])")
} onError: { error in
    print("Error: \(error?.errorDescription ?? "")")
}
```

### Unblock Users

```swift lines theme={null}
// Unblock single user
CometChat.unblockUsers(["user-uid"]) { unblockedUsers in
    print("Unblocked \(unblockedUsers?.count ?? 0) users")
} onError: { error in
    print("Error: \(error?.errorDescription ?? "")")
}

// Unblock multiple users
CometChat.unblockUsers(["user1", "user2"]) { unblockedUsers in
    print("Unblocked users: \(unblockedUsers?.map { $0.uid ?? "" } ?? [])")
} onError: { error in
    print("Error: \(error?.errorDescription ?? "")")
}
```

### Fetch Blocked Users

```swift lines theme={null}
let request = BlockedUserRequest.BlockedUserRequestBuilder()
    .set(limit: 50)
    .set(direction: .blockedByMe)  // or .hasBlockedMe, .both
    .build()

request.fetchNext { blockedUsers in
    for user in blockedUsers ?? [] {
        print("Blocked: \(user.name ?? "")")
    }
} onError: { error in
    print("Error: \(error?.errorDescription ?? "")")
}
```

## Styling

Customize the avatar appearance:

```swift lines theme={null}
let avatarStyle = AvatarStyle()
avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 50)
avatarStyle.borderWidth = 2
avatarStyle.borderColor = .systemBlue
avatarStyle.backgroundColor = .systemGray5

avatar.set(style: avatarStyle)
```

## Components Reference

| Component                        | Purpose                      |
| -------------------------------- | ---------------------------- |
| `CometChatAvatar`                | Display user profile picture |
| `CometChatMessages`              | Open chat interface          |
| `CometChat.blockUsers()`         | Block users                  |
| `CometChat.unblockUsers()`       | Unblock users                |
| `CometChat.deleteConversation()` | Delete chat history          |
| `CometChat.initiateCall()`       | Start audio/video calls      |

## Edge Cases

* **Self-blocking**: Hide block controls when viewing your own profile
* **Already blocked**: Check block status before showing chat/call options
* **Call SDK unavailable**: Conditionally show call buttons with `#if canImport(CometChatCallsSDK)`
* **Missing user data**: Show placeholder UI for incomplete profiles

## Error Handling

| Error                      | Solution                             |
| -------------------------- | ------------------------------------ |
| Block failed               | Show retry option, check network     |
| Unblock failed             | Verify user was previously blocked   |
| Call initiation failed     | Check permissions and call SDK setup |
| Delete conversation failed | Verify conversation exists           |

## Related Guides

<CardGroup>
  <Card title="Users" icon="user" href="/ui-kit/ios/users">
    Display and manage user list
  </Card>

  <Card title="Events" icon="bell" href="/ui-kit/ios/events">
    Handle user and block events
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/ios/conversations">
    View and manage conversations
  </Card>
</CardGroup>

***

<CardGroup>
  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5/SampleApp">
    Complete implementation example
  </Card>

  <Card title="UIKit Source" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5">
    CometChat UIKit iOS repository
  </Card>
</CardGroup>


# Call Log Details
Source: https://www.cometchat.com/docs/ui-kit/ios/guide-call-log-details

Show CometChat iOS UI Kit call log details with call history, participants, recordings, tabbed views, and Calls SDK integration.

Learn how to integrate and customize CometChat's call log components to display call history, participant details, and call recordings in your iOS app.

## Overview

The `CallLogDetailsVC` module provides a tabbed interface for viewing details of past calls:

* **History** — Chronological join/leave events with timestamps
* **Participants** — Users who joined the call
* **Recordings** — Links to cloud-hosted call recordings

This ensures transparency and auditability for both users and administrators.

## Prerequisites

Before implementing call log details, ensure you have:

* Completed [Getting Started](/docs/ui-kit/ios/getting-started) setup
* CometChat UIKit v5+ installed
* CometChatCallsSDK integrated
* User logged in with `CometChatUIKit.login()`
* Active internet connection

## Components

| Component                  | Description                                                       |
| -------------------------- | ----------------------------------------------------------------- |
| `CallLogDetailsVC`         | Main container with segmented control and page view               |
| `CallLogParticipantsVC`    | Displays a list of users who participated in the call             |
| `CallLogHistoryVC`         | Shows join/leave history entries with timestamps and statuses     |
| `CallLogRecordingsVC`      | Lists call recordings with playback actions                       |
| `CallLogDetailsHeaderView` | Header view showing call metadata (title, status, duration)       |
| `CallLogUserCell`          | UITableViewCell for participants, history, and recordings entries |
| `CallLogDetailsModel`      | Data model formatting participants, history, and recordings data  |
| `CallLogViewModel`         | Fetches and distributes call log data to the UI components        |

## Integration Steps

### Step 1: Present Call Log Details Screen

Show the call log interface for a selected call:

```swift lines theme={null}
import UIKit
import CometChatSDK
import CometChatCallsSDK

class CallLogsViewController: UIViewController {
    
    func showCallDetails(for call: CallLog) {
        // Initialize the call log details view controller
        let detailsVC = CallLogDetailsVC(call: call)
        
        // Push onto navigation stack
        navigationController?.pushViewController(detailsVC, animated: true)
    }
}
```

This bundles history, participants, and recordings into a single UI flow.

**File reference:** [`CallLogDetailsVC.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/Call%20Log%20Details/CallLogDetailsVC.swift)

### Step 2: Display Participants List

Populate the participants tab with the call's members:

```swift lines theme={null}
import UIKit
import CometChatSDK

class CallLogParticipantsVC: UIViewController {
    
    var participants: [Participant] = []
    @IBOutlet weak var participantsTableView: UITableView!
    
    func loadParticipants() {
        // Fetch participants from call log data
        // ...
        
        // Reload table view to display participants
        participantsTableView.reloadData()
    }
}
```

This provides an audit trail of who was present in the call.

**File reference:** [`CallLogParticipantsVC.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/Call%20Log%20Details/Call%20Participants/CallLogParticipantsVC.swift)

### Step 3: Show Call History

Render join/leave activities in chronological order:

```swift lines theme={null}
import UIKit

class CallLogHistoryVC: UIViewController {
    
    var history: [CallHistoryEntry] = []
    @IBOutlet weak var tableView: UITableView!
    
    func addHistoryEntry(user: String, action: String, timestamp: Date) {
        // Create and append new history entry
        let entry = CallHistoryEntry(user: user, action: action, timestamp: timestamp)
        history.append(entry)
        
        // Refresh the table view
        tableView.reloadData()
    }
}
```

This tracks user join/leave times for transparency.

**File references:**

* [`CallHistoyTVC.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/Call%20Log%20Details/Call%20History%20/CallHistoyTVC.swift)
* [`CallLogHistoryVC.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/Call%20Log%20Details/Call%20History%20/CallLogHistoryVC.swift)

### Step 4: List and Play Recordings

Provide playback links for any recorded calls:

```swift lines theme={null}
import UIKit

class CallLogRecordingsVC: UIViewController {
    
    func playRecording(url: URL) {
        // Open recording URL in default browser/player
        UIApplication.shared.open(url)
    }
}
```

This enables administrators and users to review call content (if recording is enabled).

**File references:**

* [`CallLogRecordingsVC.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/Call%20Log%20Details/Call%20Recording%20/CallLogRecordingsVC.swift)
* [`CallRecordingTVC.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/Call%20Log%20Details/Call%20Recording%20/CallRecordingTVC.swift)

## Customization Options

### Styling

Customize colors, fonts, and spacing using CometChat's theming system:

```swift lines theme={null}
import CometChatUIKitSwift

// Apply custom theme to call log components
let theme = CometChatTheme()
theme.palette.primary = UIColor.systemBlue

// Apply typography
let typography = CometChatTypography()
typography.heading = UIFont.systemFont(ofSize: 18, weight: .bold)

// Apply spacing
let spacing = CometChatSpacing()
spacing.padding = 16
```

### Filters

Use `CallLogViewModel` to filter by call type:

```swift lines theme={null}
// Filter by call type
viewModel.filterByType(.incoming)   // Show only incoming calls
viewModel.filterByType(.outgoing)   // Show only outgoing calls
viewModel.filterByType(.missed)     // Show only missed calls
```

### Empty States

Implement an `EmptyStateView` in `CallLogHistoryVC` for no-history scenarios:

```swift lines theme={null}
func showEmptyState() {
    let emptyView = UILabel()
    emptyView.text = "No call history available"
    emptyView.textAlignment = .center
    emptyView.textColor = .secondaryLabel
    tableView.backgroundView = emptyView
}
```

## Edge Cases

| Scenario              | Handling                                                                     |
| --------------------- | ---------------------------------------------------------------------------- |
| No call logs          | Show a custom empty state instead of a blank table                           |
| Large history         | Add lazy loading in `scrollViewDidScroll` to fetch more entries              |
| Blocked users         | Disable profile navigation in `CallLogParticipantsVC` if the user is blocked |
| Missing recording URL | Gracefully disable playback links                                            |

## Error Handling

| Error Type            | Solution                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------- |
| Network/API errors    | Display `UIAlertController` on fetch failures; expose error via `CallLogViewModel` delegate |
| Retry mechanism       | Add pull-to-refresh or a retry button in `CallLogDetailsVC`                                 |
| Recording unavailable | Gracefully disable playback links if URL is missing                                         |

## Additional Notes

* **Group Calls vs 1:1 Calls** — Customize `CallLogParticipantsVC` display based on call type and participant roles
* **Metadata Display** — Use `CallLogDetailsHeaderView` to show titles, call duration, and status icons

## Feature Matrix

| Feature                      | Component / Method         | File(s)                                               |
| ---------------------------- | -------------------------- | ----------------------------------------------------- |
| Show call log details screen | `CallLogDetailsVC(call:)`  | `CallLogDetailsVC.swift`                              |
| Display participants         | `CallLogParticipantsVC`    | `CallLogParticipantsVC.swift`                         |
| Display history entries      | `CallLogHistoryVC`         | `CallHistoyTVC.swift`, `CallLogHistoryVC.swift`       |
| List recordings              | `CallLogRecordingsVC`      | `CallLogRecordingsVC.swift`, `CallRecordingTVC.swift` |
| Header metadata              | `CallLogDetailsHeaderView` | `CallLogDetailsHeaderView.swift`                      |
| Data handling                | `CallLogDetailsModel`      | `CallLogDetailsModel.swift`                           |
| Data fetching & distribution | `CallLogViewModel`         | `CallLogViewModel.swift`                              |

## Related Components

* [Call Logs](/docs/ui-kit/ios/call-logs) - Display call log list
* [Call Features](/docs/ui-kit/ios/call-features) - Overview of calling capabilities
* [Ongoing Call](/docs/ui-kit/ios/ongoing-call) - Active call interface

<CardGroup>
  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5/SampleApp">
    Explore a full sample implementation
  </Card>

  <Card title="UIKit Source" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5/SampleApp/View%20Controllers/CometChat%20Components/Call%20Log%20Details">
    Review the call log components in the UIKit library
  </Card>
</CardGroup>

## Related Guides

<CardGroup>
  <Card title="Call Logs" icon="phone" href="/ui-kit/ios/call-logs">
    Display call history list
  </Card>

  <Card title="Call Features" icon="video" href="/ui-kit/ios/call-features">
    Overview of calling capabilities
  </Card>

  <Card title="Events" icon="bell" href="/ui-kit/ios/events">
    Handle call events
  </Card>
</CardGroup>


# Group Details
Source: https://www.cometchat.com/docs/ui-kit/ios/guide-group-chat

Display CometChat iOS UI Kit group details with group info, join, leave, delete, member management, and real-time group events.

Provide a detailed view for CometChat groups in your iOS app, enabling users to see group info, join/leave, manage members, and respond to real-time group events.

## Overview

`GroupDetailsViewController` displays comprehensive group information and actions:

* **Group Info** — Name, icon, description, and member count
* **Actions** — Join, leave, or delete group
* **Member Management** — View members, add members, view banned members
* **Real-Time Updates** — Reflects joins, leaves, bans, and ownership changes

## Prerequisites

Before implementing group details, ensure you have:

* Completed [Getting Started](/docs/ui-kit/ios/getting-started) setup
* CometChat UIKit v5+ installed via CocoaPods or Swift Package Manager
* Valid CometChat App ID, Region, and Auth Key
* User logged in with `CometChatUIKit.login()`
* Navigation controller (`UINavigationController`) configured

## Components

| Component                         | Description                                              |
| --------------------------------- | -------------------------------------------------------- |
| `CometChatGroup`                  | Renders group avatar, name, and metadata                 |
| `GroupActionView`                 | Custom view for action buttons (view/add/banned members) |
| `CometChatMessagesViewController` | Opens group chat interface when "Chat" is tapped         |
| `CometChat.joinGroup()`           | Joins public or password-protected groups                |
| `CometChat.leaveGroup()`          | Leaves the current group                                 |
| `CometChat.deleteGroup()`         | Deletes and exits the group (owners only)                |
| `CometChatGroupMembers`           | Lists current group members                              |
| `CometChatGroupDelegate`          | Receives real-time group events                          |

## Integration Steps

### Step 1: Present the Group Details Screen

Push `GroupDetailsViewController` for a selected group:

```swift lines theme={null}
import UIKit
import CometChatSDK

class GroupListViewController: UIViewController {
    
    func showGroupDetails(for group: Group) {
        // Initialize the group details view controller
        let detailsVC = GroupDetailsViewController()
        detailsVC.group = group
        
        // Push onto navigation stack
        navigationController?.pushViewController(detailsVC, animated: true)
    }
}
```

This initializes and presents the details UI with the correct group context.

**File reference:** [`HomeScreenViewController.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/HomeScreenViewController.swift)

### Step 2: Set Up the UI

Configure scroll view, header, and action views:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class GroupDetailsViewController: UIViewController {
    
    var group: Group?
    
    override public func viewDidLoad() {
        super.viewDidLoad()
        
        // Connect to group event listeners
        connect()
        
        // Apply theme
        view.backgroundColor = CometChatTheme.backgroundColor01
        
        // Set up UI components
        setupScrollView()
        setupLayout()
        addButtonActions()
    }
    
    private func setupScrollView() {
        // Configure scroll view for content
    }
    
    private func setupLayout() {
        // Arrange header, info, and action views
    }
}
```

This lays out the UI components and registers for group events.

**File reference:** [`GroupDetailsViewController.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/DetailsPage/GroupDetailsViewController.swift)

### Step 3: Enable Group Action Buttons

Wire up view/add/banned members actions:

```swift lines theme={null}
// Action views for member management
private let viewMembersView = GroupActionView()
private let addMembersView = GroupActionView()
private let bannedMembersView = GroupActionView()

public func addButtonActions() {
    // View current group members
    viewMembersView.onActionButtonTapped = { [weak self] in
        self?.viewMembers()
    }
    
    // Add new members to the group
    addMembersView.onActionButtonTapped = { [weak self] in
        self?.addMembers()
    }
    
    // View banned members
    bannedMembersView.onActionButtonTapped = { [weak self] in
        self?.banMembers()
    }
}

private func viewMembers() {
    guard let group = group else { return }
    let membersVC = CometChatGroupMembers()
    membersVC.set(group: group)
    navigationController?.pushViewController(membersVC, animated: true)
}

private func addMembers() {
    // Present add members interface
}

private func banMembers() {
    // Present banned members list
}
```

This enables user interaction for member management.

**File reference:** [`GroupDetailsViewController.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/DetailsPage/GroupDetailsViewController.swift)

### Step 4: Handle Leave and Delete Actions

Provide ownership-aware leave/delete flows:

```swift lines theme={null}
@objc func showLeaveGroupAlert() {
    guard let group = group else { return }
    
    let alert = UIAlertController(
        title: "Leave Group",
        message: "Are you sure you want to leave this group?",
        preferredStyle: .alert
    )
    
    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
    alert.addAction(UIAlertAction(title: "Leave", style: .destructive) { [weak self] _ in
        self?.leaveGroup()
    })
    
    present(alert, animated: true)
}

@objc func showDeleteGroupAlert() {
    guard let group = group else { return }
    
    let alert = UIAlertController(
        title: "Delete Group",
        message: "Are you sure you want to delete this group? This action cannot be undone.",
        preferredStyle: .alert
    )
    
    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
    alert.addAction(UIAlertAction(title: "Delete", style: .destructive) { [weak self] _ in
        self?.deleteGroup()
    })
    
    present(alert, animated: true)
}

private func leaveGroup() {
    guard let guid = group?.guid else { return }
    
    CometChat.leaveGroup(GUID: guid) { [weak self] _ in
        DispatchQueue.main.async {
            self?.navigationController?.popToRootViewController(animated: true)
        }
    } onError: { error in
        print("Leave group error: \(error?.errorDescription ?? "")")
    }
}

private func deleteGroup() {
    guard let guid = group?.guid else { return }
    
    CometChat.deleteGroup(GUID: guid) { [weak self] _ in
        DispatchQueue.main.async {
            self?.navigationController?.popToRootViewController(animated: true)
        }
    } onError: { error in
        print("Delete group error: \(error?.errorDescription ?? "")")
    }
}
```

This manages group exit, with transfer prompt for owners.

**File reference:** [`GroupDetailsViewController.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/DetailsPage/GroupDetailsViewController.swift)

### Step 5: Listen for Group Events

Update UI on member joins, leaves, bans, and ownership changes:

```swift lines theme={null}
private let listenerId = "group-details-listener"

func connect() {
    // Add SDK group listener
    CometChat.addGroupListener(listenerId, self)
    
    // Add UIKit group events listener
    CometChatGroupEvents.addListener(listenerId, self)
}

func disconnect() {
    CometChat.removeGroupListener(listenerId)
    CometChatGroupEvents.removeListener(listenerId)
}

deinit {
    disconnect()
}
```

```swift lines theme={null}
// MARK: - CometChatGroupDelegate
extension GroupDetailsViewController: CometChatGroupDelegate {
    
    func onGroupMemberJoined(action: ActionMessage, joinedUser: User, joinedGroup: Group) {
        updateGroupInfo(joinedGroup)
    }
    
    func onGroupMemberLeft(action: ActionMessage, leftUser: User, leftGroup: Group) {
        // Hide UI if current user left
        if leftUser.uid == CometChat.getLoggedInUser()?.uid {
            navigationController?.popViewController(animated: true)
        } else {
            updateGroupInfo(leftGroup)
        }
    }
    
    func onGroupMemberKicked(action: ActionMessage, kickedUser: User, kickedBy: User, kickedFrom: Group) {
        updateGroupInfo(kickedFrom)
    }
    
    func onGroupMemberBanned(action: ActionMessage, bannedUser: User, bannedBy: User, bannedFrom: Group) {
        updateGroupInfo(bannedFrom)
    }
    
    func onGroupMemberUnbanned(action: ActionMessage, unbannedUser: User, unbannedBy: User, unbannedFrom: Group) {
        updateGroupInfo(unbannedFrom)
    }
    
    func onGroupMemberScopeChanged(action: ActionMessage, scopeChangeduser: User, scopeChangedBy: User, scopeChangedTo: String, scopeChangedFrom: String, group: Group) {
        updateGroupInfo(group)
    }
    
    func onMemberAddedToGroup(action: ActionMessage, addedBy: User, addedUser: User, addedTo: Group) {
        updateGroupInfo(addedTo)
    }
}

// MARK: - CometChatGroupEventListener
extension GroupDetailsViewController: CometChatGroupEventListener {
    
    func ccOwnershipChanged(group: Group, newOwner: GroupMember) {
        updateGroupInfo(group)
    }
}

private func updateGroupInfo(_ group: Group) {
    self.group = group
    // Refresh UI with updated group data
}
```

This keeps the group details in sync with back-end events.

**File reference:** [`GroupDetailsViewController.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/DetailsPage/GroupDetailsViewController.swift#L200-L245)

## Customization Options

### Header Styling

Use `CometChatTheme` to customize fonts, colors, and borders:

```swift lines theme={null}
// Apply custom theme
CometChatTheme.palette.primary = UIColor.systemBlue
CometChatTheme.typography.heading = UIFont.systemFont(ofSize: 20, weight: .bold)
```

### Button Labels

Localize or rebrand action texts:

```swift lines theme={null}
viewMembersView.setTitle("View Members", for: .normal)
addMembersView.setTitle("Add Members", for: .normal)
bannedMembersView.setTitle("Banned Members", for: .normal)
```

### Avatar Placeholder

Provide fallback initials or default images:

```swift lines theme={null}
avatarView.set(name: group.name)
avatarView.set(image: UIImage(named: "default_group_avatar"))
```

## Edge Cases

| Scenario                 | Handling                             |
| ------------------------ | ------------------------------------ |
| Private/Protected groups | Prompt for a password before joining |
| Already a member         | Hide or disable Join button          |
| Empty group              | Show an empty state when no members  |
| Owner restrictions       | Disable Delete for non-owners        |

## Error Handling

| Error Type          | Solution                                   |
| ------------------- | ------------------------------------------ |
| Join failures       | Show alert on network or permission errors |
| Leave/Delete errors | Display retry prompt on API failure        |
| Event errors        | Log and notify user if group events fail   |

## Feature Matrix

| Feature            | Component / Method           | File(s)                            |
| ------------------ | ---------------------------- | ---------------------------------- |
| Show group details | `GroupDetailsViewController` | `GroupDetailsViewController.swift` |
| View group members | `viewMembersView` action     | `GroupDetailsViewController.swift` |
| Add members        | `addMembersView` action      | `GroupDetailsViewController.swift` |
| Ban members        | `bannedMembersView` action   | `GroupDetailsViewController.swift` |
| Join group         | `CometChat.joinGroup()`      | `GroupDetailsViewController.swift` |
| Leave group        | `showLeaveGroupAlert()`      | `GroupDetailsViewController.swift` |
| Delete group       | `showDeleteGroupAlert()`     | `GroupDetailsViewController.swift` |
| Real-time updates  | `CometChatGroupDelegate`     | `GroupDetailsViewController.swift` |

## Related Components

* [Groups](/docs/ui-kit/ios/groups) - Display group list
* [Group Members](/docs/ui-kit/ios/group-members) - Display group member list
* [Events](/docs/ui-kit/ios/events) - Listen for chat events

<CardGroup>
  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5/SampleApp">
    Explore the complete Group Details flow
  </Card>

  <Card title="UIKit Source" href="https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/DetailsPage/GroupDetailsViewController.swift">
    Browse the Group Details implementation
  </Card>
</CardGroup>

## Related Guides

<CardGroup>
  <Card title="Groups" icon="users" href="/ui-kit/ios/groups">
    Display and manage group list
  </Card>

  <Card title="Group Members" icon="user-group" href="/ui-kit/ios/group-members">
    View and manage group membership
  </Card>

  <Card title="Events" icon="bell" href="/ui-kit/ios/events">
    Handle group and membership events
  </Card>
</CardGroup>


# Transfer Group Ownership
Source: https://www.cometchat.com/docs/ui-kit/ios/guide-group-ownership

Transfer CometChat iOS UI Kit group ownership to another member with member selection, ownership API calls, and post-transfer flow.

Enable the current group owner to delegate ownership to another member using CometChat's UIKit for iOS.

## Overview

The Transfer Group Ownership feature provides a modal interface where the group owner can:

* See a list of current group members (excluding themselves)
* Select exactly one member to become the new owner
* Trigger the ownership transfer API call
* Automatically exit the group after successful transfer

## Prerequisites

Before implementing ownership transfer, ensure you have:

* Completed [Getting Started](/docs/ui-kit/ios/getting-started) setup
* CometChat UIKit v5+ installed via CocoaPods or Swift Package Manager
* CometChatSDK and CometChatUIKitSwift integrated
* User logged in with `CometChatUIKit.login()`
* `UINavigationController` or modal presentation flow set up
* Group context (GUID) available when invoking the transfer screen

## Components

| Component                          | Description                                                        |
| ---------------------------------- | ------------------------------------------------------------------ |
| `TransferOwnership`                | Subclass of `CometChatGroupMembers` enabling single selection mode |
| `viewModel.groupMembers`           | Data source array of `GroupMember` objects                         |
| `onSelectedItemProceed`            | Closure invoked when user confirms selection                       |
| `CometChat.transferGroupOwnership` | API call to delegate group ownership                               |
| `spinnerView`                      | `UIActivityIndicatorView` showing loading state                    |
| `leaveGroupCallback`               | Callback to perform group exit after transfer                      |

## Integration Steps

### Step 1: Present Transfer Ownership Screen

Show the ownership transfer UI modally:

```swift lines theme={null}
import UIKit
import CometChatSDK
import CometChatUIKitSwift

class GroupDetailsViewController: UIViewController {
    
    var group: Group?
    
    func showTransferOwnership(for group: Group) {
        // Initialize transfer ownership view controller
        let transferVC = TransferOwnership()
        transferVC.set(group: group)
        
        // Set callback for after transfer completes
        transferVC.leaveGroupCallback = { [weak self] in
            self?.leaveGroup()
        }
        
        // Present modally with navigation
        let nav = UINavigationController(rootViewController: transferVC)
        present(nav, animated: true)
    }
    
    private func leaveGroup() {
        // Handle leaving group after ownership transfer
        navigationController?.popToRootViewController(animated: true)
    }
}
```

**File reference:** [`GroupDetailsViewController.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/DetailsPage/GroupDetailsViewController.swift)

### Step 2: Configure Single Selection Mode

Restrict selection to one member and capture selection:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class TransferOwnership: CometChatGroupMembers {
    
    var leaveGroupCallback: (() -> Void)?
    
    private let spinnerView: UIActivityIndicatorView = {
        let spinner = UIActivityIndicatorView(style: .medium)
        spinner.hidesWhenStopped = true
        return spinner
    }()
    
    override func viewDidLoad() {
        // Enable single selection mode
        selectionMode = .single
        
        super.viewDidLoad()
        
        // Set navigation title
        title = "OWNERSHIP_TRANSFER".localize()
        
        // Handle member selection
        onSelectedItemProceed = { [weak self] users in
            if let newOwner = users.first as? GroupMember {
                self?.transferOwnership(to: newOwner)
            }
        }
    }
}
```

**File reference:** [`TransferOwnership.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/Transfer%20ownership%20/TransferOwnership.swift#L1-L30)

### Step 3: Load and Filter Member List

Exclude the current owner from the selectable list:

```swift lines theme={null}
override func reloadData() {
    super.reloadData()
    
    viewModel.reload = { [weak self] in
        guard let self = self else { return }
        
        // Get current user's UID
        let currentUID = CometChat.getLoggedInUser()?.uid
        
        // Remove current owner from the list
        self.viewModel.groupMembers.removeAll { $0.uid == currentUID }
        
        DispatchQueue.main.async {
            // Update UI state
            self.removeLoadingView()
            self.removeErrorView()
            self.reload()
            
            // Show empty state if no eligible members
            if self.viewModel.groupMembers.isEmpty {
                self.showEmptyView()
            }
        }
    }
}
```

**File reference:** [`TransferOwnership.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/Transfer%20ownership%20/TransferOwnership.swift#L31-L60)

### Step 4: Perform Ownership Transfer

Call the API, emit event, and exit the group:

```swift lines theme={null}
func transferOwnership(to member: GroupMember) {
    // Show loading indicator
    addSpinnerView()
    
    let uid = member.uid ?? ""
    let guid = viewModel.group.guid
    
    CometChat.transferGroupOwnership(UID: uid, GUID: guid) { [weak self] successMessage in
        DispatchQueue.main.async {
            guard let self = self else { return }
            
            // Update local group state
            self.viewModel.group.owner = uid
            
            // Emit ownership changed event for other components
            CometChatGroupEvents.ccOwnershipChanged(
                group: self.viewModel.group,
                newOwner: member
            )
            
            // Execute leave group callback
            self.leaveGroupCallback?()
            
            // Hide loading and dismiss
            self.removeSpinnerView()
            self.dismiss(animated: true)
        }
    } onError: { [weak self] error in
        DispatchQueue.main.async {
            self?.removeSpinnerView()
            
            // Show error alert
            let alert = UIAlertController(
                title: "Transfer Failed",
                message: error?.errorDescription ?? "Unable to transfer ownership",
                preferredStyle: .alert
            )
            alert.addAction(UIAlertAction(title: "OK", style: .default))
            self?.present(alert, animated: true)
        }
    }
}
```

**File reference:** [`TransferOwnership.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/Transfer%20ownership%20/TransferOwnership.swift#L61-L100)

### Step 5: Manage Loading State

Provide visual feedback during network calls:

```swift lines theme={null}
func addSpinnerView() {
    // Start spinner animation
    spinnerView.startAnimating()
    
    // Replace right bar button with spinner
    navigationItem.rightBarButtonItem = UIBarButtonItem(customView: spinnerView)
}

func removeSpinnerView() {
    // Stop spinner animation
    spinnerView.stopAnimating()
    
    // Remove spinner from navigation bar
    navigationItem.rightBarButtonItem = nil
}
```

**File reference:** [`TransferOwnership.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/Transfer%20ownership%20/TransferOwnership.swift#L101-L130)

## Complete Implementation

Here's the complete `TransferOwnership` class:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class TransferOwnership: CometChatGroupMembers {
    
    // MARK: - Properties
    var leaveGroupCallback: (() -> Void)?
    
    private let spinnerView: UIActivityIndicatorView = {
        let spinner = UIActivityIndicatorView(style: .medium)
        spinner.hidesWhenStopped = true
        return spinner
    }()
    
    // MARK: - Lifecycle
    override func viewDidLoad() {
        selectionMode = .single
        super.viewDidLoad()
        
        title = "Transfer Ownership"
        
        onSelectedItemProceed = { [weak self] users in
            if let newOwner = users.first as? GroupMember {
                self?.transferOwnership(to: newOwner)
            }
        }
    }
    
    // MARK: - Data Loading
    override func reloadData() {
        super.reloadData()
        
        viewModel.reload = { [weak self] in
            guard let self = self else { return }
            
            let currentUID = CometChat.getLoggedInUser()?.uid
            self.viewModel.groupMembers.removeAll { $0.uid == currentUID }
            
            DispatchQueue.main.async {
                self.removeLoadingView()
                self.removeErrorView()
                self.reload()
                
                if self.viewModel.groupMembers.isEmpty {
                    self.showEmptyView()
                }
            }
        }
    }
    
    // MARK: - Transfer Ownership
    func transferOwnership(to member: GroupMember) {
        addSpinnerView()
        
        let uid = member.uid ?? ""
        let guid = viewModel.group.guid
        
        CometChat.transferGroupOwnership(UID: uid, GUID: guid) { [weak self] _ in
            DispatchQueue.main.async {
                guard let self = self else { return }
                
                self.viewModel.group.owner = uid
                CometChatGroupEvents.ccOwnershipChanged(
                    group: self.viewModel.group,
                    newOwner: member
                )
                
                self.leaveGroupCallback?()
                self.removeSpinnerView()
                self.dismiss(animated: true)
            }
        } onError: { [weak self] error in
            DispatchQueue.main.async {
                self?.removeSpinnerView()
                self?.showError(error)
            }
        }
    }
    
    // MARK: - Loading State
    func addSpinnerView() {
        spinnerView.startAnimating()
        navigationItem.rightBarButtonItem = UIBarButtonItem(customView: spinnerView)
    }
    
    func removeSpinnerView() {
        spinnerView.stopAnimating()
        navigationItem.rightBarButtonItem = nil
    }
    
    // MARK: - Error Handling
    private func showError(_ error: CometChatException?) {
        let alert = UIAlertController(
            title: "Transfer Failed",
            message: error?.errorDescription ?? "Unable to transfer ownership",
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "OK", style: .default))
        present(alert, animated: true)
    }
}
```

## Customization Options

### Title Text

Replace localization key with custom string:

```swift lines theme={null}
title = "Select New Owner"
```

### Spinner Style

Adjust `spinnerView.style` and color using `CometChatTheme`:

```swift lines theme={null}
spinnerView.style = .large
spinnerView.color = CometChatTheme.palette.primary
```

### Error Handling

Customize error alerts in the `onError` closure:

```swift lines theme={null}
let alert = UIAlertController(
    title: "Oops!",
    message: "Could not transfer ownership. Please try again.",
    preferredStyle: .alert
)
alert.addAction(UIAlertAction(title: "Retry", style: .default) { [weak self] _ in
    self?.transferOwnership(to: member)
})
alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
present(alert, animated: true)
```

## Edge Cases

| Scenario          | Handling                                                       |
| ----------------- | -------------------------------------------------------------- |
| Empty member list | Show an informative empty state when no eligible members exist |
| Network failures  | Disable proceed button until connection restores               |
| Blocked members   | Exclude or disable blocked users from selection                |

## Error Handling

| Error Type        | Solution                                                |
| ----------------- | ------------------------------------------------------- |
| Transfer failures | Present `UIAlertController` with retry option           |
| Unexpected states | Ensure `removeSpinnerView()` always executes in `defer` |

## Feature Matrix

| Feature                     | Method / Component                        | File(s)                            |
| --------------------------- | ----------------------------------------- | ---------------------------------- |
| Launch transfer flow        | `showTransferOwnership(for:)`             | `GroupDetailsViewController.swift` |
| Single-member selection     | `selectionMode = .single`                 | `TransferOwnership.swift`          |
| Filter out current owner    | `reloadData()` override                   | `TransferOwnership.swift`          |
| Execute API transfer        | `CometChat.transferGroupOwnership()`      | `TransferOwnership.swift`          |
| Show/hide loading indicator | `addSpinnerView()`, `removeSpinnerView()` | `TransferOwnership.swift`          |

## Related Guides

<CardGroup>
  <Card title="Groups" icon="users" href="/ui-kit/ios/groups">
    Display and manage groups
  </Card>

  <Card title="Group Members" icon="user-group" href="/ui-kit/ios/group-members">
    View and manage group membership
  </Card>

  <Card title="Group Chat Guide" icon="comments" href="/ui-kit/ios/guide-group-chat">
    Complete group management guide
  </Card>
</CardGroup>


# Message Privately
Source: https://www.cometchat.com/docs/ui-kit/ios/guide-message-privately

Start private one-to-one chats from CometChat iOS UI Kit group conversations with message options, user lookup, and chat navigation.

Enable users to start a private one-on-one chat with a group member directly from a group chat screen using CometChat's UIKit for iOS.

## Overview

The Message Privately feature allows users to long-press a message in a group chat and select **Message Privately** to transition into a private conversation with the original sender. This streamlines side discussions and follow-ups without requiring manual user searches.

## Prerequisites

Before implementing this feature, ensure you have:

1. Completed [Getting Started](/docs/ui-kit/ios/getting-started) setup
2. CometChat UIKit v5+ installed
3. User logged in with `CometChatUIKit.login()`

## Components

| Component                                   | Description                                                      |
| ------------------------------------------- | ---------------------------------------------------------------- |
| `CometChatMessageList`                      | Displays group messages and handles long-press to show options   |
| `CometChatMessageOption`                    | Defines the **Message Privately** option in the context menu     |
| `MessageDataSource`                         | Supplies the `messagePrivatelyOption` in the options array       |
| `CometChatMessageListViewModel`             | Manages UI state, including `hideMessagePrivatelyOption`         |
| `CometChatMessages`                         | Entry point for rendering or pushing the private chat interface  |
| `CometChat.getUser(UID:onSuccess:onError:)` | Retrieves the `User` object for the selected message sender      |
| `CometChatUIEvents.openChat(user:group:)`   | Opens the chat interface for a user or group                     |
| `UIViewController` (Navigation)             | Pushes or presents the private chat screen (`CometChatMessages`) |

## Integration Steps

### Step 1: Control Option Visibility via ViewModel

Dynamically show or hide **Message Privately** based on app context:

```swift lines theme={null}
import CometChatUIKitSwift

// Control visibility of the Message Privately option
public var hideMessagePrivatelyOption: Bool = false {
    didSet {
        // Sync with view model
        viewModel.hideMessagePrivatelyOption = hideMessagePrivatelyOption
    }
}
```

This ensures the option only appears when appropriate (e.g., based on user permissions).

**File reference:** [`CometChatMessageList.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Message%20List/CometChatMessageList.swift)

### Step 2: Handle Private Chat Navigation

Retrieve the sender and initiate a private 1-on-1 chat:

```swift lines theme={null}
import UIKit
import CometChatSDK
import CometChatUIKitSwift

func startPrivateChat(with selectedMessage: BaseMessage) {
    // Get the sender from the selected message
    if let user = selectedMessage.sender {
        // Open the private chat using CometChatUIEvents
        DispatchQueue.main.async {
            CometChatUIEvents.openChat(user: user, group: nil)
        }
    }
}

// Alternative: Manual navigation with user fetch
func startPrivateChatManual(with selectedMessage: BaseMessage) {
    guard let uid = selectedMessage.sender?.uid else { return }
    
    // Fetch the user object
    CometChat.getUser(UID: uid) { [weak self] user in
        guard let user = user else { return }
        
        DispatchQueue.main.async {
            // Navigate to the private chat screen
            let messagesVC = CometChatMessages()
            messagesVC.set(user: user)
            self?.navigationController?.pushViewController(messagesVC, animated: true)
        }
    } onError: { error in
        print("Error fetching user: \(error?.errorDescription ?? "")")
    }
}
```

This automates the transition from group context to private conversation.

**File reference:** [`CometChatMessageList.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Message%20List/CometChatMessageList.swift)

## Implementation Flow

| Step | Action                                                   |
| ---- | -------------------------------------------------------- |
| 1    | Long-press a group message in `CometChatMessageList`     |
| 2    | Options menu appears with **Message Privately**          |
| 3    | User taps **Message Privately**                          |
| 4    | App gets `User` from `message.sender`                    |
| 5    | Opens chat via `CometChatUIEvents.openChat(user:group:)` |
| 6    | Pushes `CometChatMessages` onto the navigation stack     |

## Customization Options

### Styling

Override `CometChatMessageOption` UI elements:

```swift lines theme={null}
// Customize the message option appearance
let privateOption = CometChatMessageOption(
    id: "message-privately",
    title: "Message Privately",
    icon: UIImage(systemName: "person.fill"),
    backgroundColor: .systemBlue
)
```

### Availability

Control visibility via the view model:

```swift lines theme={null}
// Hide the option for specific scenarios
viewModel.hideMessagePrivatelyOption = true
```

### Extend Options

Add additional actions in `MessageDataSource.getMessageOptions(for:)`:

```swift lines theme={null}
func getMessageOptions(for message: BaseMessage) -> [CometChatMessageOption] {
    var options = [CometChatMessageOption]()
    
    // Add message privately option
    if !hideMessagePrivatelyOption {
        options.append(messagePrivatelyOption)
    }
    
    // Add custom options
    options.append(customOption)
    
    return options
}
```

## Edge Cases

| Scenario               | Handling                                                   |
| ---------------------- | ---------------------------------------------------------- |
| Blocked users          | Hide option if the sender is in block list                 |
| Existing conversations | Reuse existing thread via `getConversationWith`            |
| Unavailable users      | Skip option or show disabled state if user data is missing |

## Error Handling

| Error Type       | Solution                                             |
| ---------------- | ---------------------------------------------------- |
| Block state      | Catch errors from `CometChat.getUser` and alert user |
| Network failures | Present retry or toast on navigation errors          |
| Invalid data     | Disable option if `sender.uid` is nil                |

## Additional Notes

* This feature is only available in **group chat** screens (`CometChatMessageList`)
* The option is hidden automatically in direct/private chat views

## Feature Matrix

| Feature                  | Component / Method                     | File(s)                                                                                                                                                                                                                                                                                                                              |
| ------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Show options menu        | `getMessageOptions(for:)`              | [`MessageDataSource.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Shared/Framework/MessagesDataSource.swift)                                                                                                                                                                       |
| Toggle Message Privately | `viewModel.hideMessagePrivatelyOption` | [`CometChatMessageList.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Message%20List/CometChatMessageList.swift), [`MessageListViewModel.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Message%20List/CometChatMessageList.swift) |

## Related Components

* [Message List](/docs/ui-kit/ios/message-list) - Display messages in conversations
* [Users](/docs/ui-kit/ios/users) - Display user list
* [Conversations](/docs/ui-kit/ios/conversations) - Display conversation list

<CardGroup>
  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5/SampleApp">
    Explore this feature in the CometChat SampleApp
  </Card>

  <Card title="UIKit Source" href="https://github.com/cometchat/cometchat-uikit-ios/blob/v5/CometChatUIKitSwift/Components/Message%20List/CometChatMessageList.swift">
    Browse the message list component
  </Card>
</CardGroup>

## Related Guides

<CardGroup>
  <Card title="Users" icon="user" href="/ui-kit/ios/users">
    Display and manage users
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/ios/conversations">
    View and manage conversations
  </Card>

  <Card title="Group Members" icon="user-group" href="/ui-kit/ios/group-members">
    View group membership
  </Card>
</CardGroup>


# Create Conversation
Source: https://www.cometchat.com/docs/ui-kit/ios/guide-new-chat

Create new one-to-one or group conversations in CometChat iOS UI Kit with user and group discovery, search, tabs, and navigation.

Enable users to start new 1:1 or group chats in your iOS app using CometChat's UIKit for iOS by integrating the `CreateConversationVC` screen.

## Overview

The `CreateConversation` component enables users to:

* Browse CometChat users and groups via native list components
* Search within users and groups
* Toggle between "Users" and "Groups" tabs using a segmented control
* Swipe between lists with a `UIPageViewController`
* Navigate to `MessagesVC` upon selecting a user or group

## Prerequisites

Before implementing this feature, ensure you have:

* Completed [Getting Started](/docs/ui-kit/ios/getting-started) setup
* CometChat UIKit v5+ installed via CocoaPods or Swift Package Manager
* User authenticated with `CometChatUIKit.login()` before presenting this screen
* A `UINavigationController` embedded in your flow
* `MessagesVC` implemented to handle chat screens

## Components

| Component              | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `UISegmentedControl`   | Switches between "Users" and "Groups" tabs         |
| `UIPageViewController` | Enables swipe navigation between list views        |
| `CometChatUsers`       | Displays the list of CometChat users               |
| `CometChatGroups`      | Displays the list of CometChat groups              |
| `MessagesVC`           | Chat interface, launched upon item selection       |
| `searchController`     | Provides search for both users and groups          |
| `CometChatTheme`       | Applies theming (colors, fonts) for UI consistency |
| `CometChatTypography`  | Defines text styles for segment labels             |

## Integration Steps

### Step 1: Present the Create Conversation Screen

Push `CreateConversations` to allow starting a chat:

```swift lines theme={null}
import UIKit
import CometChatSDK

class HomeViewController: UIViewController {
    
    func showCreateConversation() {
        // Initialize the create conversation view controller
        let createVC = CreateConversationVC()
        
        // Push onto navigation stack
        navigationController?.pushViewController(createVC, animated: true)
    }
}
```

This provides the entry point to the create-conversation flow.

**File reference:** [`HomeScreenViewController.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/HomeScreenViewController.swift)

### Step 2: Set Up the User Interface

Build the segmented control and page view controller:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

class CreateConversationVC: UIViewController {
    
    private var segmentedControl: UISegmentedControl!
    private var pageViewController: UIPageViewController!
    private var usersViewController: CometChatUsers!
    private var groupsViewController: CometChatGroups!
    
    override public func viewDidLoad() {
        super.viewDidLoad()
        
        // Set up segmented control, page view controller, and search
        buildUI()
        setupPageViewController()
        
        // Add target for segment changes
        segmentedControl.addTarget(
            self,
            action: #selector(segmentChanged(_:)),
            for: .valueChanged
        )
        
        // Set initial search controller
        navigationItem.searchController = usersViewController.searchController
    }
    
    private func buildUI() {
        // Configure segmented control and page view
    }
    
    private func setupPageViewController() {
        // Initialize page view controller with users and groups
    }
}
```

This initializes the UI elements and search integration.

**File reference:** [`CreateConversations.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/CreateConversations.swift)

### Step 3: Configure Segmented Control Navigation

Toggle between user and group lists when the segment changes:

```swift lines theme={null}
@objc public func segmentChanged(_ sender: UISegmentedControl) {
    let index = sender.selectedSegmentIndex
    
    // Determine navigation direction
    let direction: UIPageViewController.NavigationDirection = index == 0 ? .reverse : .forward
    
    // Update search controller based on selected tab
    navigationItem.searchController = (index == 0)
        ? usersViewController.searchController
        : groupsViewController.searchController
    
    // Navigate to the selected page
    pageViewController.setViewControllers(
        [pages[index]],
        direction: direction,
        animated: true
    )
}
```

This keeps the proper search bar and view in sync with the selected tab.

**File reference:** [`CreateConversations.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/CreateConversations.swift)

### Step 4: Handle Item Selection

Navigate to `MessagesVC` when a user or group is tapped:

```swift lines theme={null}
// Users list with tap handler
public lazy var usersViewController: CometChatUsers = {
    let vc = CometChatUsers()
    
    // Handle user selection
    vc.set(onItemClick: { [weak self] user, _ in
        let chatVC = MessagesVC()
        chatVC.user = user
        self?.navigationController?.pushViewController(chatVC, animated: true)
    })
    
    // Keep navigation bar visible during search
    vc.searchController.hidesNavigationBarDuringPresentation = false
    
    return vc
}()

// Groups list with tap handler
public lazy var groupsViewController: CometChatGroups = {
    let vc = CometChatGroups()
    
    // Handle group selection
    vc.set(onItemClick: { [weak self] group, _ in
        let chatVC = MessagesVC()
        chatVC.group = group
        self?.navigationController?.pushViewController(chatVC, animated: true)
    })
    
    // Keep navigation bar visible during search
    vc.searchController.hidesNavigationBarDuringPresentation = false
    
    return vc
}()
```

This routes the user to the appropriate chat screen.

**File reference:** [`CreateConversations.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/CreateConversations.swift)

### Step 5: Manage Page View Transitions

Implement data source and delegate for smooth swiping:

```swift lines theme={null}
// MARK: - UIPageViewControllerDataSource
extension CreateConversationVC: UIPageViewControllerDataSource {
    
    public func pageViewController(
        _ pvc: UIPageViewController,
        viewControllerBefore vc: UIViewController
    ) -> UIViewController? {
        guard let idx = pages.firstIndex(of: vc), idx > 0 else { return nil }
        return pages[idx - 1]
    }
    
    public func pageViewController(
        _ pvc: UIPageViewController,
        viewControllerAfter vc: UIViewController
    ) -> UIViewController? {
        guard let idx = pages.firstIndex(of: vc), idx < pages.count - 1 else { return nil }
        return pages[idx + 1]
    }
}

// MARK: - UIPageViewControllerDelegate
extension CreateConversationVC: UIPageViewControllerDelegate {
    
    public func pageViewController(
        _ pvc: UIPageViewController,
        didFinishAnimating finished: Bool,
        previousViewControllers: [UIViewController],
        transitionCompleted completed: Bool
    ) {
        // Sync segmented control with current page
        if completed,
           let current = pvc.viewControllers?.first,
           let idx = pages.firstIndex(of: current) {
            segmentedControl.selectedSegmentIndex = idx
        }
    }
}
```

This synchronizes the segmented control with page swipes.

**File reference:** [`CreateConversations.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/CreateConversations.swift)

## Customization Options

### Segment Styling

Use `CometChatTheme` to customize tint and font:

```swift lines theme={null}
segmentedControl.selectedSegmentTintColor = CometChatTheme.palette.primary
segmentedControl.setTitleTextAttributes([
    .font: CometChatTypography.body,
    .foregroundColor: UIColor.white
], for: .selected)
```

### Labels

Localize or rebrand "USERS" / "GROUPS" labels:

```swift lines theme={null}
segmentedControl.setTitle("Contacts", forSegmentAt: 0)
segmentedControl.setTitle("Teams", forSegmentAt: 1)
```

### Search

Adjust `searchController.placeholder` and styling:

```swift lines theme={null}
usersViewController.searchController.searchBar.placeholder = "Search contacts..."
groupsViewController.searchController.searchBar.placeholder = "Search teams..."
```

## Edge Cases

| Scenario         | Handling                                           |
| ---------------- | -------------------------------------------------- |
| Live search      | Built-in in `CometChatUsers` and `CometChatGroups` |
| Empty states     | Components display default "no results" views      |
| Segment disabled | Hide tabs if only one list is relevant             |

## Error Handling

| Error Type          | Solution                                         |
| ------------------- | ------------------------------------------------ |
| Load errors         | Use `setErrorView()` on list components          |
| Navigation failures | Present an alert if push fails                   |
| Blocked users       | Intercept in `onItemClick` to prevent navigation |

## Feature Matrix

| Feature              | Implementation                                |
| -------------------- | --------------------------------------------- |
| Show create screen   | `showCreateConversation()`                    |
| Tabbed lists         | `UISegmentedControl` + `UIPageViewController` |
| Display users        | `CometChatUsers()`                            |
| Display groups       | `CometChatGroups()`                           |
| Search functionality | `searchController`                            |
| Navigate to chat     | `MessagesVC(user:)` / `MessagesVC(group:)`    |

## Related Components

* [Users](/docs/ui-kit/ios/users) - Display user list
* [Groups](/docs/ui-kit/ios/groups) - Display group list
* [Conversations](/docs/ui-kit/ios/conversations) - Display conversation list

## Related Guides

<CardGroup>
  <Card title="Users" icon="user" href="/ui-kit/ios/users">
    Display and select users
  </Card>

  <Card title="Groups" icon="users" href="/ui-kit/ios/groups">
    Display and select groups
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/ios/conversations">
    View recent conversations
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5/SampleApp">
    Explore the complete create-conversation flow
  </Card>

  <Card title="UIKit Source" href="https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/CreateConversationVC.swift">
    Browse the source for CreateConversationVC
  </Card>
</CardGroup>


# Overview
Source: https://www.cometchat.com/docs/ui-kit/ios/guide-overview

Browse iOS UI Kit feature guides for AI agents, user blocking, call details, group management, private messages, new chats, and threads.

This page indexes focused, task-oriented feature guides for the iOS UI Kit. Each guide shows how to implement a specific capability end-to-end using UIKit components.

## Prerequisites

Before implementing any guide, ensure you have:

1. Completed [Getting Started](/docs/ui-kit/ios/getting-started) setup
2. CometChat UIKit v5+ installed
3. User logged in with `CometChatUIKit.login()`

## When to Use These Guides

Use these guides after completing [Getting Started](/docs/ui-kit/ios/getting-started) and wiring your base conversations/messages flows. Apply them to layer feature depth without rebuilding standard patterns.

## Guide Directory

| Guide                                                         | Description                                                                                                              |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| [AI Agent Integration](/docs/ui-kit/ios/guide-ai-agent)            | Add AI-powered chat assistants with chat history, contextual responses, and seamless handoffs.                           |
| [Block / Unblock User](/docs/ui-kit/ios/guide-block-unblock-user)  | Add profile-level moderation so users can block or unblock others; hides interaction affordances and protects chat flow. |
| [Call Log Details](/docs/ui-kit/ios/guide-call-log-details)        | Provide a detailed post-call screen with metadata, participants, history, and recordings for auditing and support.       |
| [Group Management](/docs/ui-kit/ios/guide-group-chat)              | Implement create/join, membership listing, role changes, bans, and structured group moderation actions.                  |
| [Group Ownership Transfer](/docs/ui-kit/ios/guide-group-ownership) | Allow admins to hand over group ownership securely to another member.                                                    |
| [Message Privately](/docs/ui-kit/ios/guide-message-privately)      | Launch a direct 1:1 conversation from a group chat; streamlines side discussions without manual user searches.           |
| [New Chat](/docs/ui-kit/ios/guide-new-chat)                        | Offer a unified entry to discover users and groups and jump into new conversations quickly.                              |
| [Threaded Messages](/docs/ui-kit/ios/guide-threaded-messages)      | Add threaded reply views so users can branch focused discussions off individual messages.                                |

## Related Resources

* [Getting Started](/docs/ui-kit/ios/getting-started) - Initial setup and configuration
* [Components Overview](/docs/ui-kit/ios/components-overview) - All available UI components
* [Core Features](/docs/ui-kit/ios/core-features) - Messaging, reactions, threads, and more

Need another guide? Request one via the [Developer Community](https://community.cometchat.com/) or Support.

***

## Related Guides

<CardGroup>
  <Card title="AI Agent Integration" icon="robot" href="/ui-kit/ios/guide-ai-agent">
    Build AI-powered chat experiences
  </Card>

  <Card title="Group Chat" icon="users" href="/ui-kit/ios/guide-group-chat">
    Create and manage group conversations
  </Card>

  <Card title="New Chat" icon="message" href="/ui-kit/ios/guide-new-chat">
    Start new conversations with users or groups
  </Card>

  <Card title="Threaded Messages" icon="comments" href="/ui-kit/ios/guide-threaded-messages">
    Implement threaded message replies
  </Card>
</CardGroup>


# Threaded Messages
Source: https://www.cometchat.com/docs/ui-kit/ios/guide-threaded-messages

Add threaded messages in CometChat iOS UI Kit with parent message context, reply views, message composers, and thread navigation.

Enhance your iOS chat app with threaded messaging by integrating CometChat's UIKit for iOS, allowing users to reply to specific messages within a focused thread view.

## Overview

Threaded messages allow users to reply to specific messages within a conversation, creating a sub-conversation for improved clarity and context. With CometChat's UIKit for iOS, you can:

* Display a dedicated thread view
* View and send replies to a selected message
* Maintain context between the main conversation and the thread

## Prerequisites

Before implementing this feature, ensure you have:

1. Completed [Getting Started](/docs/ui-kit/ios/getting-started) setup
2. CometChat UIKit v5+ installed
3. User logged in with `CometChatUIKit.login()`

## Components

| Component                        | Description                                                   |
| -------------------------------- | ------------------------------------------------------------- |
| `CometChatMessageList`           | Displays messages and provides `onThreadRepliesClick` handler |
| `CometChatThreadedMessageHeader` | Shows the parent message context at the top of the thread     |
| `CometChatMessageComposer`       | Composes messages with an optional `parentMessageId`          |
| `ThreadedMessagesVC`             | View controller that hosts the threaded conversation          |

## Integration Steps

### Step 1: Show the "Reply in Thread" Option

Navigate to the thread when a message's thread icon is tapped:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class MessagesViewController: UIViewController {
    
    var messageListView: CometChatMessageList!
    
    func setupThreadReplies() {
        // Handle thread replies click
        messageListView.set(onThreadRepliesClick: { [weak self] message, _ in
            guard let self = self else { return }
            
            // Create and configure thread view controller
            let threadVC = ThreadedMessagesVC()
            threadVC.parentMessage = message
            
            // Navigate to thread screen
            self.navigationController?.pushViewController(threadVC, animated: true)
        })
    }
}
```

This captures user intent and opens a focused thread screen.

**File reference:** [`ThreadedMessagesVC.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/ThreadedMessagesVC.swift)

### Step 2: Navigate to the Thread Screen

Show a dedicated UI for thread replies. In `ThreadedMessagesVC.swift`:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ThreadedMessagesVC: UIViewController {
    
    var parentMessage: BaseMessage?
    var user: User?
    var group: Group?
    
    private var parentMessageContainerView: CometChatThreadedMessageHeader!
    private var messageListView: CometChatMessageList!
    private var composerView: CometChatMessageComposer!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupUI()
    }
    
    private func setupUI() {
        // Add UI components to view hierarchy
        view.addSubview(parentMessageView)
        view.addSubview(messageListView)
        view.addSubview(composerView)
    }
}
```

Header configuration:

```swift lines theme={null}
// Create the threaded message header
let parentMessageContainerView = CometChatThreadedMessageHeader()
```

Message list configuration:

```swift lines theme={null}
// Configure message list with user and parent message
messageListView.set(user: user, parentMessage: parentMessage)
```

This provides a focused UI for thread interactions.

### Step 3: Send a Threaded Message

Ensure new replies are attached to the correct parent message:

```swift lines theme={null}
// Set the parent message ID for threaded replies
composerView.set(parentMessageId: parentMessage?.id ?? 0)
```

Set the conversation context:

```swift lines theme={null}
// Configure composer for user conversation
composerView.set(user: user)

// Or configure for group conversation
composerView.set(group: group)
```

### Step 4: Fetch and Display Thread Replies

Only messages that are part of the thread are displayed. This is handled internally by:

```swift lines theme={null}
// Configure message list to fetch thread replies
messageListView.set(user: user, parentMessage: parentMessage)
```

This ensures `CometChatMessageList` fetches replies using the `parentMessageId`.

## Customization Options

### Header Styling

Customize `CometChatThreadedMessageHeader` appearance:

```swift lines theme={null}
// Customize fonts, colors, and layout
let headerStyle = ThreadedMessageHeaderStyle()
headerStyle.titleFont = UIFont.systemFont(ofSize: 16, weight: .semibold)
headerStyle.titleColor = .label
parentMessageContainerView.set(style: headerStyle)
```

### Composer

Modify placeholder text, input styles, and icons:

```swift lines theme={null}
// Customize composer appearance
composerView.set(placeholderText: "Reply in thread...")
```

### Navigation

Add a custom back button for navigation:

```swift lines theme={null}
// Add custom back button
navigationItem.leftBarButtonItem = UIBarButtonItem(
    image: UIImage(systemName: "chevron.left"),
    style: .plain,
    target: self,
    action: #selector(goBack)
)
```

## Edge Cases

| Scenario               | Handling                                         |
| ---------------------- | ------------------------------------------------ |
| Parent message deleted | Display a fallback UI or disable the composer    |
| No replies             | Show an empty state (e.g., "No replies yet")     |
| Offline mode           | Disable the composer and queue thread operations |

## Error Handling

| Error Type     | Solution                                                              |
| -------------- | --------------------------------------------------------------------- |
| Fetch failures | Show an error UI or retry mechanism when loading thread messages      |
| Send failures  | Handle send errors via delegate callbacks or show an alert with retry |
| Loading states | Display a `UIActivityIndicatorView` during fetch/send operations      |
| Blocked users  | Remove the composer and display a blocked status label                |

## Feature Matrix

| Feature                   | Implementation                                   |
| ------------------------- | ------------------------------------------------ |
| Show thread option        | `CometChatMessageList.onThreadRepliesClick`      |
| Thread view screen        | `ThreadedMessagesVC.swift`                       |
| Display threaded messages | `CometChatMessageList.set(parentMessage:)`       |
| Send threaded message     | `CometChatMessageComposer.set(parentMessageId:)` |
| Thread header             | `CometChatThreadedMessageHeader`                 |
| Handle blocked user       | Remove composer and show a blocked user label    |

## Related Components

* [Message List](/docs/ui-kit/ios/message-list) - Display messages in conversations
* [Message Composer](/docs/ui-kit/ios/message-composer) - Compose and send messages
* [Threaded Messages Header](/docs/ui-kit/ios/threaded-messages-header) - Thread header component

<CardGroup>
  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5/SampleApp">
    Explore a complete sample application demonstrating threaded messaging
  </Card>

  <Card title="UIKit Source" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5">
    Browse the CometChat UIKit for iOS source code
  </Card>
</CardGroup>

## Related Guides

<CardGroup>
  <Card title="Threaded Messages Header" icon="heading" href="/ui-kit/ios/threaded-messages-header">
    Customize the thread header component
  </Card>

  <Card title="Message List" icon="list" href="/ui-kit/ios/message-list">
    Display and customize chat messages
  </Card>

  <Card title="Core Features" icon="star" href="/ui-kit/ios/core-features">
    Overview of messaging features
  </Card>
</CardGroup>


# Incoming Call
Source: https://www.cometchat.com/docs/ui-kit/ios/incoming-call

Handle incoming CometChat iOS UI Kit voice and video calls with caller details, accept, reject, custom sounds, and view slots.

The `CometChatIncomingCall` component serves as a visual representation when the user receives an incoming call, such as a voice call or video call, providing options to answer or decline the call.

<Frame>
  <img alt="CometChatIncomingCall showing incoming call interface with caller avatar, name, and accept/reject buttons" />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatIncomingCall",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "description": "Displays incoming call interface with accept and reject options",
    "inherits": "UIViewController",
    "primaryOutput": {
      "callback": "onAcceptClick",
      "type": "(Call, UIViewController) -> Void"
    },
    "props": {
      "data": {
        "call": { "type": "Call", "required": true }
      },
      "callbacks": {
        "onAcceptClick": "(Call, UIViewController) -> Void",
        "onCancelClick": "(Call, UIViewController) -> Void",
        "onError": "(CometChatException) -> Void"
      },
      "sound": {
        "disableSoundForCalls": { "type": "Bool", "default": false },
        "customSoundForCalls": { "type": "URL?", "default": "nil" }
      },
      "viewSlots": {
        "listItemView": "(Call) -> UIView",
        "leadingView": "(Call) -> UIView",
        "titleView": "(Call) -> UIView"
      }
    },
    "events": [
      { "name": "onIncomingCallAccepted", "payload": "Call", "description": "Fires when incoming call is accepted" },
      { "name": "onIncomingCallRejected", "payload": "Call", "description": "Fires when incoming call is rejected" },
      { "name": "onCallEnded", "payload": "Call", "description": "Fires when call ends" }
    ],
    "sdkListeners": [],
    "compositionExample": {
      "description": "IncomingCall is presented when a call is received",
      "components": ["CometChatIncomingCall", "CometChatOngoingCall"],
      "flow": "Call received → IncomingCall shown → User accepts → OngoingCall starts"
    }
  }
  ```
</Accordion>

| Field     | Value                   |
| --------- | ----------------------- |
| Component | `CometChatIncomingCall` |
| Package   | `CometChatUIKitSwift`   |
| Inherits  | `UIViewController`      |

***

## Usage

### Integration

`CometChatIncomingCall` is a custom view controller that offers versatility in its integration. It can be seamlessly launched via button clicks or any user-triggered action, enhancing the overall user experience and facilitating smoother interactions within the application.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Create and configure incoming call view controller
    let cometChatIncomingCall = CometChatIncomingCall().set(call: call)

    // Present full screen
    cometChatIncomingCall.modalPresentationStyle = .fullScreen
    self.present(cometChatIncomingCall, animated: true)
    ```
  </Tab>
</Tabs>

<Note>
  If you are already using a navigation controller, you can use the `pushViewController` function instead of presenting the view controller.
</Note>

### Actions

[Actions](/docs/ui-kit/ios/components-overview#actions) dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the component to fit your specific needs.

#### 1. SetOnAcceptClick

The `setOnAcceptClick` action is typically triggered when the user clicks on the accept button, initiating a predefined action. However, by implementing the following code snippet, you can easily customize or override this default behavior to suit your specific requirements.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let cometChatIncomingCall = CometChatIncomingCall()
        .set(onAcceptClick: { call, controller in
            // Perform your custom action when call is accepted
        })
    ```
  </Tab>
</Tabs>

#### 2. SetOnCancelClick

The `setOnCancelClick` action is typically triggered when the user clicks on the reject button, initiating a predefined action. However, by implementing the following code snippet, you can easily customize or override this default behavior to suit your specific requirements.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let cometChatIncomingCall = CometChatIncomingCall()
        .set(onCancelClick: { call, controller in
            // Perform your custom action when call is rejected
        })
    ```
  </Tab>
</Tabs>

#### 3. OnError

You can customize this behavior by using the provided code snippet to override the `On Error` and improve error handling.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let incomingCallConfiguration = IncomingCallConfiguration()
        .set(onError: { error in
            // Perform your custom error handling action
        })
    ```
  </Tab>
</Tabs>

***

### Filters

Filters allow you to customize the data displayed in a list within a Component. You can filter the list based on your specific criteria, allowing for a more customized experience. Filters can be applied using RequestBuilders of Chat SDK.

The IncomingCall component does not have any exposed filters.

***

### Events

[Events](/docs/ui-kit/ios/components-overview#events) are emitted by a Component. By using events you can extend existing functionality. Being global events, they can be applied in multiple locations and are capable of being added or removed.

Events emitted by the Incoming Call component are as follows:

| Event                    | Description                                                |
| ------------------------ | ---------------------------------------------------------- |
| `onIncomingCallAccepted` | Triggers when the logged-in user accepts the incoming call |
| `onIncomingCallRejected` | Triggers when the logged-in user rejects the incoming call |
| `onCallEnded`            | Triggers when the initiated call successfully ends         |

<Tabs>
  <Tab title="Add Listener">
    ```swift lines theme={null}
    // View controller from your project where you want to listen to events
    public class ViewController: UIViewController {

        public override func viewDidLoad() {
            super.viewDidLoad()

            // Subscribe to call events
            CometChatCallEvents.addListener("UNIQUE_ID", self as CometChatCallEventListener)
        }
    }

    // Listener events from call module
    extension ViewController: CometChatCallEventListener {

        func onIncomingCallAccepted(call: Call) {
            // Handle accepted call
        }
        
        func onIncomingCallRejected(call: Call) {
            // Handle rejected call
        }

        func onCallEnded(call: Call) {
            // Handle ended call
        }
    }
    ```

    ```swift lines theme={null}
    // Emitting Call Events

    // Emit when logged in user accepts the incoming call
    CometChatCallEvents.emitOnIncomingCallAccepted(call: Call)

    // Emit when logged in user rejects the incoming call
    CometChatCallEvents.emitOnIncomingCallRejected(call: Call)

    // Emit when logged in user ends a call
    CometChatCallEvents.emitOnCallEnded(call: Call)
    ```
  </Tab>
</Tabs>

***

<Tabs>
  <Tab title="Remove Listener">
    ```swift lines theme={null}
    public override func viewWillDisappear(_ animated: Bool) {
        // Unsubscribe from call events
        CometChatCallEvents.removeListener("LISTENER_ID_USED_FOR_ADDING_THIS_LISTENER")
    }
    ```
  </Tab>
</Tabs>

***

## Customization

To fit your app's design requirements, you can customize the appearance of the conversation component. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.

### Style

Using Style you can customize the look and feel of the component in your app. These parameters typically control elements such as the color, size, shape, and fonts used within the component.

#### 1. IncomingCall Style

You can customize the appearance of the `IncomingCall` Component by applying the `IncomingCallStyle` to it using the following code snippet.

**Global level styling**

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Create custom avatar style
    let customAvatarStyle = AvatarStyle()
    customAvatarStyle.backgroundColor = UIColor(hex: "#FBAA75")
    customAvatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)

    // Apply global incoming call styles
    CometChatIncomingCall.style.nameLabelFont = UIFont(name: "Times-New-Roman", size: 20)
    CometChatIncomingCall.style.callLabelFont = UIFont(name: "Times-New-Roman", size: 14)
    CometChatIncomingCall.style.acceptButtonCornerRadius = .init(cornerRadius: 8)
    CometChatIncomingCall.style.rejectButtonCornerRadius = .init(cornerRadius: 8)
    CometChatIncomingCall.avatarStyle = customAvatarStyle
    ```
  </Tab>
</Tabs>

**Instance level styling**

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Create custom avatar style
    var customAvatarStyle = AvatarStyle()
    customAvatarStyle.backgroundColor = UIColor(hex: "#FBAA75")
    customAvatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 20)

    // Create custom incoming call style
    var incomingCallStyle = IncomingCallStyle()
    incomingCallStyle.nameLabelFont = UIFont(name: "Times-New-Roman", size: 20)
    incomingCallStyle.callLabelFont = UIFont(name: "Times-New-Roman", size: 14)
    incomingCallStyle.acceptButtonCornerRadius = .init(cornerRadius: 8)
    incomingCallStyle.rejectButtonCornerRadius = .init(cornerRadius: 8)

    // Apply styles to instance
    let incomingCall = CometChatIncomingCall()
    incomingCall.style = incomingCallStyle
    incomingCall.avatarStyle = customAvatarStyle
    ```
  </Tab>
</Tabs>

<Frame>
  <img alt="CometChatIncomingCall with custom styling showing custom fonts and rounded button corners" />
</Frame>

List of properties exposed by IncomingCallStyle:

| Property                      | Description                            | Code                                              |
| ----------------------------- | -------------------------------------- | ------------------------------------------------- |
| `overlayBackgroundColor`      | Background color for the overlay       | `overlayBackgroundColor: UIColor`                 |
| `acceptButtonBackgroundColor` | Background color for the accept button | `acceptButtonBackgroundColor: UIColor`            |
| `rejectButtonBackgroundColor` | Background color for the reject button | `rejectButtonBackgroundColor: UIColor`            |
| `acceptButtonTintColor`       | Tint color for the accept button       | `acceptButtonTintColor: UIColor`                  |
| `rejectButtonTintColor`       | Tint color for the reject button       | `rejectButtonTintColor: UIColor`                  |
| `acceptButtonImage`           | Icon image for the accept button       | `acceptButtonImage: UIImage`                      |
| `rejectButtonImage`           | Icon image for the reject button       | `rejectButtonImage: UIImage`                      |
| `acceptButtonCornerRadius`    | Sets corner radius for accept button   | `acceptButtonCornerRadius: CometChatCornerStyle?` |
| `rejectButtonCornerRadius`    | Sets corner radius for reject button   | `rejectButtonCornerRadius: CometChatCornerStyle?` |
| `acceptButtonBorderWidth`     | Sets border width for accept button    | `acceptButtonBorderWidth: CGFloat?`               |
| `rejectButtonBorderWidth`     | Sets border width for reject button    | `rejectButtonBorderWidth: CGFloat?`               |
| `acceptButtonBorderColor`     | Sets border color for accept button    | `acceptButtonBorderColor: UIColor?`               |
| `rejectButtonBorderColor`     | Sets border color for reject button    | `rejectButtonBorderColor: UIColor?`               |
| `backgroundColor`             | Background color for the call view     | `backgroundColor: UIColor`                        |
| `cornerRadius`                | Corner radius for the view             | `cornerRadius: nil`                               |
| `borderColor`                 | Border color for the view              | `borderColor: UIColor`                            |
| `borderWidth`                 | Border width for the view              | `borderWidth: CGFloat`                            |
| `callLabelColor`              | Text color for the call label          | `callLabelColor: UIColor`                         |
| `callLabelFont`               | Font for the call label                | `callLabelFont: UIFont`                           |
| `nameLabelColor`              | Text color for the name label          | `nameLabelColor: UIColor`                         |
| `nameLabelFont`               | Font for the name label                | `nameLabelFont: UIFont`                           |

***

### Functionality

These are a set of small functional customizations that allow you to fine-tune the overall experience of the component.

| Property                 | Description                            | Code                            |
| ------------------------ | -------------------------------------- | ------------------------------- |
| `disableSoundForCalls`   | Disables sound for incoming calls      | `disableSoundForCalls = true`   |
| `setCustomSoundForCalls` | Sets a custom sound for incoming calls | `set(customSoundForCalls: URL)` |

### Advanced

For advanced-level customization, you can set custom views to the component. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your views, layouts, and UI elements and then incorporate those into the component.

#### SetListItemView

With this function, you can assign a custom view to the incoming call item view.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatIncomingCall.set(listItemView: { call in
        let customView = CustomListItemView()
        return customView
    })
    ```
  </Tab>
</Tabs>

Demonstration:

<Frame>
  <img alt="CometChatIncomingCall with custom list item view showing compact call notification with avatar and action buttons" />
</Frame>

You can create a CustomListItemView as a custom `UIView`:

```swift lines theme={null}
import UIKit

class CustomListItemView: UIView {
    
    private let avatarView: UILabel = {
        let label = UILabel()
        label.backgroundColor = UIColor.systemPurple
        label.textColor = .white
        label.font = UIFont.boldSystemFont(ofSize: 18)
        label.textAlignment = .center
        label.layer.cornerRadius = 20
        label.clipsToBounds = true
        return label
    }()
    
    private let callTypeLabel: UILabel = {
        let label = UILabel()
        label.text = "Voice Call"
        label.textColor = .darkGray
        label.font = UIFont.systemFont(ofSize: 14)
        return label
    }()
    
    private let userNameLabel: UILabel = {
        let label = UILabel()
        label.text = "George Allen"
        label.font = UIFont.boldSystemFont(ofSize: 16)
        return label
    }()
    
    private let endCallButton: UIButton = {
        let button = UIButton()
        button.setImage(UIImage(systemName: "phone.down.fill"), for: .normal)
        button.tintColor = .red
        button.backgroundColor = .white
        button.layer.cornerRadius = 18
        return button
    }()
    
    private let acceptCallButton: UIButton = {
        let button = UIButton()
        button.setImage(UIImage(systemName: "phone.fill"), for: .normal)
        button.tintColor = .white
        button.backgroundColor = UIColor.systemPurple
        button.layer.cornerRadius = 18
        return button
    }()
    
    override init(frame: CGRect) {
        super.init(frame: frame)
        setupView()
    }
    
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
    
    private func setupView() {
        backgroundColor = UIColor.systemPurple.withAlphaComponent(0.1)
        layer.cornerRadius = 20
        
        addSubview(avatarView)
        addSubview(callTypeLabel)
        addSubview(userNameLabel)
        addSubview(endCallButton)
        addSubview(acceptCallButton)
        
        avatarView.translatesAutoresizingMaskIntoConstraints = false
        callTypeLabel.translatesAutoresizingMaskIntoConstraints = false
        userNameLabel.translatesAutoresizingMaskIntoConstraints = false
        endCallButton.translatesAutoresizingMaskIntoConstraints = false
        acceptCallButton.translatesAutoresizingMaskIntoConstraints = false
        
        NSLayoutConstraint.activate([
            avatarView.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 12),
            avatarView.centerYAnchor.constraint(equalTo: centerYAnchor),
            avatarView.widthAnchor.constraint(equalToConstant: 40),
            avatarView.heightAnchor.constraint(equalToConstant: 40),
            
            callTypeLabel.topAnchor.constraint(equalTo: topAnchor, constant: 8),
            callTypeLabel.leadingAnchor.constraint(equalTo: avatarView.trailingAnchor, constant: 8),
            
            userNameLabel.topAnchor.constraint(equalTo: callTypeLabel.bottomAnchor, constant: 2),
            userNameLabel.leadingAnchor.constraint(equalTo: avatarView.trailingAnchor, constant: 8),
            
            endCallButton.trailingAnchor.constraint(equalTo: acceptCallButton.leadingAnchor, constant: -8),
            endCallButton.centerYAnchor.constraint(equalTo: centerYAnchor),
            endCallButton.widthAnchor.constraint(equalToConstant: 36),
            endCallButton.heightAnchor.constraint(equalToConstant: 36),
            
            acceptCallButton.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -12),
            acceptCallButton.centerYAnchor.constraint(equalTo: centerYAnchor),
            acceptCallButton.widthAnchor.constraint(equalToConstant: 36),
            acceptCallButton.heightAnchor.constraint(equalToConstant: 36)
        ])
    }
}
```

***

#### SetLeadingView

You can modify the leading view of an Incoming call component using the property below.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatIncomingCall.set(leadingView: { call in
        let view = CustomLeadingView()
        return view
    })
    ```
  </Tab>
</Tabs>

Demonstration:

<Frame>
  <img alt="CometChatIncomingCall with custom leading view showing PRO USER badge with star icon" />
</Frame>

You can create a CustomLeadingView as a custom `UIView`:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit

    class CustomLeadingView: UIView {
        
        private let starIconView: UIImageView = {
            let imageView = UIImageView(image: UIImage(systemName: "star.fill"))
            imageView.tintColor = UIColor.systemPurple
            imageView.backgroundColor = .white
            imageView.layer.cornerRadius = 20
            imageView.contentMode = .center
            return imageView
        }()
        
        private let label: UILabel = {
            let label = UILabel()
            label.text = "PRO USER"
            label.font = UIFont.boldSystemFont(ofSize: 14)
            label.textColor = .white
            label.textAlignment = .center
            return label
        }()
        
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupView()
        }
        
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
        
        private func setupView() {
            backgroundColor = UIColor.systemPurple
            layer.cornerRadius = 10
            
            addSubview(starIconView)
            addSubview(label)
            
            starIconView.translatesAutoresizingMaskIntoConstraints = false
            label.translatesAutoresizingMaskIntoConstraints = false
            
            NSLayoutConstraint.activate([
                starIconView.centerXAnchor.constraint(equalTo: centerXAnchor),
                starIconView.topAnchor.constraint(equalTo: topAnchor, constant: 8),
                starIconView.widthAnchor.constraint(equalToConstant: 40),
                starIconView.heightAnchor.constraint(equalToConstant: 40),
                
                label.topAnchor.constraint(equalTo: starIconView.bottomAnchor, constant: 8),
                label.centerXAnchor.constraint(equalTo: centerXAnchor),
                label.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -8)
            ])
        }
    }
    ```
  </Tab>
</Tabs>

***

#### SetTitleView

You can customize the title view of an incoming call component using the property below.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatIncomingCall.set(titleView: { call in
        let view = CustomTitleView()
        return view
    })
    ```
  </Tab>
</Tabs>

Demonstration:

<Frame>
  <img alt="CometChatIncomingCall with custom title view showing Voice Call label with Important tag" />
</Frame>

You can create a `CustomTitleView` as a custom `UIView` which we will inflate in `setTitleView()`:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit

    class CustomTitleView: UIView {
        
        private let titleLabel: UILabel = {
            let label = UILabel()
            label.text = "Voice Call"
            label.textColor = .darkGray
            label.font = UIFont.systemFont(ofSize: 16)
            return label
        }()
        
        private let tagView: UIView = {
            let view = UIView()
            view.backgroundColor = .systemGreen
            view.layer.cornerRadius = 12
            return view
        }()
        
        private let starIconView: UIImageView = {
            let imageView = UIImageView(image: UIImage(systemName: "star.fill"))
            imageView.tintColor = .white
            return imageView
        }()
        
        private let tagLabel: UILabel = {
            let label = UILabel()
            label.text = "Important"
            label.textColor = .white
            label.font = UIFont.boldSystemFont(ofSize: 14)
            return label
        }()
        
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupView()
        }
        
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
        
        private func setupView() {
            addSubview(titleLabel)
            addSubview(tagView)
            tagView.addSubview(starIconView)
            tagView.addSubview(tagLabel)
            
            titleLabel.translatesAutoresizingMaskIntoConstraints = false
            tagView.translatesAutoresizingMaskIntoConstraints = false
            starIconView.translatesAutoresizingMaskIntoConstraints = false
            tagLabel.translatesAutoresizingMaskIntoConstraints = false
            
            NSLayoutConstraint.activate([
                titleLabel.leadingAnchor.constraint(equalTo: leadingAnchor),
                titleLabel.centerYAnchor.constraint(equalTo: centerYAnchor),
                
                tagView.leadingAnchor.constraint(equalTo: titleLabel.trailingAnchor, constant: 8),
                tagView.centerYAnchor.constraint(equalTo: centerYAnchor),
                tagView.heightAnchor.constraint(equalToConstant: 24),
                tagView.widthAnchor.constraint(equalToConstant: 100),
                
                starIconView.leadingAnchor.constraint(equalTo: tagView.leadingAnchor, constant: 8),
                starIconView.centerYAnchor.constraint(equalTo: tagView.centerYAnchor),
                starIconView.widthAnchor.constraint(equalToConstant: 16),
                starIconView.heightAnchor.constraint(equalToConstant: 16),
                
                tagLabel.leadingAnchor.constraint(equalTo: starIconView.trailingAnchor, constant: 4),
                tagLabel.centerYAnchor.constraint(equalTo: tagView.centerYAnchor)
            ])
        }
    }
    ```
  </Tab>
</Tabs>

***

## Props

All props are optional unless noted.

***

### call

The incoming call object to display.

|         |               |
| ------- | ------------- |
| Type    | `Call`        |
| Default | Auto-detected |

***

### disableSoundForCalls

Disables the incoming call ringtone.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

***

### customSoundForCalls

Custom sound file URL for incoming calls.

|         |        |
| ------- | ------ |
| Type    | `URL?` |
| Default | `nil`  |

***

### avatarStyle

Customizes the appearance of the caller's avatar.

|         |                 |
| ------- | --------------- |
| Type    | `AvatarStyle`   |
| Default | `AvatarStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let customAvatarStyle = AvatarStyle()
customAvatarStyle.backgroundColor = UIColor.systemPurple
customAvatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 20)

let incomingCall = CometChatIncomingCall()
incomingCall.avatarStyle = customAvatarStyle
```

***

## Events

Events emitted by the Incoming Call component:

| Event                    | Description                                                |
| ------------------------ | ---------------------------------------------------------- |
| `onIncomingCallAccepted` | Triggers when the logged-in user accepts the incoming call |
| `onIncomingCallRejected` | Triggers when the logged-in user rejects the incoming call |
| `onCallEnded`            | Triggers when the call ends                                |

***

## View Slots

| Slot           | Signature          | Replaces                  |
| -------------- | ------------------ | ------------------------- |
| `listItemView` | `(Call) -> UIView` | Entire list item          |
| `leadingView`  | `(Call) -> UIView` | Avatar / left section     |
| `titleView`    | `(Call) -> UIView` | Name / title text         |
| `subtitleView` | `(Call) -> UIView` | Subtitle text (call type) |
| `trailingView` | `(Call) -> UIView` | Right section             |

### subtitleView

You can customize the subtitle view of an incoming call component using the property below.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatIncomingCall.set(subtitleView: { call in
        let view = CustomSubtitleView()
        return view
    })
    ```
  </Tab>
</Tabs>

### trailingView

You can customize the trailing view of an incoming call component using the property below.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatIncomingCall.set(trailingView: { call in
        let view = CustomTrailingView()
        return view
    })
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Present Incoming Call Screen

Present the incoming call screen when a call is received:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // In your call listener
    func onIncomingCallReceived(incomingCall: Call) {
        DispatchQueue.main.async {
            let incomingCallVC = CometChatIncomingCall()
            incomingCallVC.set(call: incomingCall)
            incomingCallVC.modalPresentationStyle = .fullScreen
            
            // Get the top view controller to present from
            if let topVC = UIApplication.shared.keyWindow?.rootViewController {
                topVC.present(incomingCallVC, animated: true)
            }
        }
    }
    ```
  </Tab>
</Tabs>

### Handle Call Accept and Navigate to Ongoing Call

Transition from incoming call to ongoing call when accepted:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let incomingCall = CometChatIncomingCall()
    incomingCall.set(call: call)
    incomingCall.set(onAcceptClick: { [weak self] acceptedCall, controller in
        // Dismiss incoming call screen
        controller.dismiss(animated: false) {
            // Present ongoing call screen
            let ongoingCall = CometChatOngoingCall()
            ongoingCall.set(sessionId: acceptedCall.sessionId ?? "")
            ongoingCall.modalPresentationStyle = .fullScreen
            self?.present(ongoingCall, animated: true)
        }
    })
    ```
  </Tab>
</Tabs>

### Custom Ringtone for Incoming Calls

Set a custom sound for incoming calls:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let incomingCall = CometChatIncomingCall()
    incomingCall.set(call: call)

    // Use custom ringtone
    if let soundURL = Bundle.main.url(forResource: "custom_ringtone", withExtension: "mp3") {
        incomingCall.set(customSoundForCalls: soundURL)
    }
    ```
  </Tab>
</Tabs>

***

## Related Components

<CardGroup>
  <Card title="Outgoing Call" href="/ui-kit/ios/outgoing-call">
    Display outgoing call interface
  </Card>

  <Card title="Ongoing Call" href="/ui-kit/ios/ongoing-call">
    Display active call interface
  </Card>

  <Card title="Call Logs" href="/ui-kit/ios/call-logs">
    Display call history
  </Card>
</CardGroup>


# Changelog
Source: https://www.cometchat.com/docs/ui-kit/ios/link/changelog

Navigate to Changelog documentation.



# Figma Design
Source: https://www.cometchat.com/docs/ui-kit/ios/link/figma

Navigate to Figma Design documentation.



# iOS Sample App
Source: https://www.cometchat.com/docs/ui-kit/ios/link/sample

Navigate to iOS Sample App documentation.



# Mentions Formatter
Source: https://www.cometchat.com/docs/ui-kit/ios/mentions-formatter-guide

Format @mentions in CometChat iOS UI Kit messages with custom styles, mention suggestions, group member mentions, and tap handling.

## Overview

The `CometChatMentionsFormatter` class is part of the CometChat UI Kit, a ready-to-use chat UI component library for integrating CometChat into your iOS applications. This class provides functionality to format mentions within text messages displayed in the chat interface. Mentions allow users to reference other users within a conversation, providing a convenient way to direct messages or involve specific participants.

***

## Features

* **Mention Formatting**: Automatically formats mentions within text messages based on provided styles and settings
* **Customizable Styles**: Allows customization of text styles for mentions, including colors, fonts, and background colors
* **User and Group Member Mentions**: Supports mentions for both individual users and group members, providing flexibility in communication scenarios
* **Mention List Generation**: Generates a list of suggested mentions based on user input, facilitating easy selection of recipients during message composition
* **Mention Click Handling**: Provides a listener interface for handling click events on mentions, enabling custom actions to be performed when a mention is tapped by the user

***

## Usage

To integrate the `CometChatMentionsFormatter` class into your application:

1. **Initialization**: Create an instance of the `CometChatMentionsFormatter` class and configure it with desired settings, such as mention text styles and limit settings.

2. **Set Mention Listeners**: Set listeners for handling mention click events (`.setOnMentionClicked`).

3. **Format Messages**: Use the `.set(leftBubbleTextStyle)`, `.set(rightBubbleTextStyle)`, `.set(composerTextStyle)`, and `.set(conversationListTextStyle)` methods to format text messages with mentions appropriately for display in the chat interface.

4. **Customization**: Customize the appearance and behavior of mentions by adjusting the text styles, colors, and other formatting properties as needed.

`CometChatMentionsFormatter` can be directly initialized, tweaked using its properties, and passed into different configurations.

Below is an example demonstrating how to use the `CometChatMentionsFormatter` class in components such as [CometChatConversations](/docs/ui-kit/ios/conversations), [CometChatMessageList](/docs/ui-kit/ios/message-list), and [CometChatMessageComposer](/docs/ui-kit/ios/message-composer).

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Create a custom mention formatter instance
    let customMentionFormatter = CometChatMentionsFormatter()

    // Apply the formatter to a message list
    let messageListView = CometChatMessageList()
    messageListView.set(textFormatters: [customMentionFormatter])
    ```
  </Tab>
</Tabs>

***

## Actions

[Actions](/docs/ui-kit/ios/components-overview#actions) dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the component to fit your specific needs.

### setOnMentionClick

Setting a listener for mention-click events in Message Bubbles enhances interactivity within the chat. This listener is activated when a mention is clicked, returning the corresponding user object. This feature transforms mentions into interactive links, enabling more in-depth and contextual engagement with the user associated with the clicked mention.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Set up mention click handler
    let customMentionFormatter = CometChatMentionsFormatter()
    customMentionFormatter.set { message, tappedText, controller in
        // Display the name of the first mentioned user
        controller?.view.showToastMessage(message: "\(message.mentionedUsers.first?.name)")
    }
    ```
  </Tab>
</Tabs>

The following code snippet represents a UIView extension used to display `showToastMessage`:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    extension UIView {
        func showToastMessage(message: String) {
            // Create toast label with centered positioning
            let toastLabel = UILabel(frame: CGRect(
                x: self.frame.size.width/2 - 100,
                y: self.frame.size.height - 120,
                width: 200,
                height: 35
            ))
            
            // Configure toast appearance
            toastLabel.backgroundColor = UIColor.black
            toastLabel.textColor = UIColor.white
            toastLabel.textAlignment = .center
            toastLabel.text = message
            toastLabel.alpha = 2.0
            toastLabel.layer.cornerRadius = 13
            toastLabel.clipsToBounds = true
            
            self.addSubview(toastLabel)
            
            // Animate fade out and remove
            UIView.animate(withDuration: 4.0, delay: 0.4, options: .curveEaseOut, animations: {
                toastLabel.alpha = 0.0
            }, completion: { isCompleted in
                toastLabel.removeFromSuperview()
            })
        }
    }
    ```
  </Tab>
</Tabs>

***

## Customization

| Method                              | Description                                                 | Type                                                                                        |
| ----------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Set Conversation List TextStyle** | Sets styling for conversation list's formatted text         | `MentionTextStyle`                                                                          |
| **Set GroupMembersRequestBuilder**  | Sets the builder for fetching group members                 | `GroupMembersRequest.GroupMembersRequestBuilder?`                                           |
| **Set UsersRequestBuilder**         | Sets the builder for fetching users                         | `UsersRequest.UsersRequestBuilder?`                                                         |
| **Set OnMentionClick**              | Sets a listener for mention click events in Message Bubbles | `((_ baseMessage: BaseMessage, _ tappedText: String, _ controller: UIViewController?)->())` |
| **Set composerTextStyle**           | Sets styling for composer's formatted text                  | `MentionTextStyle`                                                                          |

***

## Advanced

For advanced-level customization, you can set the style of the Mentions formatters. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your own formatter styles.

### Composer Mention Text Style

Assigns the list of text formatters. If the provided list is not null, it sets the list. Otherwise, it assigns the default text formatters retrieved from the data source. To configure the existing Mentions look and feel for [CometChatMessageComposer](/docs/ui-kit/ios/message-composer), refer to the code snippet below.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Create and configure composer mention style
    let composerMentionStyle = MentionTextStyle()
    composerMentionStyle.textColor = UIColor(hex: "#30A46C")

    // Apply the style globally
    CometChatMentionsFormatter.composerTextStyle = composerMentionStyle
    ```
  </Tab>
</Tabs>

### Message Bubble Mention Text Style

Assigns the list of text formatters. If the provided list is not null, it sets the list. Otherwise, it assigns the default text formatters retrieved from the data source. To configure the existing Mentions look and feel for [CometChatMessageList](/docs/ui-kit/ios/message-list), refer to the code snippet below.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Configure left bubble (incoming) mention style
    var leftBubbleMentionsStyle = MentionTextStyle()
    leftBubbleMentionsStyle.textColor = UIColor(hex: "#D6409F")
    CometChatMentionsFormatter.leftBubbleTextStyle = leftBubbleMentionsStyle

    // Configure right bubble (outgoing) mention style
    var rightBubbleMentionsStyle = MentionTextStyle()
    rightBubbleMentionsStyle.textColor = UIColor(hex: "#30A46C")
    CometChatMentionsFormatter.rightBubbleTextStyle = rightBubbleMentionsStyle
    ```
  </Tab>
</Tabs>

### Conversations Mention Text Style

Assigns the list of text formatters. If the provided list is not null, it sets the list. Otherwise, it assigns the default text formatters retrieved from the data source. To configure the existing Mentions look and feel for [CometChatConversations](/docs/ui-kit/ios/conversations), refer to the code snippet below.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Create and configure conversation list mention style
    let mentionsStyle = MentionTextStyle()
    mentionsStyle.textColor = UIColor(hex: "#30A46C")

    // Apply the style globally
    CometChatMentionsFormatter.conversationListTextStyle = mentionsStyle
    ```
  </Tab>
</Tabs>

***

## Next Steps

* [Message Composer](/docs/ui-kit/ios/message-composer) — Learn about the message input component
* [Message List](/docs/ui-kit/ios/message-list) — Display and customize chat messages
* [Conversations](/docs/ui-kit/ios/conversations) — Manage conversation lists

***


# Message Composer
Source: https://www.cometchat.com/docs/ui-kit/ios/message-composer

Configure CometChat iOS UI Kit Message Composer for text, media, attachments, mentions, voice notes, custom messages, and threads.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatMessageComposer",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "inherits": "UIView",
    "description": "Rich text input for composing and sending text, media, attachments, mentions, voice notes, and custom messages.",
    "props": {
      "data": {
        "user": "User? - recipient user for direct messaging",
        "group": "Group? - recipient group for group messaging",
        "parentMessageId": "Int? - parent message ID for thread replies"
      },
      "callbacks": {
        "onSendButtonClick": "(BaseMessage) -> Void",
        "onTextChangedListener": "(String) -> Void",
        "onError": "(CometChatException) -> Void"
      },
      "visibility": {
        "hideAttachmentButton": "Bool (default: false)",
        "hideVoiceRecordingButton": "Bool (default: false)",
        "hideStickersButton": "Bool (default: false)",
        "hideSendButton": "Bool (default: false)",
        "hideAIButton": "Bool (default: false)",
        "hideHeaderView": "Bool (default: false)",
        "hideFooterView": "Bool (default: false)"
      },
      "behavior": {
        "disableTypingEvents": "Bool (default: false)",
        "disableMentions": "Bool (default: false)",
        "enableMultipleAttachments": "Bool (default: true) - multi-select picker + attachment tray; false reverts to single-attachment send",
        "placeholderText": "String (default: 'Type a message...')"
      },
      "viewSlots": {
        "headerView": "(User?, Group?) -> UIView",
        "footerView": "(User?, Group?) -> UIView",
        "sendButtonView": "(User?, Group?) -> UIView",
        "auxillaryButtonView": "(User?, Group?) -> UIView",
        "attachmentOptions": "(User?, Group?, UIViewController?) -> [CometChatMessageComposerAction]"
      }
    },
    "methods": {
      "set(user:)": "Sets recipient user",
      "set(group:)": "Sets recipient group",
      "set(parentMessageId:)": "Sets parent message for threads",
      "setInitialComposerText(_:)": "Pre-fills composer text",
      "set(textFormatter:)": "Sets custom text formatter",
      "setDisableMentionAll(_:)": "Disables @all mentions",
      "setMentionAllLabel(_:_:)": "Customizes @all label"
    },
    "styling": {
      "globalStyle": "CometChatMessageComposer.style",
      "instanceStyle": "MessageComposerStyle",
      "subStyles": ["MediaRecorderStyle", "AttachmentSheetStyle", "SuggestionsStyle", "AIOptionsStyle", "MentionStyle"]
    }
  }
  ```
</Accordion>

| Field     | Value                      |
| --------- | -------------------------- |
| Component | `CometChatMessageComposer` |
| Package   | `CometChatUIKitSwift`      |
| Inherits  | `UIView`                   |

The `CometChatMessageComposer` component enables users to write and send messages including text, images, videos, audio, files, and custom messages. It supports attachments, voice recording, stickers, mentions, and AI-powered features.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatMessageComposer` provides a rich text input with attachment, emoji, voice recording, sticker, and send controls. Wire it alongside `CometChatMessageHeader` and `CometChatMessageList` to build a standard chat view.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ChatViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        CometChat.getUser(UID: "uid") { user in
            DispatchQueue.main.async {
                let header = CometChatMessageHeader()
                header.set(user: user)
                
                let messageList = CometChatMessageList()
                messageList.set(user: user)
                
                let composer = CometChatMessageComposer()
                composer.set(user: user)
                
                // Add to view hierarchy and layout
            }
        } onError: { error in
            print("Error: \(error?.errorDescription ?? "")")
        }
    }
}
```

<Frame>
  <img />
</Frame>

***

## Minimal Render

```swift lines theme={null}
import CometChatUIKitSwift

let composer = CometChatMessageComposer()
composer.set(user: user)
```

<Frame>
  <img />
</Frame>

***

## Actions and Events

### Callback Props

#### onSendButtonClick

Fires when the send button is clicked. Overrides the default send behavior.

```swift lines theme={null}
import CometChatUIKitSwift

let composer = CometChatMessageComposer()
composer.set(user: user)

composer.set(onSendButtonClick: { message in
    print("Custom send: \(message.id)")
})
```

#### onTextChangedListener

Fires as the user types in the composer input.

```swift lines theme={null}
import CometChatUIKitSwift

let composer = CometChatMessageComposer()
composer.set(user: user)

composer.set(onTextChangedListener: { text in
    print("Text changed: \(text)")
})
```

#### onError

Fires on internal errors.

```swift lines theme={null}
import CometChatUIKitSwift

let composer = CometChatMessageComposer()
composer.set(user: user)

composer.set(onError: { error in
    print("Composer error: \(error.errorDescription)")
})
```

### SDK Events (Real-Time, Automatic)

The component internally handles typing indicators and message sending. No manual SDK listener attachment needed.

***

## Custom View Slots

| Slot                  | Signature                                                                | Replaces                        |
| --------------------- | ------------------------------------------------------------------------ | ------------------------------- |
| `headerView`          | `(User?, Group?) -> UIView`                                              | Area above the composer input   |
| `footerView`          | `(User?, Group?) -> UIView`                                              | Area below the composer input   |
| `sendButtonView`      | `(User?, Group?) -> UIView`                                              | Send button                     |
| `auxillaryButtonView` | `(User?, Group?) -> UIView`                                              | Sticker and AI button area      |
| `attachmentOptions`   | `(User?, Group?, UIViewController?) -> [CometChatMessageComposerAction]` | Default attachment options list |

### headerView

Custom view above the composer input.

<Frame>
  <img />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let composer = CometChatMessageComposer()
composer.set(user: user)

composer.set(headerView: { user, group in
    let view = UIView()
    view.backgroundColor = UIColor.purple.withAlphaComponent(0.1)
    
    let label = UILabel()
    label.text = "User has paused their notifications"
    label.font = UIFont.systemFont(ofSize: 14)
    view.addSubview(label)
    
    return view
})
```

### footerView

Custom view below the composer input.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let composer = CometChatMessageComposer()
composer.set(user: user)

composer.set(footerView: { user, group in
    let view = UIView()
    
    let label = UILabel()
    label.text = "Messages are end-to-end encrypted"
    label.font = UIFont.systemFont(ofSize: 12)
    label.textColor = .secondaryLabel
    view.addSubview(label)
    
    return view
})
```

### sendButtonView

Replace the send button.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let composer = CometChatMessageComposer()
composer.set(user: user)

composer.set(sendButtonView: { user, group in
    let button = UIButton(type: .system)
    button.setImage(UIImage(systemName: "paperplane.fill"), for: .normal)
    button.tintColor = .systemBlue
    return button
})
```

### auxillaryButtonView

Replace the sticker and AI button area.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let composer = CometChatMessageComposer()
composer.set(user: user)

composer.set(auxillaryButtonView: { user, group in
    let stackView = UIStackView()
    stackView.axis = .horizontal
    stackView.spacing = 8
    
    let aiButton = UIButton(type: .system)
    aiButton.setImage(UIImage(systemName: "sparkles"), for: .normal)
    
    let emojiButton = UIButton(type: .system)
    emojiButton.setImage(UIImage(systemName: "face.smiling"), for: .normal)
    
    stackView.addArrangedSubview(aiButton)
    stackView.addArrangedSubview(emojiButton)
    
    return stackView
})
```

### attachmentOptions

Override the default attachment options.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let composer = CometChatMessageComposer()
composer.set(user: user)

composer.set(attachmentOptions: { user, group, controller in
    return [
        CometChatMessageComposerAction(
            id: "photo",
            text: "Photo",
            startIcon: UIImage(systemName: "photo"),
            startIconTint: .systemBlue,
            onActionClick: { print("Photo selected") }
        ),
        CometChatMessageComposerAction(
            id: "camera",
            text: "Camera",
            startIcon: UIImage(systemName: "camera"),
            startIconTint: .systemGreen,
            onActionClick: { print("Camera selected") }
        ),
        CometChatMessageComposerAction(
            id: "location",
            text: "Location",
            startIcon: UIImage(systemName: "location"),
            startIconTint: .systemRed,
            onActionClick: { print("Location selected") }
        )
    ]
})
```

***

## Multiple Attachments

The composer supports sending several attachments in one go. Tapping a media or file option opens a multi-select picker; the picks are staged in an **attachment tray** above the input box, upload immediately, and are sent together when the user taps send.

**How it works:**

* **Multi-select picking** — the photo/video picker and the document picker both allow selecting multiple items, capped to the app's per-message limit.
* **Attachment tray** — each staged file shows as a tile (thumbnail for media, chip for files/audio) with a live upload progress ring, a ✕ to cancel or remove, and tap-to-retry on network failure.
* **Upload before send** — files upload as soon as they are staged; the send button stays disabled until every upload finishes. Text typed in the composer becomes the **caption** of the batch.
* **One message per attachment type** — a mixed pick is split into separate messages in a fixed order (images → videos → audios → files) that render as grouped bubbles in the message list.
* **Clipboard paste** — images, videos, documents and audio files copied to the clipboard can be pasted straight into the composer and stage into the tray.
* **Voice notes stay standalone** — a mic recording always sends immediately as its own message and is never staged.
* Attachments cannot be added while **editing** a message; the attachment button is disabled for the duration of the edit.

### Limits and Validation

Limits are governed by the app's server settings (CometChat dashboard) — the composer reads them at runtime and they cannot be overridden client-side:

| Limit             | Setting                          | Behavior on violation                                                                                   |
| ----------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Files per message | `file.count.max` (default 10)    | Picker selection is capped; overflow picks are dropped with a "You can attach up to N files." snack bar |
| Per-file size     | `file.size.max` (default 100 MB) | The file stages as a red, non-retryable error tile; sending is blocked until it is removed              |
| File type         | Server-side validation           | The upload is refused by the server and the file becomes a red, non-retryable error tile                |

Tapping an error tile shows a snack bar with the reason ("File exceeds N MB.", "This file type isn't allowed."). The snack bar's appearance is themable through `CometChatErrorStateStyle`:

```swift theme={null}
CometChatErrorState.defaultStyle.backgroundColor = .systemRed
CometChatErrorState.defaultStyle.cornerRadius = 12
```

### Disabling Multiple Attachments

Set `enableMultipleAttachments` to `false` to restore the legacy behavior — single-item pickers that send immediately with no tray:

```swift theme={null}
composer.enableMultipleAttachments = false
```

This is composer-side only: received multi-attachment messages still render with the grouped bubbles (see [Message List](/docs/ui-kit/ios/message-list)).

***

## Common Patterns

### Thread composer

```swift lines theme={null}
let composer = CometChatMessageComposer()
composer.set(user: user)
composer.set(parentMessageId: parentMessage.id)
```

### Minimal composer — text only

```swift lines theme={null}
let composer = CometChatMessageComposer()
composer.set(user: user)
composer.hideAttachmentButton = true
composer.hideVoiceRecordingButton = true
composer.hideStickersButton = true
composer.hideAIButton = true
```

### Pre-filled text

```swift lines theme={null}
let composer = CometChatMessageComposer()
composer.set(user: user)
composer.setInitialComposerText("Hello! ")
composer.placeholderText = "Type a message..."
```

### Disable typing indicators

```swift lines theme={null}
let composer = CometChatMessageComposer()
composer.set(user: user)
composer.disableTypingEvents = true
```

### Disable mentions

```swift lines theme={null}
let composer = CometChatMessageComposer()
composer.set(user: user)
composer.disableMentions = true
```

### Custom send button action

```swift lines theme={null}
let composer = CometChatMessageComposer()
composer.set(user: user)

composer.set(onSendButtonClick: { message in
    print("Sending message: \(message)")
})
```

***

## Styling

### Style Hierarchy

1. Global styles (`CometChatMessageComposer.style`) apply to all instances
2. Instance styles override global for specific instances

### Global Level Styling

```swift lines theme={null}
import CometChatUIKitSwift

CometChatMessageComposer.style.backgroundColor = .systemBackground
CometChatMessageComposer.style.activeSendButtonImageBackgroundColor = .systemBlue
CometChatMessageComposer.style.attachmentImageTint = .systemGray
CometChatMessageComposer.style.voiceRecordingImageTint = .systemGray
```

### Instance Level Styling

```swift lines theme={null}
import CometChatUIKitSwift

var customStyle = MessageComposerStyle()
customStyle.backgroundColor = UIColor(red: 0.95, green: 0.95, blue: 0.97, alpha: 1.0)
customStyle.activeSendButtonImageBackgroundColor = .systemOrange
customStyle.composeBoxBackgroundColor = .white
customStyle.composeBoxBorderColor = .systemGray4

let composer = CometChatMessageComposer()
composer.style = customStyle
```

<Frame>
  <img />
</Frame>

### Key Style Properties

| Property                                 | Type                    | Description                     |
| ---------------------------------------- | ----------------------- | ------------------------------- |
| `backgroundColor`                        | `UIColor`               | Background color                |
| `borderWidth`                            | `CGFloat`               | Border width                    |
| `borderColor`                            | `UIColor`               | Border color                    |
| `cornerRadius`                           | `CometChatCornerStyle?` | Corner radius                   |
| `placeHolderTextFont`                    | `UIFont`                | Placeholder font                |
| `placeHolderTextColor`                   | `UIColor`               | Placeholder color               |
| `textFiledColor`                         | `UIColor`               | Input text color                |
| `textFiledFont`                          | `UIFont`                | Input text font                 |
| `sendButtonImage`                        | `UIImage?`              | Send button icon                |
| `sendButtonImageTint`                    | `UIColor`               | Send button tint                |
| `activeSendButtonImageBackgroundColor`   | `UIColor`               | Active send button background   |
| `inactiveSendButtonImageBackgroundColor` | `UIColor`               | Inactive send button background |
| `composeBoxBackgroundColor`              | `UIColor`               | Compose box background          |
| `composeBoxBorderColor`                  | `UIColor`               | Compose box border color        |
| `composeBoxBorderWidth`                  | `CGFloat`               | Compose box border width        |
| `attachmentImage`                        | `UIImage?`              | Attachment button icon          |
| `attachmentImageTint`                    | `UIColor`               | Attachment icon tint            |
| `voiceRecordingImage`                    | `UIImage?`              | Voice recording icon            |
| `voiceRecordingImageTint`                | `UIColor`               | Voice recording tint            |

### Sub-Component Styles

| Property               | Type                   | Description               |
| ---------------------- | ---------------------- | ------------------------- |
| `mediaRecorderStyle`   | `MediaRecorderStyle`   | Voice recording interface |
| `attachmentSheetStyle` | `AttachmentSheetStyle` | Attachment options sheet  |
| `suggestionsStyle`     | `SuggestionsStyle`     | Mentions suggestions view |
| `aiOptionsStyle`       | `AIOptionsStyle`       | AI options menu           |
| `mentionStyle`         | `MentionStyle`         | Mentions appearance       |

### Customization Matrix

| What to change         | Where     | Property/API                               |
| ---------------------- | --------- | ------------------------------------------ |
| Override send behavior | Callback  | `set(onSendButtonClick:)`                  |
| Track text input       | Callback  | `set(onTextChangedListener:)`              |
| Toggle visibility      | Props     | `hide<Feature>` boolean props              |
| Custom attachments     | View Slot | `set(attachmentOptions:)`                  |
| Replace UI sections    | View Slot | `set(headerView:)`, `set(sendButtonView:)` |
| Change colors, fonts   | Style     | `MessageComposerStyle` properties          |

***

## Props

All props are optional. Sorted alphabetically.

| Property                            | Type                       | Default               | Description                                                                                                                     |
| ----------------------------------- | -------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `disableMentions`                   | `Bool`                     | `false`               | Disables the @mention feature                                                                                                   |
| `disableSoundForMessages`           | `Bool`                     | `false`               | Disables sound when sending messages                                                                                            |
| `disableTypingEvents`               | `Bool`                     | `false`               | Disables sending typing indicators                                                                                              |
| `enableMultipleAttachments`         | `Bool`                     | `true`                | Multi-select attachment picking with a preview tray; `false` reverts to the legacy single-attachment, send-immediately behavior |
| `hideAIButton`                      | `Bool`                     | `false`               | Hides the AI button                                                                                                             |
| `hideAttachmentButton`              | `Bool`                     | `false`               | Hides the attachment button                                                                                                     |
| `hideAudioAttachmentOption`         | `Bool`                     | `false`               | Hides the audio attachment option                                                                                               |
| `hideCollaborativeDocumentOption`   | `Bool`                     | `false`               | Hides the collaborative document option                                                                                         |
| `hideCollaborativeWhiteboardOption` | `Bool`                     | `false`               | Hides the collaborative whiteboard option                                                                                       |
| `hideFileAttachmentOption`          | `Bool`                     | `false`               | Hides the file attachment option                                                                                                |
| `hideFooterView`                    | `Bool`                     | `false`               | Hides the footer view                                                                                                           |
| `hideHeaderView`                    | `Bool`                     | `false`               | Hides the header view                                                                                                           |
| `hideImageAttachmentOption`         | `Bool`                     | `false`               | Hides the image attachment option                                                                                               |
| `hidePollsOption`                   | `Bool`                     | `false`               | Hides the polls option                                                                                                          |
| `hideSendButton`                    | `Bool`                     | `false`               | Hides the send button                                                                                                           |
| `hideStickersButton`                | `Bool`                     | `false`               | Hides the stickers button                                                                                                       |
| `hideVideoAttachmentOption`         | `Bool`                     | `false`               | Hides the video attachment option                                                                                               |
| `hideVoiceRecordingButton`          | `Bool`                     | `false`               | Hides the voice recording button                                                                                                |
| `maxLine`                           | `Int`                      | `5`                   | Maximum lines before scrolling                                                                                                  |
| `placeholderText`                   | `String`                   | `"Type a message..."` | Placeholder text                                                                                                                |
| `textFormatters`                    | `[CometChatTextFormatter]` | `[]`                  | Custom text formatters                                                                                                          |

***

## Methods

### set(textFormatter:)

Sets a custom text formatter for the composer input.

```swift lines theme={null}
let composer = CometChatMessageComposer()
let mentionFormatter = MentionTextFormatter(trackingCharacter: "@")
composer.set(textFormatter: mentionFormatter)
```

### setDisableMentionAll(\_:)

Disables or enables the @all mention feature that notifies all group members.

```swift lines theme={null}
let composer = CometChatMessageComposer()
composer.setDisableMentionAll(true)
```

### setMentionAllLabel(*:*:)

Customizes the label displayed for @all mentions in the suggestions list.

```swift lines theme={null}
let composer = CometChatMessageComposer()
composer.setMentionAllLabel("Everyone", "Notify all members in this group")
```

***

## Related Components

* [Message List](/docs/ui-kit/ios/message-list) — Display messages in a conversation
* [Message Header](/docs/ui-kit/ios/message-header) — Display user/group details
* [Mentions Formatter](/docs/ui-kit/ios/mentions-formatter-guide) — Configure @mention formatting


# Message Header
Source: https://www.cometchat.com/docs/ui-kit/ios/message-header

Configure CometChat iOS UI Kit Message Header with user or group details, avatar, status, typing indicators, navigation, and call buttons.

The `CometChatMessageHeader` component displays user or group details in the toolbar including avatar, name, status, and typing indicators. It also provides navigation controls and call buttons.

<Frame>
  <img alt="CometChatMessageHeader showing user avatar, name, online status, and call buttons in the navigation bar" />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatMessageHeader",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "description": "Displays user or group details in the toolbar with avatar, name, status, typing indicators, and navigation controls.",
    "inherits": "UIView",
    "primaryOutput": {
      "callback": "onBack",
      "type": "() -> Void"
    },
    "props": {
      "data": {
        "user": {
          "type": "User?",
          "default": "nil",
          "note": "User to display in header"
        },
        "group": {
          "type": "Group?",
          "default": "nil",
          "note": "Group to display in header"
        }
      },
      "callbacks": {
        "onBack": "() -> Void",
        "onError": "(CometChatException) -> Void",
        "onAiChatHistoryClicked": "() -> Void",
        "onAiNewChatClicked": "() -> Void"
      },
      "visibility": {
        "hideBackButton": { "type": "Bool", "default": false },
        "hideUserStatus": { "type": "Bool", "default": false },
        "hideVideoCallButton": { "type": "Bool", "default": false },
        "hideVoiceCallButton": { "type": "Bool", "default": false },
        "hideNewChatButton": { "type": "Bool", "default": false },
        "hideChatHistoryButton": { "type": "Bool", "default": false },
        "disableTyping": { "type": "Bool", "default": false }
      },
      "style": {
        "avatarStyle": { "type": "AvatarStyle", "default": "AvatarStyle()" },
        "statusIndicatorStyle": { "type": "StatusIndicatorStyle", "default": "StatusIndicatorStyle()" },
        "typingIndicatorStyle": { "type": "TypingIndicatorStyle", "default": "TypingIndicatorStyle()" }
      },
      "formatting": {
        "dateTimeFormatter": { "type": "CometChatDateTimeFormatter?", "default": "nil" }
      },
      "viewSlots": {
        "listItemView": "(User?, Group?) -> UIView",
        "leadingView": "(User?, Group?) -> UIView",
        "titleView": "(User?, Group?) -> UIView",
        "subtitleView": "(User?, Group?) -> UIView",
        "trailView": "(User?, Group?) -> UIView"
      }
    },
    "methods": {
      "connection": {
        "connect()": "Establishes WebSocket connection for real-time updates",
        "disconnect()": "Disconnects WebSocket connection"
      },
      "menuCustomization": {
        "set(options:)": "((User?, Group?) -> [CometChatMessageHeaderOption])? - Sets custom menu options"
      }
    },
    "events": [],
    "sdkListeners": [
      "onUserOnline",
      "onUserOffline",
      "onTypingStarted",
      "onTypingEnded"
    ],
    "compositionExample": {
      "description": "MessageHeader is typically used within CometChatMessages at the top of the chat screen",
      "components": ["CometChatMessageHeader", "CometChatMessageList", "CometChatMessageComposer"],
      "flow": "User views header → sees recipient info → taps back to return to conversations"
    },
    "types": {}
  }
  ```
</Accordion>

| Field     | Value                    |
| --------- | ------------------------ |
| Component | `CometChatMessageHeader` |
| Package   | `CometChatUIKitSwift`    |
| Inherits  | `UIView`                 |

***

## Where It Fits

`CometChatMessageHeader` displays the recipient's information at the top of the chat screen. It's typically used within `CometChatMessages` alongside `CometChatMessageList` and `CometChatMessageComposer`.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ChatViewController: UIViewController {
    
    private var messageHeader: CometChatMessageHeader!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupMessageHeader()
    }
    
    private func setupMessageHeader(for user: User) {
        messageHeader = CometChatMessageHeader()
        messageHeader.set(user: user)
        
        // Handle back button
        messageHeader.set(onBack: { [weak self] in
            self?.navigationController?.popViewController(animated: true)
        })
        
        view.addSubview(messageHeader)
    }
}
```

<Frame>
  <img alt="CometChatMessageHeader showing user avatar, name, online status, and call buttons in the navigation bar" />
</Frame>

***

## Minimal Render

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let messageHeader = CometChatMessageHeader()
messageHeader.set(user: user)
```

<Frame>
  <img alt="CometChatMessageHeader showing minimal render with user details and default styling" />
</Frame>

***

## Actions and Events

### Callback Props

#### onBack

Fires when the back button is pressed. Use this for custom navigation handling.

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()

messageHeader.set(onBack: { [weak self] in
    self?.navigationController?.popViewController(animated: true)
})
```

#### onError

Fires when an error occurs.

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()

messageHeader.set(onError: { error in
    print("Error: \(error.errorDescription)")
})
```

### Actions Reference

| Method          | Description                           | Example                    |
| --------------- | ------------------------------------- | -------------------------- |
| `set(onBack:)`  | Triggered when back button is pressed | Custom navigation          |
| `set(onError:)` | Triggered when an error occurs        | Show error alert           |
| `set(user:)`    | Sets the user to display              | Configure header for user  |
| `set(group:)`   | Sets the group to display             | Configure header for group |

### SDK Events (Real-Time, Automatic)

| SDK Listener      | Internal behavior                   |
| ----------------- | ----------------------------------- |
| `onUserOnline`    | Updates status indicator to online  |
| `onUserOffline`   | Updates status indicator to offline |
| `onTypingStarted` | Shows typing indicator in subtitle  |
| `onTypingEnded`   | Hides typing indicator              |

***

## Custom View Slots

| Slot           | Signature                   | Replaces                  |
| -------------- | --------------------------- | ------------------------- |
| `listItemView` | `(User?, Group?) -> UIView` | Entire header content     |
| `leadingView`  | `(User?, Group?) -> UIView` | Avatar / left section     |
| `titleView`    | `(User?, Group?) -> UIView` | Name / title text         |
| `subtitleView` | `(User?, Group?) -> UIView` | Status / subtitle text    |
| `trailView`    | `(User?, Group?) -> UIView` | Right side (call buttons) |

### listItemView

Replace the entire header content with a custom view.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let messageHeader = CometChatMessageHeader()

messageHeader.set(listItemView: { user, group in
    let customView = CustomHeaderView()
    customView.configure(user: user, group: group)
    return customView
})
```

You can create a `CustomHeaderView` as a custom `UIView`:

```swift lines theme={null}
import UIKit
import CometChatSDK

class CustomHeaderView: UIView {
    
    private let backButton: UIButton = {
        let button = UIButton(type: .system)
        button.setImage(UIImage(systemName: "chevron.left"), for: .normal)
        button.tintColor = .black
        return button
    }()
    
    private let profileImageView: UIImageView = {
        let imageView = UIImageView()
        imageView.contentMode = .scaleAspectFill
        imageView.layer.cornerRadius = 18
        imageView.clipsToBounds = true
        imageView.backgroundColor = .lightGray
        return imageView
    }()
    
    private let nameLabel: UILabel = {
        let label = UILabel()
        label.font = UIFont.systemFont(ofSize: 16, weight: .semibold)
        label.textColor = .black
        return label
    }()
    
    private let statusLabel: UILabel = {
        let label = UILabel()
        label.font = UIFont.systemFont(ofSize: 12)
        label.textColor = .gray
        return label
    }()
    
    private let videoCallButton: UIButton = {
        let button = UIButton(type: .system)
        button.setImage(UIImage(systemName: "video.fill"), for: .normal)
        button.tintColor = .black
        return button
    }()
    
    private let callButton: UIButton = {
        let button = UIButton(type: .system)
        button.setImage(UIImage(systemName: "phone.fill"), for: .normal)
        button.tintColor = .black
        return button
    }()
    
    override init(frame: CGRect) {
        super.init(frame: frame)
        setupView()
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    private func setupView() {
        backgroundColor = .white

        let userInfoStack = UIStackView(arrangedSubviews: [nameLabel, statusLabel])
        userInfoStack.axis = .vertical
        userInfoStack.spacing = 2
        userInfoStack.alignment = .leading

        let rightButtonsStack = UIStackView(arrangedSubviews: [videoCallButton, callButton])
        rightButtonsStack.axis = .horizontal
        rightButtonsStack.spacing = 16

        addSubview(backButton)
        addSubview(profileImageView)
        addSubview(userInfoStack)
        addSubview(rightButtonsStack)

        backButton.translatesAutoresizingMaskIntoConstraints = false
        profileImageView.translatesAutoresizingMaskIntoConstraints = false
        userInfoStack.translatesAutoresizingMaskIntoConstraints = false
        rightButtonsStack.translatesAutoresizingMaskIntoConstraints = false

        NSLayoutConstraint.activate([
            backButton.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 16),
            backButton.centerYAnchor.constraint(equalTo: centerYAnchor),
            backButton.widthAnchor.constraint(equalToConstant: 30),
            backButton.heightAnchor.constraint(equalToConstant: 30),

            profileImageView.leadingAnchor.constraint(equalTo: backButton.trailingAnchor, constant: 10),
            profileImageView.centerYAnchor.constraint(equalTo: centerYAnchor),
            profileImageView.widthAnchor.constraint(equalToConstant: 36),
            profileImageView.heightAnchor.constraint(equalToConstant: 36),

            userInfoStack.leadingAnchor.constraint(equalTo: profileImageView.trailingAnchor, constant: 10),
            userInfoStack.centerYAnchor.constraint(equalTo: centerYAnchor),

            rightButtonsStack.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -16),
            rightButtonsStack.centerYAnchor.constraint(equalTo: centerYAnchor)
        ])
    }
    
    func configure(user: User?, group: Group?) {
        nameLabel.text = user?.name ?? group?.name ?? "Chat"
        if let user = user {
            statusLabel.text = user.status == .online ? "Online" : "Offline"
        } else if let group = group {
            statusLabel.text = "\(group.membersCount) members"
        }
    }
}
```

### leadingView

Customize the leading view (avatar area) of the header.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let messageHeader = CometChatMessageHeader()

messageHeader.set(leadingView: { user, group in
    let view = CustomLeadingView()
    return view
})
```

<Frame>
  <img alt="CometChatMessageHeader with custom leadingView showing avatar with Admin badge overlay" />
</Frame>

You can create a `CustomLeadingView` as a custom `UIView`:

```swift lines theme={null}
import UIKit

class CustomLeadingView: UIView {

    private let profileImageView: UIImageView = {
        let imageView = UIImageView()
        imageView.contentMode = .scaleAspectFill
        imageView.layer.cornerRadius = 20
        imageView.clipsToBounds = true
        imageView.backgroundColor = .lightGray
        imageView.image = UIImage(systemName: "person.fill")
        return imageView
    }()

    private let badgeLabel: UILabel = {
        let label = UILabel()
        label.text = "Admin"
        label.font = UIFont.systemFont(ofSize: 10, weight: .bold)
        label.textColor = .white
        label.backgroundColor = .orange
        label.textAlignment = .center
        label.layer.cornerRadius = 6
        label.clipsToBounds = true
        return label
    }()

    override init(frame: CGRect) {
        super.init(frame: frame)
        setupView()
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    private func setupView() {
        addSubview(profileImageView)
        addSubview(badgeLabel)

        profileImageView.translatesAutoresizingMaskIntoConstraints = false
        badgeLabel.translatesAutoresizingMaskIntoConstraints = false

        NSLayoutConstraint.activate([
            profileImageView.leadingAnchor.constraint(equalTo: leadingAnchor),
            profileImageView.trailingAnchor.constraint(equalTo: trailingAnchor),
            profileImageView.topAnchor.constraint(equalTo: topAnchor),
            profileImageView.bottomAnchor.constraint(equalTo: bottomAnchor),
            profileImageView.heightAnchor.constraint(equalToConstant: 40),
            profileImageView.widthAnchor.constraint(equalToConstant: 40),

            badgeLabel.trailingAnchor.constraint(equalTo: profileImageView.trailingAnchor),
            badgeLabel.bottomAnchor.constraint(equalTo: profileImageView.bottomAnchor),
            badgeLabel.widthAnchor.constraint(equalToConstant: 40),
            badgeLabel.heightAnchor.constraint(equalToConstant: 12)
        ])
    }
}
```

### titleView

Customize the title view of the header.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let messageHeader = CometChatMessageHeader()

messageHeader.set(titleView: { user, group in
    let view = CustomTitleView()
    return view
})
```

<Frame>
  <img alt="CometChatMessageHeader with custom titleView showing group name with Public badge" />
</Frame>

You can create a `CustomTitleView` as a custom `UIView`:

```swift lines theme={null}
import UIKit

class CustomTitleView: UIView {

    private let titleLabel: UILabel = {
        let label = UILabel()
        label.text = "Artistic Design"
        label.font = UIFont.systemFont(ofSize: 16, weight: .medium)
        label.textColor = .black
        return label
    }()

    private let publicBadge: UIView = {
        let view = UIView()
        view.backgroundColor = .blue
        view.layer.cornerRadius = 10

        let icon = UIImageView(image: UIImage(systemName: "person.3.fill"))
        icon.tintColor = .white
        icon.contentMode = .scaleAspectFit

        let label = UILabel()
        label.text = "Public"
        label.font = UIFont.systemFont(ofSize: 12, weight: .bold)
        label.textColor = .white

        let stackView = UIStackView(arrangedSubviews: [icon, label])
        stackView.spacing = 4
        stackView.alignment = .center
        stackView.translatesAutoresizingMaskIntoConstraints = false

        view.addSubview(stackView)

        NSLayoutConstraint.activate([
            stackView.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            stackView.centerYAnchor.constraint(equalTo: view.centerYAnchor),
            view.widthAnchor.constraint(equalToConstant: 60),
            view.heightAnchor.constraint(equalToConstant: 20)
        ])
        
        return view
    }()

    override init(frame: CGRect) {
        super.init(frame: frame)
        setupView()
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    private func setupView() {
        addSubview(titleLabel)
        addSubview(publicBadge)

        titleLabel.translatesAutoresizingMaskIntoConstraints = false
        publicBadge.translatesAutoresizingMaskIntoConstraints = false

        NSLayoutConstraint.activate([
            titleLabel.leadingAnchor.constraint(equalTo: leadingAnchor),
            titleLabel.centerYAnchor.constraint(equalTo: centerYAnchor),

            publicBadge.leadingAnchor.constraint(equalTo: titleLabel.trailingAnchor, constant: 6),
            publicBadge.centerYAnchor.constraint(equalTo: centerYAnchor)
        ])
    }
}
```

### subtitleView

Customize the subtitle area (status, typing indicator).

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let messageHeader = CometChatMessageHeader()

messageHeader.set(subtitleView: { user, group in
    let label = UILabel()
    label.font = UIFont.systemFont(ofSize: 13)
    label.textColor = UIColor.secondaryLabel
    
    if let user = user {
        label.text = user.status == .online ? "🟢 Online" : "⚫ Offline"
    } else if let group = group {
        label.text = "\(group.membersCount) members"
    }
    
    return label
})
```

### trailView

Customize the right side of the header (call buttons, etc.).

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let messageHeader = CometChatMessageHeader()

messageHeader.set(trailView: { user, group in
    let view = CustomTrailView()
    return view
})
```

<Frame>
  <img alt="CometChatMessageHeader with custom trailView showing video call, voice call, and bookmark buttons" />
</Frame>

You can create a `CustomTrailView` as a custom `UIView`:

```swift lines theme={null}
import UIKit

class CustomTrailView: UIView {

    private let videoCallButton: UIButton = {
        let button = UIButton(type: .system)
        let image = UIImage(systemName: "video.fill")?.withRenderingMode(.alwaysTemplate)
        button.setImage(image, for: .normal)
        button.tintColor = .black
        return button
    }()

    private let callButton: UIButton = {
        let button = UIButton(type: .system)
        let image = UIImage(systemName: "phone.fill")?.withRenderingMode(.alwaysTemplate)
        button.setImage(image, for: .normal)
        button.tintColor = .black
        return button
    }()
    
    private let bookMarkButton: UIButton = {
        let button = UIButton(type: .system)
        let image = UIImage(systemName: "bookmark.fill")?.withRenderingMode(.alwaysTemplate)
        button.setImage(image, for: .normal)
        button.tintColor = .black
        return button
    }()

    override init(frame: CGRect) {
        super.init(frame: frame)
        setupView()
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    private func setupView() {
        let buttonsStack = UIStackView(arrangedSubviews: [videoCallButton, callButton, bookMarkButton])
        buttonsStack.axis = .horizontal
        buttonsStack.spacing = 16
        buttonsStack.distribution = .fillEqually

        addSubview(buttonsStack)
        buttonsStack.translatesAutoresizingMaskIntoConstraints = false

        NSLayoutConstraint.activate([
            buttonsStack.leadingAnchor.constraint(equalTo: leadingAnchor),
            buttonsStack.trailingAnchor.constraint(equalTo: trailingAnchor),
            buttonsStack.topAnchor.constraint(equalTo: topAnchor),
            buttonsStack.bottomAnchor.constraint(equalTo: bottomAnchor)
        ])
    }
}
```

***

## Styling

### Style Hierarchy

1. Global styles (`CometChatMessageHeader.style`) apply to all instances
2. Instance styles override global for specific instances

### Global Level Styling

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

// Apply global styles that affect all CometChatMessageHeader instances
CometChatMessageHeader.style.backgroundColor = UIColor.systemBackground
CometChatMessageHeader.style.titleTextColor = UIColor.label
CometChatMessageHeader.style.titleTextFont = UIFont.systemFont(ofSize: 17, weight: .semibold)
CometChatMessageHeader.style.subtitleTextColor = UIColor.secondaryLabel
CometChatMessageHeader.style.subtitleTextFont = UIFont.systemFont(ofSize: 13)
CometChatMessageHeader.style.backButtonImageTintColor = UIColor.systemBlue

// Custom avatar style
let avatarStyle = AvatarStyle()
avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 20)
CometChatMessageHeader.style.avatarStyle = avatarStyle
```

### Instance Level Styling

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

// Create a custom style for a specific instance
var customStyle = MessageHeaderStyle()
customStyle.backgroundColor = UIColor(red: 0.95, green: 0.95, blue: 0.97, alpha: 1.0)
customStyle.titleTextColor = UIColor.darkGray
customStyle.titleTextFont = UIFont.systemFont(ofSize: 18, weight: .bold)
customStyle.subtitleTextColor = UIColor.gray

let messageHeader = CometChatMessageHeader()
messageHeader.style = customStyle
```

<Frame>
  <img alt="CometChatMessageHeader with custom instance styling showing modified background color and text appearance" />
</Frame>

### Key Style Properties

| Property                                    | Type                    | Default                               | Description                                   |
| ------------------------------------------- | ----------------------- | ------------------------------------- | --------------------------------------------- |
| `backgroundColor`                           | `UIColor`               | `CometChatTheme.backgroundColor01`    | Background color                              |
| `borderWidth`                               | `CGFloat`               | `0`                                   | Border width                                  |
| `borderColor`                               | `UIColor`               | `.clear`                              | Border color                                  |
| `cornerRadius`                              | `CometChatCornerStyle?` | `nil`                                 | Corner radius                                 |
| `titleTextColor`                            | `UIColor`               | `CometChatTheme.textColorPrimary`     | Title text color                              |
| `titleTextFont`                             | `UIFont`                | `CometChatTypography.Heading4.medium` | Title font                                    |
| `subtitleTextColor`                         | `UIColor`               | `CometChatTheme.textColorSecondary`   | Subtitle text color                           |
| `subtitleTextFont`                          | `UIFont`                | `CometChatTypography.Body.regular`    | Subtitle font                                 |
| `backButtonImageTintColor`                  | `UIColor`               | `CometChatTheme.iconColorPrimary`     | Back button tint                              |
| `backButtonIcon`                            | `UIImage?`              | System chevron                        | Back button icon                              |
| `privateGroupBadgeImageTintColor`           | `UIColor`               | `CometChatTheme.iconColorSecondary`   | Private group badge tint                      |
| `passwordProtectedGroupBadgeImageTintColor` | `UIColor`               | `CometChatTheme.iconColorSecondary`   | Password group badge tint                     |
| `avatarStyle`                               | `AvatarStyle`           | `AvatarStyle()`                       | Avatar customization                          |
| `statusIndicatorStyle`                      | `StatusIndicatorStyle`  | `StatusIndicatorStyle()`              | Online/offline status indicator customization |
| `typingIndicatorStyle`                      | `TypingIndicatorStyle`  | `TypingIndicatorStyle()`              | Typing indicator customization                |

### Customization Matrix

| What to change      | Where     | Property/API                                 | Example                                     |
| ------------------- | --------- | -------------------------------------------- | ------------------------------------------- |
| Background color    | Style     | `backgroundColor`                            | `UIColor.systemBackground`                  |
| Title appearance    | Style     | `titleTextColor`, `titleTextFont`            | Custom colors and fonts                     |
| Subtitle appearance | Style     | `subtitleTextColor`, `subtitleTextFont`      | Custom colors and fonts                     |
| Back button         | Style     | `backButtonIcon`, `backButtonImageTintColor` | Custom icon and color                       |
| Avatar look         | Style     | `avatarStyle`                                | `AvatarStyle()` with custom radius          |
| Status indicator    | Style     | `statusIndicatorStyle`                       | `StatusIndicatorStyle()` with custom colors |
| Typing indicator    | Style     | `typingIndicatorStyle`                       | `TypingIndicatorStyle()` with custom font   |
| Hide back button    | Property  | `hideBackButton`                             | `header.hideBackButton = true`              |
| Hide status         | Property  | `hideUserStatus`                             | `header.hideUserStatus = true`              |
| Disable typing      | Property  | `disableTyping`                              | `header.disableTyping = true`               |
| Hide AI buttons     | Property  | `hideNewChatButton`, `hideChatHistoryButton` | `header.hideNewChatButton = true`           |
| Custom subtitle     | View Slot | `set(subtitleView:)`                         | See Custom View Slots                       |
| Custom menu options | Method    | `set(options:)`                              | See Menu Customization                      |

***

## Connection Management

Manually control the WebSocket connection for the message header.

### connect()

Establishes the WebSocket connection for real-time updates. Use this when you need to manually reconnect after disconnecting.

```swift lines theme={null}
@discardableResult
public func connect() -> Self
```

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()

// Manually connect to receive real-time updates
messageHeader.connect()
```

### disconnect()

Disconnects the WebSocket connection. Use this when you want to temporarily stop receiving real-time updates, such as when the view is not visible.

```swift lines theme={null}
@discardableResult
public func disconnect() -> Self
```

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

class ChatViewController: UIViewController {
    
    private var messageHeader: CometChatMessageHeader!
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        messageHeader.disconnect()
    }
    
    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        messageHeader.connect()
    }
}
```

***

## Menu Customization

### set(options:)

Sets custom menu options for the message header. These options appear in the header's menu (typically accessed via a more button or long press).

```swift lines theme={null}
@discardableResult
public func set(options: ((_ user: User?, _ group: Group?) -> [CometChatMessageHeaderOption])?) -> Self
```

| Parameter | Type                                                   | Description                                                                      |
| --------- | ------------------------------------------------------ | -------------------------------------------------------------------------------- |
| `options` | `((User?, Group?) -> [CometChatMessageHeaderOption])?` | Closure that returns an array of menu options based on the current user or group |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let messageHeader = CometChatMessageHeader()

messageHeader.set(options: { user, group in
    var options = [CometChatMessageHeaderOption]()
    
    // Add a custom "View Profile" option
    let viewProfileOption = CometChatMessageHeaderOption(
        id: "view_profile",
        title: "View Profile",
        icon: UIImage(systemName: "person.circle")
    ) { user, group in
        // Handle view profile action
        print("View profile tapped")
    }
    options.append(viewProfileOption)
    
    // Add a custom "Mute Notifications" option
    let muteOption = CometChatMessageHeaderOption(
        id: "mute_notifications",
        title: "Mute Notifications",
        icon: UIImage(systemName: "bell.slash")
    ) { user, group in
        // Handle mute action
        print("Mute notifications tapped")
    }
    options.append(muteOption)
    
    return options
})
```

***

## Props

All props are optional. Sorted alphabetically.

### avatarStyle

Customizes the appearance of the avatar in the message header.

|         |                 |
| ------- | --------------- |
| Type    | `AvatarStyle`   |
| Default | `AvatarStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()

let avatarStyle = AvatarStyle()
avatarStyle.backgroundColor = UIColor.systemBlue
avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 20)
avatarStyle.borderWidth = 2
avatarStyle.borderColor = UIColor.white

messageHeader.set(avatarStyle: avatarStyle)
```

### dateTimeFormatter

Custom formatter for date/time display in the message header (e.g., "Last seen at...").

|         |                               |
| ------- | ----------------------------- |
| Type    | `CometChatDateTimeFormatter?` |
| Default | `nil`                         |

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()

let dateTimeFormatter = CometChatDateTimeFormatter()
dateTimeFormatter.todayFormat = "h:mm a"
dateTimeFormatter.yesterdayFormat = "'Yesterday at' h:mm a"
dateTimeFormatter.otherFormat = "MMM d, yyyy"

messageHeader.dateTimeFormatter = dateTimeFormatter
```

### disableTyping

Disables typing indicators in the message header.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()
messageHeader.disableTyping = true
```

### hideBackButton

Hides the back button in the header.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideChatHistoryButton

Hides the AI chat history button in the header.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()
messageHeader.hideChatHistoryButton = true
```

### hideNewChatButton

Hides the AI new chat button in the header.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()
messageHeader.hideNewChatButton = true
```

### hideUserStatus

Hides the user status (online/offline/last active).

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideVideoCallButton

Hides the video call button.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideVoiceCallButton

Hides the voice call button.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### onAiChatHistoryClicked

Callback triggered when the AI chat history button is clicked.

|         |                 |
| ------- | --------------- |
| Type    | `(() -> Void)?` |
| Default | `nil`           |

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()

messageHeader.set(onAiChatHistoryClicked: { [weak self] in
    // Handle AI chat history button click
    self?.presentAiChatHistory()
})
```

### onAiNewChatClicked

Callback triggered when the AI new chat button is clicked.

|         |                 |
| ------- | --------------- |
| Type    | `(() -> Void)?` |
| Default | `nil`           |

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()

messageHeader.set(onAiNewChatClicked: { [weak self] in
    // Handle AI new chat button click
    self?.startNewAiChat()
})
```

### statusIndicatorStyle

Customizes the appearance of the online/offline status indicator.

|         |                          |
| ------- | ------------------------ |
| Type    | `StatusIndicatorStyle`   |
| Default | `StatusIndicatorStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()

let statusIndicatorStyle = StatusIndicatorStyle()
statusIndicatorStyle.backgroundColor = UIColor.systemGreen
statusIndicatorStyle.borderWidth = 2
statusIndicatorStyle.borderColor = UIColor.white
statusIndicatorStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 6)

messageHeader.set(statusIndicatorStyle: statusIndicatorStyle)
```

### typingIndicatorStyle

Customizes the appearance of the typing indicator in the message header subtitle.

|         |                          |
| ------- | ------------------------ |
| Type    | `TypingIndicatorStyle`   |
| Default | `TypingIndicatorStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()

let typingIndicatorStyle = TypingIndicatorStyle()
typingIndicatorStyle.textColor = UIColor.systemGray
typingIndicatorStyle.textFont = UIFont.italicSystemFont(ofSize: 13)

messageHeader.set(typingIndicatorStyle: typingIndicatorStyle)
```

***

## Events

The MessageHeader component does not emit any global UI events.

***

## Date Time Formatter

Customize how timestamps appear in the message header (e.g., "Last seen at...") using the `CometChatDateTimeFormatter`.

### Global Level Formatting

```swift lines theme={null}
import CometChatUIKitSwift

// Customize time format for last seen
CometChatMessageHeader.dateTimeFormatter.time = { timestamp in
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    let formatter = DateFormatter()
    formatter.dateFormat = "h:mm a"
    return "Last seen at " + formatter.string(from: date)
}

// Customize today format
CometChatMessageHeader.dateTimeFormatter.today = { timestamp in
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    let formatter = DateFormatter()
    formatter.dateFormat = "h:mm a"
    return "Last seen today at " + formatter.string(from: date)
}

// Customize yesterday format
CometChatMessageHeader.dateTimeFormatter.yesterday = { timestamp in
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    let formatter = DateFormatter()
    formatter.dateFormat = "h:mm a"
    return "Last seen yesterday at " + formatter.string(from: date)
}
```

### Instance Level Formatting

```swift lines theme={null}
import CometChatUIKitSwift

let messageHeader = CometChatMessageHeader()

messageHeader.dateTimeFormatter.otherDay = { timestamp in
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    let formatter = DateFormatter()
    formatter.dateFormat = "MMM d, yyyy"
    return "Last seen on " + formatter.string(from: date)
}
```

### Available Formatters

| Formatter   | Purpose                    | Default Format        |
| ----------- | -------------------------- | --------------------- |
| `time`      | Standard time display      | `h:mm a`              |
| `today`     | Last seen today            | `Today at h:mm a`     |
| `yesterday` | Last seen yesterday        | `Yesterday at h:mm a` |
| `lastweek`  | Last seen within last week | Day name              |
| `otherDay`  | Last seen older dates      | `MMM d, yyyy`         |

***

## Common Patterns

### Hide call buttons

```swift lines theme={null}
let messageHeader = CometChatMessageHeader()
messageHeader.set(user: user)
messageHeader.hideVideoCallButton = true
messageHeader.hideVoiceCallButton = true
```

### Custom back button action

```swift lines theme={null}
let messageHeader = CometChatMessageHeader()
messageHeader.set(user: user)

messageHeader.set(onBack: { [weak self] in
    // Custom navigation logic
    self?.dismiss(animated: true)
})
```

### Custom subtitle with typing indicator

```swift lines theme={null}
let messageHeader = CometChatMessageHeader()
messageHeader.set(user: user)

messageHeader.set(subtitleView: { user, group in
    let label = UILabel()
    label.font = UIFont.systemFont(ofSize: 12)
    
    if let user = user {
        label.text = user.status == .online ? "Online" : "Offline"
        label.textColor = user.status == .online ? .systemGreen : .secondaryLabel
    }
    
    return label
})
```

### Minimal header

```swift lines theme={null}
let messageHeader = CometChatMessageHeader()
messageHeader.set(user: user)
messageHeader.hideBackButton = true
messageHeader.hideUserStatus = true
messageHeader.hideVideoCallButton = true
messageHeader.hideVoiceCallButton = true
```

***

## Related Components

* [Messages](/docs/ui-kit/ios/message-list) - Parent component containing MessageHeader
* [Message List](/docs/ui-kit/ios/message-list) - Display messages in a conversation
* [Message Composer](/docs/ui-kit/ios/message-composer) - Send messages in a conversation
* [Conversations](/docs/ui-kit/ios/conversations) - Navigate back to conversation list


# Message List
Source: https://www.cometchat.com/docs/ui-kit/ios/message-list

Display CometChat iOS UI Kit messages with text, media, reactions, threads, real-time updates, filters, and message callbacks.

The `CometChatMessageList` component displays a scrollable list of messages in a conversation. It supports text messages, media messages, reactions, threads, and real-time updates for new messages, edits, and deletions.

<Frame>
  <img alt="CometChatMessageList showing a scrollable list of chat messages with text bubbles, timestamps, and read receipts in a conversation view" />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatMessageList",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "description": "Displays a scrollable list of messages in a conversation with real-time updates for new messages, edits, deletions, reactions, and typing indicators.",
    "inherits": "UIViewController",
    "primaryOutput": {
      "callback": "onMessageClick",
      "type": "(BaseMessage) -> Void"
    },
    "props": {
      "data": {
        "messagesRequestBuilder": {
          "type": "MessagesRequest.MessageRequestBuilder?",
          "default": "nil",
          "note": "Custom request builder for filtering messages"
        },
        "reactionsRequestBuilder": {
          "type": "ReactionsRequest.ReactionsRequestBuilder?",
          "default": "nil",
          "note": "Custom request builder for fetching reactions"
        }
      },
      "callbacks": {
        "onThreadRepliesClick": "(BaseMessage, MessageTemplate) -> Void",
        "onReactionClick": "(ReactionCount, BaseMessage?) -> Void",
        "onReactionListItemClick": "(MessageReaction, BaseMessage) -> Void",
        "onError": "(CometChatException) -> Void",
        "onEmpty": "() -> Void",
        "onLoad": "([BaseMessage]) -> Void"
      },
      "visibility": {
        "hideAvatar": { "type": "Bool", "default": false },
        "hideReceipts": { "type": "Bool", "default": false },
        "hideDateSeparator": { "type": "Bool", "default": false },
        "hideHeaderView": { "type": "Bool", "default": false },
        "hideFooterView": { "type": "Bool", "default": false },
        "hideReactionOption": { "type": "Bool", "default": false },
        "hideReplyInThreadOption": { "type": "Bool", "default": false },
        "hideEditMessageOption": { "type": "Bool", "default": false },
        "hideDeleteMessageOption": { "type": "Bool", "default": false },
        "hideCopyMessageOption": { "type": "Bool", "default": false },
        "hideMessageInfoOption": { "type": "Bool", "default": false },
        "hideTranslateMessageOption": { "type": "Bool", "default": false },
        "hideMessagePrivatelyOption": { "type": "Bool", "default": false },
        "hideGroupActionMessages": { "type": "Bool", "default": false },
        "hideNewMessageIndicator": { "type": "Bool", "default": false },
        "hideEmptyView": { "type": "Bool", "default": false },
        "hideErrorView": { "type": "Bool", "default": false },
        "hideLoadingView": { "type": "Bool", "default": false }
      },
      "sound": {
        "disableSoundForMessages": { "type": "Bool", "default": false }
      },
      "behavior": {
        "scrollToBottomOnNewMessages": { "type": "Bool", "default": true },
        "startFromUnreadMessages": { "type": "Bool", "default": false },
        "showMarkAsUnreadOption": { "type": "Bool", "default": false },
        "messageAlignment": { "type": "MessageAlignment", "default": ".standard" }
      },
      "viewSlots": {
        "headerView": "() -> UIView",
        "footerView": "() -> UIView",
        "emptyStateView": "() -> UIView",
        "errorStateView": "() -> UIView",
        "loadingStateView": "() -> UIView",
        "newMessageIndicatorView": "() -> UIView"
      },
      "formatting": {
        "datePattern": "(Int?) -> String",
        "timePattern": "(Int) -> String",
        "dateSeparatorPattern": "(Int?) -> String",
        "textFormatters": "[CometChatTextFormatter]"
      }
    },
    "events": [],
    "sdkListeners": [
      "onMessageReceived",
      "onMessageEdited",
      "onMessageDeleted",
      "onTypingStarted",
      "onTypingEnded",
      "onMessageReactionAdded",
      "onMessageReactionRemoved"
    ],
    "compositionExample": {
      "description": "MessageList is typically used within CometChatMessages alongside MessageHeader and MessageComposer",
      "components": ["CometChatMessageHeader", "CometChatMessageList", "CometChatMessageComposer"],
      "flow": "User views messages → types in composer → sends message → MessageList updates"
    },
    "types": {
      "BaseMessage": {
        "id": "Int",
        "sender": "User?",
        "receiver": "AppEntity?",
        "sentAt": "Int",
        "type": "String",
        "category": "String"
      },
      "MessageAlignment": {
        "standard": "Outgoing messages on right, incoming on left",
        "left": "All messages aligned to left"
      }
    }
  }
  ```
</Accordion>

| Field     | Value                  |
| --------- | ---------------------- |
| Component | `CometChatMessageList` |
| Package   | `CometChatUIKitSwift`  |
| Inherits  | `UIViewController`     |

***

## Where It Fits

`CometChatMessageList` is the core component for displaying messages in a chat. It's typically used within `CometChatMessages` alongside `CometChatMessageHeader` and `CometChatMessageComposer`.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class ChatViewController: UIViewController {
    
    private var messageList: CometChatMessageList!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupMessageList()
    }
    
    private func setupMessageList(for user: User) {
        messageList = CometChatMessageList()
        messageList.set(user: user)
        
        // Handle thread replies
        messageList.set(onThreadRepliesClick: { [weak self] message, template in
            self?.openThreadView(for: message)
        })
        
        // Handle reactions
        messageList.set(onReactionClick: { [weak self] reactionCount, message in
            guard let message = message else { return }
            self?.showReactionDetails(reactionCount, for: message)
        })
        
        addChild(messageList)
        view.addSubview(messageList.view)
        messageList.didMove(toParent: self)
    }
    
    private func openThreadView(for message: BaseMessage) {
        let threadMessages = CometChatMessages()
        threadMessages.set(user: message.sender as? User)
        threadMessages.set(parentMessage: message)
        navigationController?.pushViewController(threadMessages, animated: true)
    }
    
    private func showReactionDetails(_ reactionCount: ReactionCount, for message: BaseMessage) {
        // Show reaction details
    }
}
```

<Frame>
  <img alt="CometChatMessageList integrated within a chat view controller showing message bubbles with thread replies and reaction handling" />
</Frame>

***

## Minimal Render

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()
messageList.set(user: user)
```

<Frame>
  <img alt="CometChatMessageList showing minimal render with default configuration displaying messages for a user conversation" />
</Frame>

***

## Filtering

Use `MessagesRequest.MessageRequestBuilder` to filter which messages appear in the list. The builder pattern allows chaining multiple filter conditions.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

// Create a custom request builder
let messageRequestBuilder = MessagesRequest.MessageRequestBuilder()
    .set(uid: "user-id")
    .set(limit: 30)
    .set(types: ["text", "image", "video"])

let messageList = CometChatMessageList()
messageList.set(user: user)
messageList.set(messagesRequestBuilder: messageRequestBuilder)
```

### Filter Recipes

| Recipe                   | Code                                               |
| ------------------------ | -------------------------------------------------- |
| Text messages only       | `.set(types: ["text"])`                            |
| Media messages only      | `.set(types: ["image", "video", "audio", "file"])` |
| Search by keyword        | `.set(searchKeyword: "hello")`                     |
| Limit results            | `.set(limit: 50)`                                  |
| Messages after timestamp | `.set(timestamp: 1234567890)`                      |
| Hide deleted messages    | `.hideDeletedMessages(true)`                       |
| Specific categories      | `.set(categories: ["message", "custom"])`          |

***

## Multiple Attachments

Media messages that carry multiple attachments render with dedicated per-type bubbles — a media grid for images/videos, playback rows for audio files, and a connected card stack for documents (see [Message Bubble Styling](/docs/ui-kit/ios/message-bubble-styling) for their styles).

<Frame>
  <img alt="Message list rendering a multi-attachment media message as a media grid of images with a +N overflow badge, shown for both incoming and outgoing messages" />
</Frame>

When a single composer send was split into several messages (one per attachment type), the list **groups them visually as one batch**: the avatar and sender name appear only on the first message of the batch, the timestamp and read receipt only on the last, while reactions remain per message. Grouping is driven by the batch metadata (`batchId`, `batchIndex`, `batchSize`) the composer stamps on each message.

The behavior is on by default and can be toggled:

```swift theme={null}
let messageList = CometChatMessageList()
messageList.set(enableMultipleAttachments: true)   // default
```

Setting it to `false` renders every media message with the classic single-attachment bubbles instead.

***

## Actions and Events

### Callback Props

#### onThreadRepliesClick

Fires when a user taps on the thread indicator of a message bubble.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

messageList.set(onThreadRepliesClick: { [weak self] message, template in
    guard let self = self else { return }
    
    let threadMessages = CometChatMessages()
    if let user = message.sender as? User {
        threadMessages.set(user: user)
    }
    threadMessages.set(parentMessage: message)
    self.navigationController?.pushViewController(threadMessages, animated: true)
})
```

#### onReactionClick

Fires when a user taps on a reaction on a message bubble.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

messageList.set(onReactionClick: { [weak self] reactionCount, message in
    guard let self = self, let message = message else { return }
    print("Reaction \(reactionCount.reaction ?? "") tapped on message \(message.id)")
})
```

#### onReactionListItemClick

Fires when a user taps on a specific reaction in the reaction list.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

messageList.set(onReactionListItemClick: { [weak self] messageReaction, message in
    guard let self = self else { return }
    print("User \(messageReaction.reactedBy?.name ?? "") reacted with \(messageReaction.reaction)")
})
```

#### onError

Fires when an error occurs while loading messages.

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

messageList.set(onError: { error in
    print("Error loading messages: \(error.errorDescription)")
})
```

#### onEmpty

Fires when the message list is empty.

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

messageList.set(onEmpty: {
    print("No messages found")
})
```

#### onLoad

Fires when messages are successfully loaded.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

messageList.set(onLoad: { messages in
    print("Loaded \(messages.count) messages")
})
```

### Actions Reference

| Method                          | Description                                 | Example               |
| ------------------------------- | ------------------------------------------- | --------------------- |
| `set(onThreadRepliesClick:)`    | Triggered when thread indicator is tapped   | Open thread view      |
| `set(onReactionClick:)`         | Triggered when a reaction is tapped         | Show reaction details |
| `set(onReactionListItemClick:)` | Triggered when reaction list item is tapped | Show who reacted      |
| `set(onError:)`                 | Triggered when an error occurs              | Show error alert      |
| `set(onEmpty:)`                 | Triggered when list is empty                | Show empty state      |
| `set(onLoad:)`                  | Triggered when messages load                | Analytics tracking    |
| `scrollToBottom(isAnimated:)`   | Scrolls to the bottom of the list           | Navigate to latest    |
| `goToMessage(withId:)`          | Scrolls to a specific message               | Jump to message       |

### SDK Events (Real-Time, Automatic)

| SDK Listener               | Internal behavior                   |
| -------------------------- | ----------------------------------- |
| `onMessageReceived`        | Adds new message to the list        |
| `onMessageEdited`          | Updates the edited message in place |
| `onMessageDeleted`         | Removes or marks message as deleted |
| `onTypingStarted`          | Shows typing indicator              |
| `onTypingEnded`            | Hides typing indicator              |
| `onMessageReactionAdded`   | Updates reaction count on message   |
| `onMessageReactionRemoved` | Updates reaction count on message   |

***

## Data Manipulation Methods

Programmatically manage messages in the list using these methods.

### add(message:)

Adds a new message to the message list.

```swift lines theme={null}
@discardableResult
public func add(message: BaseMessage) -> Self
```

| Parameter | Type          | Description                    |
| --------- | ------------- | ------------------------------ |
| `message` | `BaseMessage` | The message to add to the list |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

// Add a message programmatically
let textMessage = TextMessage(receiverUid: "user-id", text: "Hello!", receiverType: .user)
messageList.add(message: textMessage)
```

### update(message:)

Updates an existing message in the list.

```swift lines theme={null}
@discardableResult
public func update(message: BaseMessage) -> Self
```

| Parameter | Type          | Description                      |
| --------- | ------------- | -------------------------------- |
| `message` | `BaseMessage` | The message with updated content |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

// Update a message after editing
if let editedMessage = existingMessage as? TextMessage {
    editedMessage.text = "Updated message text"
    messageList.update(message: editedMessage)
}
```

### remove(message:)

Removes a message from the list without deleting it from the server.

```swift lines theme={null}
@discardableResult
public func remove(message: BaseMessage) -> Self
```

| Parameter | Type          | Description                         |
| --------- | ------------- | ----------------------------------- |
| `message` | `BaseMessage` | The message to remove from the list |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

// Remove a message from the UI
messageList.remove(message: messageToRemove)
```

### delete(message:)

Deletes a message from both the list and the server.

```swift lines theme={null}
@discardableResult
public func delete(message: BaseMessage) -> Self
```

| Parameter | Type          | Description           |
| --------- | ------------- | --------------------- |
| `message` | `BaseMessage` | The message to delete |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

// Delete a message permanently
messageList.delete(message: messageToDelete)
```

### clearList()

Removes all messages from the list.

```swift lines theme={null}
@discardableResult
public func clearList() -> Self
```

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Clear all messages from the list
messageList.clearList()
```

### isEmpty()

Checks if the message list is empty.

```swift lines theme={null}
public func isEmpty() -> Bool
```

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Check if list is empty
if messageList.isEmpty() {
    print("No messages in the list")
}
```

***

## Connection Management

Manually control the WebSocket connection for the message list.

### connect()

Establishes the WebSocket connection for real-time updates. Use this when you need to manually reconnect after disconnecting.

```swift lines theme={null}
@discardableResult
public func connect() -> Self
```

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Manually connect to receive real-time updates
messageList.connect()
```

### disconnect()

Disconnects the WebSocket connection. Use this when you want to temporarily stop receiving real-time updates, such as when the view is not visible.

```swift lines theme={null}
@discardableResult
public func disconnect() -> Self
```

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Disconnect when view disappears
override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    messageList.disconnect()
}

// Reconnect when view appears
override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    messageList.connect()
}
```

***

## Custom View Slots

| Slot                      | Signature | Replaces                  |
| ------------------------- | --------- | ------------------------- |
| `headerView`              | `UIView`  | Header above message list |
| `footerView`              | `UIView`  | Footer below message list |
| `emptyView`               | `UIView`  | Empty state display       |
| `errorView`               | `UIView`  | Error state display       |
| `loadingView`             | `UIView`  | Loading state display     |
| `newMessageIndicatorView` | `UIView`  | New message indicator     |

### set(headerView:)

Replaces the default header with a custom view.

|           |                                   |
| --------- | --------------------------------- |
| Signature | `(UIView) -> Self`                |
| Replaces  | Default header above message list |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let headerView = UIView()
headerView.backgroundColor = UIColor.systemGray6

let label = UILabel()
label.text = "Pinned Messages"
label.font = UIFont.systemFont(ofSize: 14, weight: .medium)
label.textColor = UIColor.secondaryLabel
headerView.addSubview(label)

messageList.set(headerView: headerView)
```

### set(footerView:)

Replaces the default footer with a custom view.

|           |                                   |
| --------- | --------------------------------- |
| Signature | `(UIView) -> Self`                |
| Replaces  | Default footer below message list |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let footerView = UIView()
footerView.backgroundColor = UIColor.systemGray6

let quickRepliesStack = UIStackView()
quickRepliesStack.axis = .horizontal
quickRepliesStack.spacing = 8

let replies = ["👍", "Thanks!", "Got it"]
for reply in replies {
    let button = UIButton(type: .system)
    button.setTitle(reply, for: .normal)
    button.backgroundColor = UIColor.systemBackground
    button.layer.cornerRadius = 16
    quickRepliesStack.addArrangedSubview(button)
}

footerView.addSubview(quickRepliesStack)
messageList.set(footerView: footerView)
```

### set(emptyView:)

Replaces the default empty state view with a custom view.

|           |                                            |
| --------- | ------------------------------------------ |
| Signature | `(UIView) -> Self`                         |
| Replaces  | Default empty state when no messages exist |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let emptyView = UIView()
let imageView = UIImageView(image: UIImage(systemName: "bubble.left.and.bubble.right"))
imageView.tintColor = UIColor.tertiaryLabel

let label = UILabel()
label.text = "No messages yet. Start the conversation!"
label.textColor = UIColor.secondaryLabel
label.textAlignment = .center

emptyView.addSubview(imageView)
emptyView.addSubview(label)

messageList.set(emptyView: emptyView)
```

### set(errorView:)

Replaces the default error state view with a custom view.

|           |                                        |
| --------- | -------------------------------------- |
| Signature | `(UIView) -> Self`                     |
| Replaces  | Default error state when loading fails |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let errorView = UIView()
let errorLabel = UILabel()
errorLabel.text = "Something went wrong!"
errorLabel.textColor = .red
errorLabel.textAlignment = .center

let retryButton = UIButton(type: .system)
retryButton.setTitle("Retry", for: .normal)

errorView.addSubview(errorLabel)
errorView.addSubview(retryButton)

messageList.set(errorView: errorView)
```

### set(loadingView:)

Replaces the default loading indicator with a custom view.

|           |                           |
| --------- | ------------------------- |
| Signature | `(UIView) -> Self`        |
| Replaces  | Default loading indicator |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let loadingView = UIActivityIndicatorView(style: .large)
loadingView.color = UIColor.systemBlue
loadingView.startAnimating()

messageList.set(loadingView: loadingView)
```

### set(newMessageIndicatorView:)

Replaces the default new message indicator with a custom view.

|           |                               |
| --------- | ----------------------------- |
| Signature | `(UIView) -> Self`            |
| Replaces  | Default new message indicator |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let newMessageIndicatorView = NewUnreadMessageIndicator()
messageList.set(newMessageIndicatorView: newMessageIndicatorView)

class NewUnreadMessageIndicator: UIView {
    
    private let label: UILabel = {
        let label = UILabel()
        label.text = "New Messages ↓"
        label.textColor = .white
        label.font = UIFont.systemFont(ofSize: 14, weight: .medium)
        label.textAlignment = .center
        return label
    }()
    
    override init(frame: CGRect) {
        super.init(frame: frame)
        backgroundColor = UIColor.systemBlue
        layer.cornerRadius = 16
        
        addSubview(label)
        label.translatesAutoresizingMaskIntoConstraints = false
        NSLayoutConstraint.activate([
            label.centerXAnchor.constraint(equalTo: centerXAnchor),
            label.centerYAnchor.constraint(equalTo: centerYAnchor)
        ])
    }
    
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
}
```

***

## Text Formatters

Customize how text is displayed in messages using text formatters.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let myCustomTextFormatter = MyCustomTextFormatter(trackingCharacter: "#")

let cometChatMessages = CometChatMessages()
    .set(user: user)
    .set(textFormatter: [myCustomTextFormatter])
```

### set(textFormatters:)

Sets custom text formatters for message text display.

```swift lines theme={null}
@discardableResult
public func set(textFormatters: [CometChatTextFormatter]) -> Self
```

| Parameter        | Type                       | Description                       |
| ---------------- | -------------------------- | --------------------------------- |
| `textFormatters` | `[CometChatTextFormatter]` | Array of text formatters to apply |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let hashtagFormatter = HashtagTextFormatter(trackingCharacter: "#")
let mentionFormatter = MentionTextFormatter(trackingCharacter: "@")

messageList.set(textFormatters: [hashtagFormatter, mentionFormatter])
```

### setMentionAllLabel(*:*:)

Customizes the label displayed for @all mentions.

```swift lines theme={null}
@discardableResult
public func setMentionAllLabel(_ title: String, _ subtitle: String) -> Self
```

| Parameter  | Type     | Description                       |
| ---------- | -------- | --------------------------------- |
| `title`    | `String` | The title for the @all mention    |
| `subtitle` | `String` | The subtitle for the @all mention |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Customize the @all mention label
messageList.setMentionAllLabel("Everyone", "Notify all members")
```

You can create a custom text formatter:

```swift lines theme={null}
import Foundation
import CometChatSDK
import CometChatUIKitSwift

class MyCustomTextFormatter: CometChatTextFormatter {
    
    override func getRegex() -> String {
        return "(\\bsure\\b)"
    }

    override func getTrackingCharacter() -> Character {
        return "#"
    }

    override func search(string: String, suggestedItems: ((_: [SuggestionItem]) -> ())? = nil) {
        // This function would call an API or perform a local search
    }

    override func onScrollToBottom(suggestionItemList: [SuggestionItem], listItem: ((_: [SuggestionItem]) -> ())?) {
        // This function would call the next page of an API
    }

    override func onItemClick(suggestedItem: SuggestionItem, user: User?, group: Group?) {
        // Handle clicked item
    }

    override func handlePreMessageSend(baseMessage: BaseMessage, suggestionItemList: [SuggestionItem]) {
        // Modify the message before it's sent
    }

    override func prepareMessageString(
        baseMessage: BaseMessage,
        regexString: String,
        alignment: MessageBubbleAlignment = .left,
        formattingType: FormattingType
    ) -> NSAttributedString {
        let attrString = NSMutableAttributedString(string: "SURE")
        if alignment == .left {
            // Received message styling
            attrString.addAttribute(.foregroundColor, value: UIColor.blue, range: NSRange(location: 0, length: attrString.length))
        } else {
            // Sent message styling
            attrString.addAttribute(.foregroundColor, value: UIColor.green, range: NSRange(location: 0, length: attrString.length))
        }
        attrString.addAttribute(.font, value: UIFont.boldSystemFont(ofSize: 18), range: NSRange(location: 0, length: attrString.length))
        return attrString
    }

    override func onTextTapped(baseMessage: BaseMessage, tappedText: String, controller: UIViewController?) {
        // Handle text tap action
    }
}
```

***

## AI Features

Configure AI-powered features for the message list.

### enableSmartReplies

Enables AI-powered smart reply suggestions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.enableSmartReplies = true
```

### enableConversationStarters

Enables AI-powered conversation starter suggestions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.enableConversationStarters = true
```

### enableConversationSummary

Enables AI-powered conversation summary feature.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.enableConversationSummary = true
```

### set(smartRepliesKeywords:)

Sets keywords that trigger smart reply suggestions.

```swift lines theme={null}
@discardableResult
public func set(smartRepliesKeywords: [String]) -> Self
```

| Parameter              | Type       | Description                         |
| ---------------------- | ---------- | ----------------------------------- |
| `smartRepliesKeywords` | `[String]` | Keywords that trigger smart replies |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Set keywords that trigger smart replies
messageList.set(smartRepliesKeywords: ["help", "question", "support"])
```

### set(smartRepliesDelayDuration:)

Sets the delay duration before showing smart reply suggestions.

```swift lines theme={null}
@discardableResult
public func set(smartRepliesDelayDuration: TimeInterval) -> Self
```

| Parameter                   | Type           | Description                                 |
| --------------------------- | -------------- | ------------------------------------------- |
| `smartRepliesDelayDuration` | `TimeInterval` | Delay in seconds before showing suggestions |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

// Set a 2-second delay before showing smart replies
messageList.set(smartRepliesDelayDuration: 2.0)
```

### loadLastAgentConversation

When chatting with an AI agent, this property controls whether the message list loads the most recent existing conversation or starts fresh.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

**Basic usage — just enable the property:**

```swift theme={null}
let messageList = CometChatMessageList()
messageList.set(user: aiAgentUser)
messageList.set(loadLastAgentConversation: true)
```

**Full setup with composer continuation:**

```swift theme={null}
// In your messages view controller:
let messageList = CometChatMessageList()
messageList.set(user: aiAgentUser)
messageList.set(loadLastAgentConversation: true)

let composer = CometChatMessageComposer()
composer.set(user: aiAgentUser)

// Wire the callback so the composer knows which thread to continue
messageList.onLastAgentConversationLoaded = { parentMessageId in
    composer.set(parentMessageId: parentMessageId)
}
```

**Handling "New Chat" vs "Load Previous":**

```swift theme={null}
// Opening from conversations list → loads previous conversation
messageList.set(loadLastAgentConversation: true)

// "New Chat" button → always starts fresh
messageList.set(loadLastAgentConversation: false)

// Chat History → opens specific thread (use parentMessage directly)
messageList.set(user: aiAgentUser, parentMessage: selectedMessage, withParent: true)
```

**Behavior matrix:**

| `loadLastAgentConversation` | Previous conversation exists? | Result                          |
| --------------------------- | ----------------------------- | ------------------------------- |
| `false` (default)           | —                             | Fresh AI greeting + suggestions |
| `true`                      | Yes                           | Loads most recent thread        |
| `true`                      | No                            | Falls back to fresh AI greeting |

***

## Reactions Configuration

Configure how reactions are displayed and behave in the message list.

### reactionsConfiguration

Configuration object for the reactions feature.

|         |                            |
| ------- | -------------------------- |
| Type    | `ReactionsConfiguration`   |
| Default | `ReactionsConfiguration()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let reactionsConfig = ReactionsConfiguration()
reactionsConfig.reactionLimit = 5
reactionsConfig.showReactionCount = true

messageList.reactionsConfiguration = reactionsConfig
```

### reactionListConfiguration

Configuration object for the reaction list display.

|         |                               |
| ------- | ----------------------------- |
| Type    | `ReactionListConfiguration`   |
| Default | `ReactionListConfiguration()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let reactionListConfig = ReactionListConfiguration()
reactionListConfig.showUserNames = true

messageList.reactionListConfiguration = reactionListConfig
```

### quickReactionsConfiguration

Configuration object for quick reactions.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `QuickReactionsConfiguration`   |
| Default | `QuickReactionsConfiguration()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let quickReactionsConfig = QuickReactionsConfiguration()
quickReactionsConfig.quickReactions = ["👍", "❤️", "😂", "😮", "😢"]

messageList.quickReactionsConfiguration = quickReactionsConfig
```

### messageInformationConfiguration

Configuration object for message information display.

|         |                                     |
| ------- | ----------------------------------- |
| Type    | `MessageInformationConfiguration`   |
| Default | `MessageInformationConfiguration()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let messageInfoConfig = MessageInformationConfiguration()
messageInfoConfig.showReadReceipts = true
messageInfoConfig.showDeliveryReceipts = true

messageList.messageInformationConfiguration = messageInfoConfig
```

***

## Styling

### Style Hierarchy

1. Global styles (`CometChatMessageList.style`) apply to all instances
2. Instance styles override global for specific instances

### Global Level Styling

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

// Apply global styles that affect all CometChatMessageList instances
CometChatMessageList.style.backgroundColor = UIColor.systemBackground
CometChatMessageList.style.emptyStateTitleColor = UIColor.label
CometChatMessageList.style.emptyStateTitleFont = UIFont.systemFont(ofSize: 20, weight: .bold)
CometChatMessageList.style.emptyStateSubtitleColor = UIColor.secondaryLabel

// Customize message bubble styles
CometChatMessageList.messageBubbleStyle.outgoing.backgroundColor = UIColor.systemBlue
CometChatMessageList.messageBubbleStyle.incoming.backgroundColor = UIColor.systemGray5
```

### Instance Level Styling

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

// Create a custom style for a specific instance
let messageListStyle = MessageListStyle()
messageListStyle.backgroundColor = UIColor(red: 0.95, green: 0.95, blue: 0.97, alpha: 1.0)
messageListStyle.borderWidth = 0
messageListStyle.borderColor = .clear

let messageList = CometChatMessageList()
messageList.style = messageListStyle
```

<Frame>
  <img alt="CometChatMessageList with custom styling applied showing modified background color and message bubble appearance" />
</Frame>

### Key Style Properties

| Property                             | Type                    | Default                             | Description                      |
| ------------------------------------ | ----------------------- | ----------------------------------- | -------------------------------- |
| `backgroundColor`                    | `UIColor`               | `CometChatTheme.backgroundColor01`  | Background color of the list     |
| `borderWidth`                        | `CGFloat`               | `0`                                 | Border width for the component   |
| `borderColor`                        | `UIColor`               | `.clear`                            | Border color for the component   |
| `cornerRadius`                       | `CometChatCornerStyle?` | `nil`                               | Corner radius for the component  |
| `shimmerGradientColor1`              | `UIColor`               | `CometChatTheme.backgroundColor04`  | First shimmer gradient color     |
| `shimmerGradientColor2`              | `UIColor`               | `CometChatTheme.backgroundColor03`  | Second shimmer gradient color    |
| `emptyStateTitleColor`               | `UIColor`               | `CometChatTheme.textColorPrimary`   | Empty state title color          |
| `emptyStateTitleFont`                | `UIFont`                | `CometChatTypography.Heading3.bold` | Empty state title font           |
| `emptyStateSubtitleColor`            | `UIColor`               | `CometChatTheme.textColorSecondary` | Empty state subtitle color       |
| `emptyStateSubtitleFont`             | `UIFont`                | `CometChatTypography.Body.regular`  | Empty state subtitle font        |
| `errorStateTitleColor`               | `UIColor`               | `CometChatTheme.textColorPrimary`   | Error state title color          |
| `errorStateTitleFont`                | `UIFont`                | `CometChatTypography.Heading3.bold` | Error state title font           |
| `newMessageIndicatorTextColor`       | `UIColor?`              | `nil`                               | New message indicator text color |
| `newMessageIndicatorBackgroundColor` | `UIColor?`              | `nil`                               | New message indicator background |

### Style Properties

#### emojiKeyboardStyle

Customizes the appearance of the emoji keyboard.

|         |                        |
| ------- | ---------------------- |
| Type    | `EmojiKeyboardStyle`   |
| Default | `EmojiKeyboardStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let emojiKeyboardStyle = EmojiKeyboardStyle()
emojiKeyboardStyle.backgroundColor = UIColor.systemBackground
emojiKeyboardStyle.borderColor = UIColor.systemGray4

messageList.emojiKeyboardStyle = emojiKeyboardStyle
```

#### dateSeparatorStyle

Customizes the appearance of date separators between messages.

|         |                        |
| ------- | ---------------------- |
| Type    | `DateSeparatorStyle`   |
| Default | `DateSeparatorStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let dateSeparatorStyle = DateSeparatorStyle()
dateSeparatorStyle.textColor = UIColor.secondaryLabel
dateSeparatorStyle.textFont = UIFont.systemFont(ofSize: 12, weight: .medium)
dateSeparatorStyle.backgroundColor = UIColor.systemGray6

messageList.dateSeparatorStyle = dateSeparatorStyle
```

#### newMessageIndicatorStyle

Customizes the appearance of the new message indicator.

|         |                              |
| ------- | ---------------------------- |
| Type    | `NewMessageIndicatorStyle`   |
| Default | `NewMessageIndicatorStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let newMessageIndicatorStyle = NewMessageIndicatorStyle()
newMessageIndicatorStyle.textColor = UIColor.white
newMessageIndicatorStyle.backgroundColor = UIColor.systemBlue
newMessageIndicatorStyle.cornerRadius = 16

messageList.newMessageIndicatorStyle = newMessageIndicatorStyle
```

#### messageBubbleStyle

Customizes the appearance of message bubbles.

|         |                        |
| ------- | ---------------------- |
| Type    | `MessageBubbleStyle`   |
| Default | `MessageBubbleStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let messageBubbleStyle = MessageBubbleStyle()
messageBubbleStyle.outgoing.backgroundColor = UIColor.systemBlue
messageBubbleStyle.incoming.backgroundColor = UIColor.systemGray5
messageBubbleStyle.outgoing.textColor = UIColor.white
messageBubbleStyle.incoming.textColor = UIColor.label

messageList.messageBubbleStyle = messageBubbleStyle
```

#### actionBubbleStyle

Customizes the appearance of action message bubbles (e.g., group actions).

|         |                       |
| ------- | --------------------- |
| Type    | `ActionBubbleStyle`   |
| Default | `ActionBubbleStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let actionBubbleStyle = ActionBubbleStyle()
actionBubbleStyle.backgroundColor = UIColor.systemGray6
actionBubbleStyle.textColor = UIColor.secondaryLabel
actionBubbleStyle.textFont = UIFont.systemFont(ofSize: 13, weight: .regular)

messageList.actionBubbleStyle = actionBubbleStyle
```

#### callActionBubbleStyle

Customizes the appearance of call action message bubbles.

|         |                           |
| ------- | ------------------------- |
| Type    | `CallActionBubbleStyle`   |
| Default | `CallActionBubbleStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

let callActionBubbleStyle = CallActionBubbleStyle()
callActionBubbleStyle.backgroundColor = UIColor.systemGreen.withAlphaComponent(0.1)
callActionBubbleStyle.iconTintColor = UIColor.systemGreen
callActionBubbleStyle.textColor = UIColor.label

messageList.callActionBubbleStyle = callActionBubbleStyle
```

### Customization Matrix

| What to change   | Where     | Property/API                                     | Example                           |
| ---------------- | --------- | ------------------------------------------------ | --------------------------------- |
| Background color | Style     | `backgroundColor`                                | `UIColor.systemBackground`        |
| Empty state text | Style     | `emptyStateTitleColor`, `emptyStateTitleFont`    | Custom colors and fonts           |
| Error state text | Style     | `errorStateTitleColor`, `errorStateTitleFont`    | Custom colors and fonts           |
| Loading shimmer  | Style     | `shimmerGradientColor1`, `shimmerGradientColor2` | Custom gradient colors            |
| Outgoing bubble  | Style     | `messageBubbleStyle.outgoing`                    | `UIColor.systemBlue`              |
| Incoming bubble  | Style     | `messageBubbleStyle.incoming`                    | `UIColor.systemGray5`             |
| Hide avatars     | Property  | `hideAvatar`                                     | `messageList.hideAvatar = true`   |
| Hide receipts    | Property  | `hideReceipts`                                   | `messageList.hideReceipts = true` |
| Custom header    | View Slot | `set(headerView:)`                               | See Custom View Slots section     |

***

## Props

All props are optional. Sorted alphabetically.

### actionBubbleStyle

Customizes the appearance of action message bubbles.

|         |                       |
| ------- | --------------------- |
| Type    | `ActionBubbleStyle`   |
| Default | `ActionBubbleStyle()` |

### callActionBubbleStyle

Customizes the appearance of call action message bubbles.

|         |                           |
| ------- | ------------------------- |
| Type    | `CallActionBubbleStyle`   |
| Default | `CallActionBubbleStyle()` |

### dateSeparatorStyle

Customizes the appearance of date separators.

|         |                        |
| ------- | ---------------------- |
| Type    | `DateSeparatorStyle`   |
| Default | `DateSeparatorStyle()` |

### disableSoundForMessages

Disables notification sounds for new messages.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### disableSwipeToReply

Disables the swipe-to-reply gesture on messages.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.disableSwipeToReply = true
```

### emojiKeyboardStyle

Customizes the appearance of the emoji keyboard.

|         |                        |
| ------- | ---------------------- |
| Type    | `EmojiKeyboardStyle`   |
| Default | `EmojiKeyboardStyle()` |

### emptySubtitleText

Custom subtitle text for the empty state view.

|         |          |
| ------- | -------- |
| Type    | `String` |
| Default | `""`     |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.emptySubtitleText = "Send a message to start the conversation"
```

### emptyTitleText

Custom title text for the empty state view.

|         |                 |
| ------- | --------------- |
| Type    | `String`        |
| Default | `"No Messages"` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.emptyTitleText = "No messages yet"
```

### enableConversationStarters

Enables AI-powered conversation starter suggestions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### enableConversationSummary

Enables AI-powered conversation summary feature.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### enableSmartReplies

Enables AI-powered smart reply suggestions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### errorSubtitleText

Custom subtitle text for the error state view.

|         |          |
| ------- | -------- |
| Type    | `String` |
| Default | `""`     |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.errorSubtitleText = "Please check your connection and try again"
```

### errorTitleText

Custom title text for the error state view.

|         |                          |
| ------- | ------------------------ |
| Type    | `String`                 |
| Default | `"Something went wrong"` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.errorTitleText = "Unable to load messages"
```

### hideAvatar

Hides the sender's avatar in message bubbles.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideBubbleHeader

Hides the header section of message bubbles (sender name, timestamp).

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.hideBubbleHeader = true
```

### hideCopyMessageOption

Hides the copy message option in message actions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideDateSeparator

Hides the date separator between messages.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideDeleteMessageOption

Hides the delete message option in message actions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideEditMessageOption

Hides the edit message option in message actions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideEmptyView

Hides the empty state view when no messages are available.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideErrorView

Hides the error view when an error occurs.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideFlagMessageOption

Hides the flag/report message option in message actions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.hideFlagMessageOption = true
```

### hideFooterView

Hides the footer view of the message list.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideGroupActionMessages

Hides group action messages (join/leave notifications).

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideHeaderView

Hides the header view of the message list.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideLoadingView

Hides the loading view when fetching messages.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideMessageInfoOption

Hides the message info option in message actions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideMessagePrivatelyOption

Hides the option to message privately.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideNewMessageIndicator

Hides the new message indicator.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideReactionOption

Hides the reaction option on messages.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideReceipts

Hides message read receipts (ticks).

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideReplyInThreadOption

Hides the reply in thread option.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideReplyMessageOption

Hides the reply to message option in message actions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.hideReplyMessageOption = true
```

### hideShareMessageOption

Hides the share message option in message actions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()
messageList.hideShareMessageOption = true
```

### hideTranslateMessageOption

Hides the message translation option.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### messageAlignment

Sets the alignment of messages in the list.

|         |                    |
| ------- | ------------------ |
| Type    | `MessageAlignment` |
| Default | `.standard`        |

### messageBubbleStyle

Customizes the appearance of message bubbles.

|         |                        |
| ------- | ---------------------- |
| Type    | `MessageBubbleStyle`   |
| Default | `MessageBubbleStyle()` |

### messageInformationConfiguration

Configuration object for message information display.

|         |                                     |
| ------- | ----------------------------------- |
| Type    | `MessageInformationConfiguration`   |
| Default | `MessageInformationConfiguration()` |

### messagesRequestBuilder

Custom request builder for filtering messages.

|         |                                          |
| ------- | ---------------------------------------- |
| Type    | `MessagesRequest.MessageRequestBuilder?` |
| Default | `nil`                                    |

### newMessageIndicatorStyle

Customizes the appearance of the new message indicator.

|         |                              |
| ------- | ---------------------------- |
| Type    | `NewMessageIndicatorStyle`   |
| Default | `NewMessageIndicatorStyle()` |

### quickReactionsConfiguration

Configuration object for quick reactions.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `QuickReactionsConfiguration`   |
| Default | `QuickReactionsConfiguration()` |

### reactionsConfiguration

Configuration object for the reactions feature.

|         |                            |
| ------- | -------------------------- |
| Type    | `ReactionsConfiguration`   |
| Default | `ReactionsConfiguration()` |

### reactionListConfiguration

Configuration object for the reaction list display.

|         |                               |
| ------- | ----------------------------- |
| Type    | `ReactionListConfiguration`   |
| Default | `ReactionListConfiguration()` |

### reactionsRequestBuilder

Custom request builder for fetching reactions.

|         |                                             |
| ------- | ------------------------------------------- |
| Type    | `ReactionsRequest.ReactionsRequestBuilder?` |
| Default | `nil`                                       |

### scrollToBottomOnNewMessages

Automatically scrolls to bottom when new messages arrive.

|         |        |
| ------- | ------ |
| Type    | `Bool` |
| Default | `true` |

### showMarkAsUnreadOption

Shows the "Mark as unread" option in message actions.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### startFromUnreadMessages

Starts the message list from the first unread message.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### textFormatters

Array of text formatters for customizing message text display.

|         |                            |
| ------- | -------------------------- |
| Type    | `[CometChatTextFormatter]` |
| Default | `[]`                       |

***

## Events

The MessageList component provides callback events for handling state changes.

### set(onLoad:)

Fires when messages are successfully loaded.

```swift lines theme={null}
@discardableResult
public func set(onLoad: @escaping ([BaseMessage]) -> Void) -> Self
```

| Parameter | Type                      | Description                   |
| --------- | ------------------------- | ----------------------------- |
| `onLoad`  | `([BaseMessage]) -> Void` | Callback with loaded messages |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let messageList = CometChatMessageList()

messageList.set(onLoad: { messages in
    print("Loaded \(messages.count) messages")
    // Perform analytics tracking or other actions
})
```

### set(onEmpty:)

Fires when the message list is empty.

```swift lines theme={null}
@discardableResult
public func set(onEmpty: @escaping () -> Void) -> Self
```

| Parameter | Type         | Description                 |
| --------- | ------------ | --------------------------- |
| `onEmpty` | `() -> Void` | Callback when list is empty |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

messageList.set(onEmpty: {
    print("No messages found")
    // Show custom empty state or prompt user to start conversation
})
```

***

## Date Time Formatter

Customize how timestamps appear in the message list using the `CometChatDateTimeFormatter`.

### Global Level Formatting

```swift lines theme={null}
import CometChatUIKitSwift

// Customize time format
CometChatMessageList.dateTimeFormatter.time = { timestamp in
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    let formatter = DateFormatter()
    formatter.dateFormat = "HH:mm"
    return formatter.string(from: date)
}

// Customize today format
CometChatMessageList.dateTimeFormatter.today = { timestamp in
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    let formatter = DateFormatter()
    formatter.dateFormat = "h:mm a"
    return "Today • " + formatter.string(from: date)
}

// Customize older dates format
CometChatMessageList.dateTimeFormatter.otherDay = { timestamp in
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    let formatter = DateFormatter()
    formatter.dateFormat = "dd MMM yyyy"
    return formatter.string(from: date)
}
```

### Instance Level Formatting

#### set(datePattern:)

Sets a custom date pattern for message timestamps.

```swift lines theme={null}
@discardableResult
public func set(datePattern: @escaping (Int?) -> String) -> Self
```

| Parameter     | Type               | Description                                   |
| ------------- | ------------------ | --------------------------------------------- |
| `datePattern` | `(Int?) -> String` | Closure that formats timestamp to date string |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

messageList.set(datePattern: { timestamp in
    guard let timestamp = timestamp else { return "" }
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp / 1000))
    let formatter = DateFormatter()
    formatter.dateFormat = "dd-MM-yyyy"
    return formatter.string(from: date)
})
```

#### set(timePattern:)

Sets a custom time pattern for message timestamps.

```swift lines theme={null}
@discardableResult
public func set(timePattern: @escaping (Int) -> String) -> Self
```

| Parameter     | Type              | Description                                   |
| ------------- | ----------------- | --------------------------------------------- |
| `timePattern` | `(Int) -> String` | Closure that formats timestamp to time string |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

messageList.set(timePattern: { timestamp in
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    let formatter = DateFormatter()
    formatter.dateFormat = "HH:mm"
    return formatter.string(from: date)
})
```

#### set(dateSeparatorPattern:)

Sets a custom pattern for date separators between messages.

```swift lines theme={null}
@discardableResult
public func set(dateSeparatorPattern: @escaping (Int?) -> String) -> Self
```

| Parameter              | Type               | Description                                             |
| ---------------------- | ------------------ | ------------------------------------------------------- |
| `dateSeparatorPattern` | `(Int?) -> String` | Closure that formats timestamp to date separator string |

```swift lines theme={null}
import CometChatUIKitSwift

let messageList = CometChatMessageList()

messageList.set(dateSeparatorPattern: { timestamp in
    guard let timestamp = timestamp else { return "" }
    let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
    
    if Calendar.current.isDateInToday(date) {
        return "Today"
    } else if Calendar.current.isDateInYesterday(date) {
        return "Yesterday"
    } else {
        let formatter = DateFormatter()
        formatter.dateFormat = "EEEE, MMM d"
        return formatter.string(from: date)
    }
})
```

### Available Formatters

| Formatter              | Purpose                         | Default Format |
| ---------------------- | ------------------------------- | -------------- |
| `time`                 | Standard time display           | `h:mm a`       |
| `today`                | Messages sent today             | `Today`        |
| `yesterday`            | Messages from yesterday         | `Yesterday`    |
| `lastweek`             | Messages within last week       | Day name       |
| `otherDay`             | Older messages                  | `MMM d, yyyy`  |
| `datePattern`          | Custom date pattern             | Configurable   |
| `timePattern`          | Custom time pattern             | Configurable   |
| `dateSeparatorPattern` | Date separator between messages | Configurable   |

***

## Common Patterns

### Hide message options

```swift lines theme={null}
let messageList = CometChatMessageList()
messageList.set(user: user)
messageList.hideReplyInThreadOption = true
messageList.hideEditMessageOption = true
messageList.hideDeleteMessageOption = true
messageList.hideReactionOption = true
messageList.hideCopyMessageOption = true
```

### Disable sounds

```swift lines theme={null}
let messageList = CometChatMessageList()
messageList.set(user: user)
messageList.disableSoundForMessages = true
```

### Custom empty state

```swift lines theme={null}
let messageList = CometChatMessageList()
messageList.set(user: user)

messageList.set(emptyStateView: {
    let label = UILabel()
    label.text = "Start a conversation!"
    label.textAlignment = .center
    label.textColor = .secondaryLabel
    return label
})
```

### Scroll to bottom on new messages

```swift lines theme={null}
let messageList = CometChatMessageList()
messageList.set(user: user)
messageList.scrollToBottomOnNewMessages = true
```

### Hide UI elements

```swift lines theme={null}
let messageList = CometChatMessageList()
messageList.set(user: user)
messageList.hideAvatar = true
messageList.hideReceipts = true
messageList.hideDateSeparator = true
messageList.hideHeaderView = true
messageList.hideFooterView = true
```

***

## Related Components

* [Messages](/docs/ui-kit/ios/message-list) - Parent component containing MessageList
* [Message Composer](/docs/ui-kit/ios/message-composer) - Send messages in a conversation
* [Message Header](/docs/ui-kit/ios/message-header) - Display user/group details
* [Message Template](/docs/ui-kit/ios/message-template) - Create custom message bubble templates
* [Threaded Messages](/docs/ui-kit/ios/guide-threaded-messages) - Display threaded conversations


# Message Template
Source: https://www.cometchat.com/docs/ui-kit/ios/message-template

Define CometChat iOS UI Kit message templates with custom bubble structure, content views, header views, reply views, and interactions.

## Overview

A MessageTemplate provides you with the capability to define and customize both the structure and the behavior of the [MessageBubble](/docs/ui-kit/ios/message-bubble-styling). It acts as a schema or design blueprint for creating a variety of message bubble components, allowing you to manage their appearance and interactions within your application effectively and consistently.

***

## Structure

<Frame>
  <img />
</Frame>

The MessageBubble structure can typically be broken down into the following views:

1. **Leading view**: This is where the sender's avatar is displayed. It's typically on the left of the MessageBubble for messages from others and on the right for messages from the current user.

2. **Header view**: This displays the sender's name and is especially useful in group chats where multiple users are sending messages.

3. **Reply view**: This view can be used to extend the MessageBubble with additional elements. It's typically placed above the Content view.

4. **Content view**: This is the core of the MessageBubble where the message content (text, images, videos, etc.) is displayed.

5. **Bottom view**: This view can be used to extend the MessageBubble with additional elements, such as link previews or a 'load more' button for long messages. It's typically placed beneath the Content view.

6. **Thread view**: This is where the thread reply icon and reply counts are displayed. It's located below the footer view.

7. **Footer view**: This is where the timestamp of the message and its delivery or read status are displayed. It's located at the bottom of the MessageBubble.

8. **Status Info view**: This is where the timestamp of the message and its delivery or read status are displayed. It's located inside the MessageBubble just below the content view.

***

## Properties

MessageTemplate provides you with methods that allow you to alter various properties of the MessageBubble. These properties include aspects such as the `type` and `category` of a message, the appearance and behavior of the header, content, and footer sections of the message bubble.

### 1. Type

Using `setType()` you can set the type of CometChatMessage. This will map your MessageTemplate to the corresponding CometChatMessage. You can set the MessageTemplate's Type using the following code snippet:

```swift lines theme={null}
let type = "custom_template" // Replace with your own custom type

// Creating a custom message template
let customMessageTemplate = CometChatMessageTemplate(
    category: category,
    type: type,
    contentView: { message, alignment, controller in
        return UIView() // Replace with your own UI for message list
    },
    bubbleView: nil,
    headerView: nil,
    footerView: nil
) { message, alignment, controller in
    return UIView() // Replace with your own UI for message composer
} options: { message, group, controller in
    return [CometChatMessageOption]() // Replace with your own options
}
```

### 2. Category

Using `.setCategory()` you can set the category of a MessageTemplate. This will create a MessageTemplate with the specified category and link it with a CometChatMessage of the same category.

Please refer to our guide on [Message Categories](/docs/sdk/ios/message-structure-and-hierarchy) for a deeper understanding of message categories.

```swift lines theme={null}
let category = "custom_category" // Replace with your own category

// Creating a custom message template
// You can also set UI for bubbleView, headerView and footerView instead of nil
let customMessageTemplate = CometChatMessageTemplate(
    category: category,
    type: type,
    contentView: { message, alignment, controller in
        return UIView() // Replace with your own UI for message list
    },
    bubbleView: nil,
    headerView: nil,
    footerView: nil
) { message, alignment, controller in
    return UIView() // Replace with your own UI for message composer
} options: { message, group, controller in
    return [CometChatMessageOption]() // Replace with your own options
}
```

### 3. Header View

The `template.headerView` method allows you to assign a custom header view to the MessageBubble. By default, it is configured to display the sender's name.

```swift lines theme={null}
var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

for (index, template) in allTemplates.enumerated() {
    var template = template
    template.headerView = { (baseMessage: BaseMessage?, bubbleAlignment: MessageBubbleAlignment, viewController: UIViewController?) -> (UIView)? in
        return UIView()
    }
}
```

### 4. Content View

The `template.contentView` method allows you to assign a custom content view to the MessageBubble. By default, it displays the [Text Bubble](/docs/ui-kit/ios/message-bubble-styling#text-bubble), [Image Bubble](/docs/ui-kit/ios/message-bubble-styling#image-bubble), [File Bubble](/docs/ui-kit/ios/message-bubble-styling), [Audio Bubble](/docs/ui-kit/ios/message-bubble-styling#audio-bubble), or [Video Bubble](/docs/ui-kit/ios/message-bubble-styling#video-bubble), depending on the message type.

```swift lines theme={null}
var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

for (index, template) in allTemplates.enumerated() {
    var template = template
    template.contentView = { (baseMessage: BaseMessage?, bubbleAlignment: MessageBubbleAlignment, viewController: UIViewController?) -> (UIView)? in
        return UIView()
    }
}
```

### 5. Footer View

The `template.footerView` method allows you to assign a custom Footer view to the MessageBubble. By default, it displays the receipt and timestamp.

```swift lines theme={null}
var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

for (index, template) in allTemplates.enumerated() {
    var template = template
    template.footerView = { (baseMessage: BaseMessage?, bubbleAlignment: MessageBubbleAlignment, viewController: UIViewController?) -> (UIView)? in
        return UIView()
    }
}
```

### 6. Bottom View

The `template.bottomView` method allows you to assign a custom Bottom view to the MessageBubble. By default, it has buttons such as link previews or a 'load more' button for long messages.

```swift lines theme={null}
var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

for (index, template) in allTemplates.enumerated() {
    var template = template
    template.bottomView = { (baseMessage: BaseMessage?, bubbleAlignment: MessageBubbleAlignment, viewController: UIViewController?) -> (UIView)? in
        return UIView()
    }
}
```

### 7. Bubble View

The `template.bubbleView` method allows you to assign a custom Bubble view to the MessageBubble. By default, headerView, contentView, and footerView together form a message bubble.

```swift lines theme={null}
var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

for (index, template) in allTemplates.enumerated() {
    var template = template
    template.bubbleView = { (baseMessage: BaseMessage?, bubbleAlignment: MessageBubbleAlignment, viewController: UIViewController?) -> (UIView)? in
        return UIView()
    }
}
```

### 8. Options

The `template.options` lets you set the list of actions that a user can perform on a message. This includes actions like reacting to, editing, or deleting a message.

```swift lines theme={null}
var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

for (index, template) in allTemplates.enumerated() {
    var template = template
    template.options = { message, group, controller in
        let loggedInUser = CometChat.getLoggedInUser()
        let options = CometChatUIKit.getDataSource().getMessageOptions(
            loggedInUser: loggedInUser!,
            messageObject: message!,
            controller: controller,
            group: group
        )
        return options
    }
    allTemplates[index] = template
}
```

***

## Customization

Let's dive into how you can use the [properties](#properties) of MessageTemplate to customize an existing template or add a new one to the [MessageList](/docs/ui-kit/ios/message-list) component.

The first step is to fetch the list of existing templates when you want to modify or add to them. This can be done using the `getAllMessageTemplates()` method from the DataSource of the CometChatUIKit class:

```swift lines theme={null}
var messageTemplates: [CometChatMessageTemplate] = CometChatUIKit.getDataSource().getAllMessageTemplates()
```

***

### Existing Templates

You will need to first get the MessageTemplates object for the type of message you want to customize. In this example, we'll customize the TextMessage Bubble. The code snippet to get the Text MessageTemplate is as follows:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    var messageTemplates: [CometChatMessageTemplate] = CometChatUIKit.getDataSource().getAllMessageTemplates()

    for i in 0..<messageTemplates.count {
        if messageTemplates[i].type == "text" && messageTemplates[i].category == "message" {
            // Set your own content view
            messageTemplates[i].contentView = { message, alignment, controller in
                // Create your own content view and return
                return UIView()
            }
            
            // Set your own bubble view
            messageTemplates[i].bubbleView = { message, alignment, controller in
                // Create your own bubble view and return
                return UIView()
            }
        }
    }

    let cometChatMessages = CometChatMessageList()
    cometChatMessages.set(templates: messageTemplates)
    ```
  </Tab>
</Tabs>

You will be using the `CometChatMessageBubble` Component for this example. To apply Template to Messages, you will have to use the [MessageList](/docs/ui-kit/ios/message-list) component.

By utilizing this code snippet, you will retrieve text templates:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Get text message template
    let messageTemplates: CometChatMessageTemplate = CometChatUIKit.getDataSource().getTextMessageTemplate()

    // Configure message list with template
    let messageListConfiguration = MessageListConfiguration()
        .set(templates: [messageTemplates])

    // Apply to CometChatMessages
    let cometChatMessages = CometChatMessages()
        .set(user: user)
        .set(messageListConfiguration: messageListConfiguration)
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

<Note>
  Ensure to pass and present `cometChatMessages`. If a navigation controller is already in use, utilize the pushViewController function instead of directly presenting the view controller.
</Note>

***

#### Header View

The `template.headerView` method of MessageTemplate allows you to add custom views to the header of your message bubbles. In the example below, we will add a custom UIView `custom_header_view` to the header view of every text message in the MessageList.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="custom_header_view">
    ```swift lines theme={null}
    import UIKit
    import CometChatUIKitSwift

    class HeaderViewStyled: UIView {
                
        private let profileImageView: UIImageView = {
            let imageView = UIImageView()
            imageView.layer.cornerRadius = 16
            imageView.clipsToBounds = true
            imageView.translatesAutoresizingMaskIntoConstraints = false
            return imageView
        }()
                
        private let nameLabel: UILabel = {
            let label = UILabel()
            label.font = UIFont.boldSystemFont(ofSize: 14)
            label.textColor = .black
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
                
        private let statusLabel: UILabel = {
            let label = UILabel()
            label.font = UIFont.systemFont(ofSize: 12)
            label.textColor = .systemBlue
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
                
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupView()
        }
                
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
                
        private func setupView() {
            addSubview(profileImageView)
            addSubview(nameLabel)
            addSubview(statusLabel)
                    
            NSLayoutConstraint.activate([
                profileImageView.leadingAnchor.constraint(equalTo: leadingAnchor),
                profileImageView.topAnchor.constraint(equalTo: topAnchor),
                profileImageView.widthAnchor.constraint(equalToConstant: 32),
                profileImageView.heightAnchor.constraint(equalToConstant: 32),
                        
                nameLabel.leadingAnchor.constraint(equalTo: profileImageView.trailingAnchor, constant: 8),
                nameLabel.topAnchor.constraint(equalTo: topAnchor),
                        
                statusLabel.leadingAnchor.constraint(equalTo: nameLabel.trailingAnchor, constant: 4),
                statusLabel.topAnchor.constraint(equalTo: topAnchor),
            ])
        }
                
        func configure(profileImage: UIImage?, name: String, status: String) {
            profileImageView.image = profileImage
            nameLabel.text = name
            statusLabel.text = status
        }
    }
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

    for (index, template) in allTemplates.enumerated() {
        var template = template
        template.headerView = { (baseMessage: BaseMessage?, bubbleAlignment: MessageBubbleAlignment, viewController: UIViewController?) -> (UIView)? in
            let customHeaderView = HeaderViewStyled()
            return customHeaderView
        }
        allTemplates[index] = template
    }

    let cometChatMessages = CometChatMessageList()
    cometChatMessages.set(templates: allTemplates)
    ```
  </Tab>
</Tabs>

<Note>
  Ensure to pass and present `cometChatMessages`. If a navigation controller is already in use, utilize the pushViewController function instead of directly presenting the view controller.
</Note>

***

#### Content View

The `template.contentView` method of MessageTemplate allows you to add a custom view to the content of your message bubbles. In the example below, we will add a custom `custom_message_view_file` to the content view of every text message in the MessageList.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="custom_message_view_file">
    ```swift lines theme={null}
    import UIKit
    import CometChatSDK
    import CometChatUIKitSwift

    class ContentViewStyled: UIView {

        // MARK: - UI Components
        private lazy var productImageView: UIImageView = {
            let imageView = UIImageView()
            imageView.contentMode = .scaleAspectFit
            imageView.clipsToBounds = true
            imageView.layer.cornerRadius = 8
            imageView.translatesAutoresizingMaskIntoConstraints = false
            return imageView
        }()
                
        private lazy var separatorView: UIView = {
            let view = UIView()
            view.backgroundColor = .systemGray6
            view.translatesAutoresizingMaskIntoConstraints = false
            return view
        }()
                
        private lazy var buyNowButton: UIButton = {
            let button = UIButton(type: .system)
            button.setTitle("Buy Now", for: .normal)
            button.setTitleColor(.systemPurple, for: .normal)
            button.titleLabel?.font = UIFont.boldSystemFont(ofSize: 16)
            button.layer.cornerRadius = 8
            button.layer.borderWidth = 1
            button.layer.borderColor = UIColor.systemPurple.cgColor
            button.translatesAutoresizingMaskIntoConstraints = false
            return button
        }()

        // MARK: - Initializer
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupView()
        }

        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }

        // MARK: - Setup View
        private func setupView() {
            backgroundColor = UIColor.systemGray6
            layer.cornerRadius = 12
            layer.masksToBounds = true
                    
            addSubview(productImageView)
            addSubview(separatorView)
            addSubview(buyNowButton)
                    
            setupConstraints()
        }
                
        // MARK: - Constraints
        private func setupConstraints() {
            NSLayoutConstraint.activate([
                productImageView.topAnchor.constraint(equalTo: topAnchor, constant: 16),
                productImageView.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 16),
                productImageView.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -16),
                productImageView.heightAnchor.constraint(equalTo: productImageView.widthAnchor),
                        
                buyNowButton.topAnchor.constraint(equalTo: productImageView.bottomAnchor, constant: 16),
                buyNowButton.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 16),
                buyNowButton.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -16),
                buyNowButton.heightAnchor.constraint(equalToConstant: 44),
                        
                separatorView.heightAnchor.constraint(equalToConstant: 1),
                separatorView.leadingAnchor.constraint(equalTo: leadingAnchor),
                separatorView.trailingAnchor.constraint(equalTo: trailingAnchor),
                separatorView.topAnchor.constraint(equalTo: buyNowButton.bottomAnchor, constant: 16),
                separatorView.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -16),
            ])
        }
                
        // MARK: - Public Methods
        func configure(with image: UIImage) {
            productImageView.image = image
        }
    }
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

    for (index, template) in allTemplates.enumerated() {
        var template = template
        template.contentView = { (baseMessage: BaseMessage?, bubbleAlignment: MessageBubbleAlignment, viewController: UIViewController?) -> (UIView)? in
            let customView = ContentViewStyled()
            return customView
        }
        allTemplates[index] = template
    }

    let cometChatMessages = CometChatMessageList()
    cometChatMessages.set(templates: allTemplates)
    ```
  </Tab>
</Tabs>

<Note>
  Ensure to pass and present `cometChatMessages`. If a navigation controller is already in use, utilize the pushViewController function instead of directly presenting the view controller.
</Note>

***

#### Bottom View

The `template.bottomView` method of MessageTemplate allows you to add a custom button view to your message bubbles. In the example below, we will add a custom UIView `custom_bottom_view_file` to the bottom view of every text message in the MessageList.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="custom_bottom_view_file">
    ```swift lines theme={null}
    import UIKit

    class BottomViewStyled: UIView {
                
        private let warningLabel: UILabel = {
            let label = UILabel()
            label.font = UIFont.systemFont(ofSize: 12)
            label.textColor = .systemRed
            label.text = "According to guidelines you cannot share contact"
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
                
        private let warningImage: UIImageView = {
            let image = UIImageView()
            image.image = UIImage(systemName: "error-alert")
            image.translatesAutoresizingMaskIntoConstraints = false
            return image
        }()
                
        private let warningStack: UIStackView = {
            let stack = UIStackView()
            stack.translatesAutoresizingMaskIntoConstraints = false
            stack.distribution = .fill
            stack.alignment = .center
            stack.axis = .vertical
            stack.spacing = 2
            return stack
        }()
                
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupView()
        }
                
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
                
        private func setupView() {
            backgroundColor = .systemBlue
            layer.cornerRadius = 8
                    
            addSubview(warningStack)
            warningStack.addArrangedSubview(warningImage)
            warningStack.addArrangedSubview(warningLabel)
                    
            NSLayoutConstraint.activate([
                warningStack.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 8),
                warningStack.topAnchor.constraint(equalTo: topAnchor, constant: 4),
                warningStack.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -8),
                warningStack.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -8)
            ])
        }
    }
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

    for (index, template) in allTemplates.enumerated() {
        var template = template
        template.bottomView = { (baseMessage: BaseMessage?, bubbleAlignment: MessageBubbleAlignment, viewController: UIViewController?) -> (UIView)? in
            let customView = BottomViewStyled()
            return customView
        }
        allTemplates[index] = template
    }

    let cometChatMessages = CometChatMessageList()
    cometChatMessages.set(templates: allTemplates)
    ```
  </Tab>
</Tabs>

<Note>
  Ensure to pass and present `cometChatMessages`. If a navigation controller is already in use, utilize the pushViewController function instead of directly presenting the view controller.
</Note>

***

#### Footer View

The `template.footerView` method of MessageTemplate allows you to add a footer view to your message bubbles. In the example below, we will add a custom UIView file `custom_footer_view` to the bottom view of every text message in the MessageList.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="custom_footer_view">
    ```swift lines theme={null}
    import UIKit

    class FooterViewStyled: UIView {
                
        private let reactionsStackView: UIStackView = {
            let stackView = UIStackView()
            stackView.axis = .horizontal
            stackView.spacing = 4
            stackView.translatesAutoresizingMaskIntoConstraints = false
            return stackView
        }()
                
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupView()
        }
                
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
                
        private func setupView() {
            addSubview(reactionsStackView)
                    
            NSLayoutConstraint.activate([
                reactionsStackView.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 8),
                reactionsStackView.topAnchor.constraint(equalTo: topAnchor, constant: 8),
                reactionsStackView.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -8),
                reactionsStackView.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -8)
            ])
        }
                
        func configure(reactions: [UIImage]) {
            reactionsStackView.arrangedSubviews.forEach { $0.removeFromSuperview() }
                    
            for reaction in reactions {
                let imageView = UIImageView(image: reaction)
                imageView.contentMode = .scaleAspectFit
                imageView.translatesAutoresizingMaskIntoConstraints = false
                reactionsStackView.addArrangedSubview(imageView)
            }
        }
    }
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

    for (index, template) in allTemplates.enumerated() {
        var template = template
        template.footerView = { (baseMessage: BaseMessage?, bubbleAlignment: MessageBubbleAlignment, viewController: UIViewController?) -> (UIView)? in
            let customView = FooterViewStyled()
            return customView
        }
        allTemplates[index] = template
    }

    let cometChatMessages = CometChatMessageList()
    cometChatMessages.set(templates: allTemplates)
    ```
  </Tab>
</Tabs>

<Note>
  Ensure to pass and present `cometChatMessages`. If a navigation controller is already in use, utilize the pushViewController function instead of directly presenting the view controller.
</Note>

***

#### Bubble View

The `template.bubbleView` method of MessageTemplate allows you to add a bubble view to your message bubbles. In the example below, we will add a custom UIView `custom_bubble_view` to the bubble view of every text message in the MessageList.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="custom_bubble_view">
    ```swift lines theme={null}
    import UIKit

    class CustomMessageView: UIView {
        
        // MARK: - Subviews
        private let messageLabel: UILabel = {
            let label = UILabel()
            label.textColor = .white
            label.numberOfLines = 0
            label.font = UIFont.systemFont(ofSize: 16)
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
        
        private let timeLabel: UILabel = {
            let label = UILabel()
            label.text = "4:56 pm"
            label.textColor = .gray
            label.font = UIFont.systemFont(ofSize: 12)
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
        
        private let doubleTickImageView: UIImageView = {
            let imageView = UIImageView()
            imageView.image = UIImage(named: "double_tick")
            imageView.contentMode = .scaleAspectFit
            imageView.translatesAutoresizingMaskIntoConstraints = false
            return imageView
        }()
        
        private let bubbleView: UIView = {
            let view = UIView()
            view.backgroundColor = UIColor.systemPurple
            view.layer.cornerRadius = 12
            view.translatesAutoresizingMaskIntoConstraints = false
            return view
        }()
        
        private let timeStackView: UIStackView = {
            let stackView = UIStackView()
            stackView.axis = .horizontal
            stackView.spacing = 4
            stackView.alignment = .center
            stackView.translatesAutoresizingMaskIntoConstraints = false
            return stackView
        }()
        
        // MARK: - Initialization
        init(message: BaseMessage) {
            super.init(frame: .zero)
            
            // Add subviews
            addSubview(bubbleView)
            addSubview(timeStackView)
            bubbleView.addSubview(messageLabel)
            timeStackView.addArrangedSubview(timeLabel)
            timeStackView.addArrangedSubview(doubleTickImageView)
            
            // Constraints for bubble view
            NSLayoutConstraint.activate([
                bubbleView.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 16),
                bubbleView.trailingAnchor.constraint(lessThanOrEqualTo: trailingAnchor, constant: -16),
                bubbleView.topAnchor.constraint(equalTo: topAnchor, constant: 8),
                bubbleView.bottomAnchor.constraint(equalTo: timeStackView.topAnchor, constant: -4),
                
                messageLabel.leadingAnchor.constraint(equalTo: bubbleView.leadingAnchor, constant: 12),
                messageLabel.trailingAnchor.constraint(equalTo: bubbleView.trailingAnchor, constant: -12),
                messageLabel.topAnchor.constraint(equalTo: bubbleView.topAnchor, constant: 8),
                messageLabel.bottomAnchor.constraint(equalTo: bubbleView.bottomAnchor, constant: -8)
            ])
            
            // Constraints for time stack view
            NSLayoutConstraint.activate([
                timeStackView.leadingAnchor.constraint(equalTo: bubbleView.leadingAnchor),
                timeStackView.topAnchor.constraint(equalTo: bubbleView.bottomAnchor, constant: 4),
                timeStackView.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -8)
            ])
            
            NSLayoutConstraint.activate([
                doubleTickImageView.widthAnchor.constraint(equalToConstant: 16),
                doubleTickImageView.heightAnchor.constraint(equalToConstant: 16)
            ])
            
            // Configure with message data
            if let textMessage = message as? TextMessage {
                messageLabel.text = textMessage.text
                var status = "Sent"
                doubleTickImageView.image = UIImage(named: "single-tick")
                
                if textMessage.readAt > 0 {
                    status = "Read"
                    doubleTickImageView.image = UIImage(named: "message-read")
                } else if textMessage.deliveredAt > 0 {
                    status = "Delivered"
                    doubleTickImageView.image = UIImage(named: "double-tick")
                }

                let dateFormatter = DateFormatter()
                dateFormatter.dateFormat = "hh:mm a"
                let time = dateFormatter.string(from: Date(timeIntervalSince1970: TimeInterval(textMessage.sentAt)))

                timeLabel.text = "\(time)"
            }
        }
        
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
    }
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

    for (index, template) in allTemplates.enumerated() {
        var template = template
        template.bubbleView = { (baseMessage: BaseMessage?, bubbleAlignment: MessageBubbleAlignment, viewController: UIViewController?) -> (UIView)? in
            let customBubbleView = CustomBubbleView()
            return customBubbleView
        }
        allTemplates[index] = template
    }

    let cometChatMessages = CometChatMessages()
    cometChatMessages.set(templates: allTemplates)
    ```
  </Tab>
</Tabs>

<Note>
  Ensure to pass and present `cometChatMessages`. If a navigation controller is already in use, utilize the pushViewController function instead of directly presenting the view controller.
</Note>

***

#### Options List

The `template.options` method in the MessageTemplate allows you to customize the options that appear in the action sheet when a message is long-pressed. By default, CometChat UIKit provides a set of options like "Edit", "Share", "Translated message", and "Delete".

However, if you wish to override or modify these options, you can use the `template.options` method and pass a list of `getMessageOptions`. This list of options will replace the default set.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

    for (index, template) in allTemplates.enumerated() {
        var template = template
        template.options = { message, group, controller in
            let loggedInUser = CometChat.getLoggedInUser()
            var options = CometChatUIKit.getDataSource().getMessageOptions(
                loggedInUser: loggedInUser!,
                messageObject: message!,
                controller: controller,
                group: group
            )
            
            for (index, option) in (options ?? []).enumerated() {
                if option.id == "replyInThread" {
                    // Create custom options
                    let forwardOption = CometChatMessageOption(id: "customOptionId", title: "Forward", icon: UIImage(systemName: "chevron.right"))
                    let favoriteOption = CometChatMessageOption(id: "favoriteOptionId", title: "Mark as Favorite", icon: UIImage(systemName: "star"))
                    let deleteOption = CometChatMessageOption(id: "deleteOptionId", title: "Delete", icon: UIImage(systemName: "trash"))

                    options?[index...index] = [forwardOption, favoriteOption, deleteOption]
                }
            }
            return options ?? []
        }
        allTemplates[index] = template
    }

    let cometChatMessages = CometChatMessageList()
    cometChatMessages.set(templates: allTemplates)
    ```
  </Tab>
</Tabs>

<Note>
  Ensure to pass and present `cometChatMessages`. If a navigation controller is already in use, utilize the pushViewController function instead of directly presenting the view controller.
</Note>

***

#### Status Info View

The `template.statusInfoView` method of MessageTemplate enables you to add a status info view to your message bubbles. This is a user-defined component used to display the statusInfo view, which shows the timestamp and read-receipt of the message.

In the example below, we will integrate a custom UIView file named `custom_status_view` into the status info view of every text message in the MessageList.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="custom_status_view">
    ```swift lines theme={null}
    import UIKit
    import CometChatSDK
    import CometChatUIKitSwift

    class StatusInfoView: UIView {
        
        private let timeLabel: UILabel = {
            let label = UILabel()
            label.text = "4:56 pm"
            label.textColor = .gray
            label.font = UIFont.systemFont(ofSize: 12)
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
        
        private let doubleTickImageView: UIImageView = {
            let imageView = UIImageView()
            imageView.image = UIImage(named: "double_tick")
            imageView.contentMode = .scaleAspectFit
            imageView.translatesAutoresizingMaskIntoConstraints = false
            return imageView
        }()
        
        private let timeStackView: UIStackView = {
            let stackView = UIStackView()
            stackView.axis = .horizontal
            stackView.spacing = 4
            stackView.alignment = .center
            stackView.translatesAutoresizingMaskIntoConstraints = false
            return stackView
        }()
        
        // MARK: - Initialization
        init(baseMessage: BaseMessage) {
            super.init(frame: .zero)
            
            // Add subviews
            addSubview(timeStackView)
            timeStackView.addArrangedSubview(timeLabel)
            timeStackView.addArrangedSubview(doubleTickImageView)
            
            // Constraints for time stack view
            NSLayoutConstraint.activate([
                timeStackView.leadingAnchor.constraint(equalTo: leadingAnchor),
                timeStackView.topAnchor.constraint(equalTo: bottomAnchor, constant: 4),
                timeStackView.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -8)
            ])
            
            NSLayoutConstraint.activate([
                doubleTickImageView.widthAnchor.constraint(equalToConstant: 16),
                doubleTickImageView.heightAnchor.constraint(equalToConstant: 16)
            ])
            
            // Configure with message data
            if let textMessage = baseMessage as? TextMessage {
                var status = "Sent"
                doubleTickImageView.image = UIImage(named: "single-tick")
                
                if textMessage.readAt > 0 {
                    status = "Read"
                    doubleTickImageView.image = UIImage(named: "message-read")
                } else if textMessage.deliveredAt > 0 {
                    status = "Delivered"
                    doubleTickImageView.image = UIImage(named: "double-tick")
                }

                let dateFormatter = DateFormatter()
                dateFormatter.dateFormat = "hh:mm a"
                let time = dateFormatter.string(from: Date(timeIntervalSince1970: TimeInterval(textMessage.sentAt)))

                timeLabel.text = "\(time)"
            }
        }
        
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
    }
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    var allTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates()

    for (index, template) in allTemplates.enumerated() {
        var template = template
        template.statusInfoView = { (baseMessage: BaseMessage?, bubbleAlignment: MessageBubbleAlignment, viewController: UIViewController?) -> UIView? in
            if let baseMessage = baseMessage {
                return CustomStatusView(baseMessage: baseMessage)
            }
            return nil
        }
        allTemplates[index] = template
    }

    let cometChatMessages = CometChatMessages()
    cometChatMessages.set(templates: allTemplates)
    ```
  </Tab>
</Tabs>

<Note>
  Ensure to pass and present `cometChatMessages`. If a navigation controller is already in use, utilize the pushViewController function instead of directly presenting the view controller.
</Note>

***

### New Template

Creating an entirely new template for custom messages is one of the powerful features of CometChat's MessageTemplate. To add a new template, you can create a new one and then add it to the list of existing templates.

First, let's see how to send a custom message:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Creating a text template
    let textTemplate = CometChatUIKit.getDataSource().getTextMessageTemplate()

    // Set content view for TextMessage template
    textTemplate.contentView = { message, alignment, controller in
        // Create your own content view and return
        return UIView()
    }

    // Set bubble view for TextMessage template
    textTemplate.bubbleView = { message, alignment, controller in
        // Create your own bubble view and return
        return UIView()
    }

    // Creating an audio template
    let audioTemplate = CometChatUIKit.getDataSource().getAudioMessageTemplate()

    // Set content view for AudioMessage template
    audioTemplate.contentView = { message, alignment, controller in
        // Create your own content view and return
        return UIView()
    }

    // Set bubble view for AudioMessage template
    audioTemplate.bubbleView = { message, alignment, controller in
        // Create your own bubble view and return
        return UIView()
    }

    let type = "custom_template" // Replace with your own custom type
    let category = "custom_category" // Replace with your own category

    // Creating a custom message template
    // You can also set UI for bubbleView, headerView and footerView instead of nil
    let customMessageTemplate = CometChatMessageTemplate(
        category: category,
        type: type,
        contentView: { message, alignment, controller in
            return UIView() // Replace with your own UI for message list
        },
        bubbleView: nil,
        headerView: nil,
        footerView: nil
    ) { message, alignment, controller in
        return UIView() // Replace with your own UI for message composer
    } options: { message, group, controller in
        return [CometChatMessageOption]() // Replace with your own options
    }

    // Custom list of templates
    let messageTypes = [
        textTemplate,
        audioTemplate,
        customMessageTemplate
    ]

    var templates = [(type: String, template: CometChatMessageTemplate)]()
    for template in messageTypes {
        templates.append((type: template.type, template: template))
    }

    // Passing template list to message list
    let messageList = CometChatMessageList()
    messageList.set(templates: templates)
    ```
  </Tab>
</Tabs>

Find the example below:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit

    class CustomBubbleView: UIView {
        
        // MARK: - Subviews
        private let profileImageView: UIImageView = {
            let imageView = UIImageView()
            imageView.contentMode = .scaleAspectFill
            imageView.clipsToBounds = true
            imageView.layer.cornerRadius = 25
            imageView.translatesAutoresizingMaskIntoConstraints = false
            imageView.image = UIImage(named: "profile_placeholder")
            return imageView
        }()
        
        private let nameLabel: UILabel = {
            let label = UILabel()
            label.text = "Safiya Fareena"
            label.textColor = .white
            label.font = UIFont.systemFont(ofSize: 16, weight: .semibold)
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
        
        private let timeLabel: UILabel = {
            let label = UILabel()
            label.text = "4:56 pm"
            label.textColor = .white
            label.font = UIFont.systemFont(ofSize: 12)
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
        
        private let doubleTickImageView: UIImageView = {
            let imageView = UIImageView()
            imageView.contentMode = .scaleAspectFit
            imageView.translatesAutoresizingMaskIntoConstraints = false
            imageView.image = UIImage(named: "double_tick")
            return imageView
        }()
        
        private let separatorView: UIView = {
            let view = UIView()
            view.backgroundColor = UIColor.white.withAlphaComponent(0.5)
            view.translatesAutoresizingMaskIntoConstraints = false
            return view
        }()
        
        private let addContactButton: UIButton = {
            let button = UIButton(type: .system)
            button.setTitle("Add Contact", for: .normal)
            button.setTitleColor(.white, for: .normal)
            button.titleLabel?.font = UIFont.systemFont(ofSize: 14, weight: .medium)
            button.translatesAutoresizingMaskIntoConstraints = false
            return button
        }()
        
        private let messageButton: UIButton = {
            let button = UIButton(type: .system)
            button.setTitle("Message", for: .normal)
            button.setTitleColor(.white, for: .normal)
            button.titleLabel?.font = UIFont.systemFont(ofSize: 14, weight: .medium)
            button.translatesAutoresizingMaskIntoConstraints = false
            return button
        }()
        
        private let backgroundCardView: UIView = {
            let view = UIView()
            view.backgroundColor = UIColor.systemPurple
            view.layer.cornerRadius = 12
            view.clipsToBounds = true
            view.translatesAutoresizingMaskIntoConstraints = false
            return view
        }()
        
        private let timeStackView: UIStackView = {
            let stackView = UIStackView()
            stackView.axis = .horizontal
            stackView.spacing = 4
            stackView.alignment = .center
            stackView.translatesAutoresizingMaskIntoConstraints = false
            return stackView
        }()
        
        private let buttonStackView: UIStackView = {
            let stackView = UIStackView()
            stackView.axis = .horizontal
            stackView.spacing = 1
            stackView.distribution = .fillEqually
            stackView.translatesAutoresizingMaskIntoConstraints = false
            return stackView
        }()
        
        // MARK: - Initialization
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupViews()
        }
        
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
        
        private func setupViews() {
            // Add subviews
            addSubview(backgroundCardView)
            backgroundCardView.addSubview(profileImageView)
            backgroundCardView.addSubview(nameLabel)
            backgroundCardView.addSubview(timeStackView)
            timeStackView.addArrangedSubview(timeLabel)
            timeStackView.addArrangedSubview(doubleTickImageView)
            backgroundCardView.addSubview(separatorView)
            backgroundCardView.addSubview(buttonStackView)
            buttonStackView.addArrangedSubview(addContactButton)
            buttonStackView.addArrangedSubview(messageButton)
            
            // Constraints for the card
            NSLayoutConstraint.activate([
                backgroundCardView.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 16),
                backgroundCardView.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -16),
                backgroundCardView.topAnchor.constraint(equalTo: topAnchor, constant: 8),
                backgroundCardView.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -8)
            ])
            
            // Constraints for profile image
            NSLayoutConstraint.activate([
                profileImageView.leadingAnchor.constraint(equalTo: backgroundCardView.leadingAnchor, constant: 16),
                profileImageView.topAnchor.constraint(equalTo: backgroundCardView.topAnchor, constant: 16),
                profileImageView.widthAnchor.constraint(equalToConstant: 50),
                profileImageView.heightAnchor.constraint(equalToConstant: 50)
            ])
            
            // Constraints for name label
            NSLayoutConstraint.activate([
                nameLabel.leadingAnchor.constraint(equalTo: profileImageView.trailingAnchor, constant: 12),
                nameLabel.centerYAnchor.constraint(equalTo: profileImageView.centerYAnchor),
                nameLabel.trailingAnchor.constraint(lessThanOrEqualTo: timeStackView.leadingAnchor, constant: -8)
            ])
            
            // Constraints for time stack view
            NSLayoutConstraint.activate([
                timeStackView.trailingAnchor.constraint(equalTo: backgroundCardView.trailingAnchor, constant: -16),
                timeStackView.centerYAnchor.constraint(equalTo: nameLabel.centerYAnchor),
                doubleTickImageView.widthAnchor.constraint(equalToConstant: 16),
                doubleTickImageView.heightAnchor.constraint(equalToConstant: 16)
            ])
            
            // Constraints for separator
            NSLayoutConstraint.activate([
                separatorView.leadingAnchor.constraint(equalTo: backgroundCardView.leadingAnchor, constant: 16),
                separatorView.trailingAnchor.constraint(equalTo: backgroundCardView.trailingAnchor, constant: -16),
                separatorView.topAnchor.constraint(equalTo: profileImageView.bottomAnchor, constant: 16),
                separatorView.heightAnchor.constraint(equalToConstant: 1)
            ])
            
            // Constraints for button stack
            NSLayoutConstraint.activate([
                buttonStackView.leadingAnchor.constraint(equalTo: backgroundCardView.leadingAnchor),
                buttonStackView.trailingAnchor.constraint(equalTo: backgroundCardView.trailingAnchor),
                buttonStackView.topAnchor.constraint(equalTo: separatorView.bottomAnchor, constant: 8),
                buttonStackView.bottomAnchor.constraint(equalTo: backgroundCardView.bottomAnchor, constant: -8)
            ])
        }
    }
    ```
  </Tab>
</Tabs>

<Note>
  Make sure to set new type and category in the message Request builder in order to fetch those respective messages as shown in the example above.
</Note>

***

## Next Steps

* [Message List](/docs/ui-kit/ios/message-list) — Display and customize the message list
* [Message Bubble Styling](/docs/ui-kit/ios/message-bubble-styling) — Customize message bubble appearance
* [Message Composer](/docs/ui-kit/ios/message-composer) — Customize the message input component

***


# Methods
Source: https://www.cometchat.com/docs/ui-kit/ios/methods

Reference for CometChatUIKit wrapper methods that manage SDK operations, internal eventing, login, logout, user creation, and message sending in the iOS UI Kit.

<Info>
  **Quick Reference for AI Agents & Developers**

  * **Class:** `CometChatUIKit`
  * **Import:** `import CometChatUIKitSwift`
  * **Init:** `CometChatUIKit.init(uiKitSettings:onSuccess:onError:)`
  * **Login:** `CometChatUIKit.login(uid:onSuccess:onError:)` or `CometChatUIKit.login(authToken:onSuccess:onError:)`
  * **Logout:** `CometChatUIKit.logout(user:result:)`
  * **Create user:** `CometChatUIKit.createUser(user:onSuccess:onError:)`
  * **Send message:** `CometChatUIKit.sendTextMessage(message:onSuccess:onError:)`, `sendMediaMessage`, `sendCustomMessage`
  * **Related:** [Getting Started](/docs/ui-kit/ios/getting-started) · [Events](/docs/ui-kit/ios/events) · [SDK Overview](/docs/sdk/ios/overview)
</Info>

## Overview

The UI Kit's core function is to extend the [CometChat SDK](/docs/sdk/ios/overview), translating raw data and functionality into visually appealing, easy-to-use UI components.

To effectively manage and synchronize UI elements and data across all components, the UI Kit uses internal events. These events enable real-time change tracking and ensure the UI reflects the most current state of data.

The CometChat UI Kit encapsulates critical [CometChat SDK](/docs/sdk/ios/overview) methods within its wrapper to efficiently manage internal eventing. This abstraction layer simplifies interaction with the underlying SDK, making it more developer-friendly.

## Methods

Access all public methods exposed by the CometChat UI Kit through the `CometChatUIKit` class.

### Init

You must invoke this method before using any other UI Kit methods. This initialization ensures the UI Kit and Chat SDK function correctly in your application. Best practice is to make this one of the first lines of code executed in your application's lifecycle.

<Note>
  Replace **APP\_ID**, **REGION**, and **AUTH\_KEY** with your CometChat App ID, Region, and Auth Key. The `Auth Key` is an optional property of the `UIKitSettings` class, intended primarily for proof-of-concept (POC) development or early stages of application development. For production, use [Auth Token](#login-using-auth-token) instead.
</Note>

#### UIKitSettings Properties

| Method                               | Type                          | Description                                                                                                                           |
| ------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **set(appID:)**                      | `String`                      | Sets the unique ID for the app, available on dashboard                                                                                |
| **set(region:)**                     | `String`                      | Sets the region for the app ('us' or 'eu')                                                                                            |
| **set(authKey:)**                    | `String`                      | Sets the auth key for the app, available on dashboard                                                                                 |
| **subscribePresenceForAllUsers**     | `String`                      | Sets subscription type for tracking the presence of all users                                                                         |
| **subscribePresenceForFriends**      | `String`                      | Sets subscription type for tracking the presence of friends                                                                           |
| **subscribePresenceForRoles**        | `String`                      | Sets subscription type for tracking the presence of users with specified roles                                                        |
| **setAutoEstablishSocketConnection** | `Boolean`                     | Configures if web socket connections will established automatically on app initialization or be done manually, set to true by default |
| **setAIFeatures**                    | `List<AIExtensionDataSource>` | Sets the AI Features that need to be added in UI Kit                                                                                  |
| **setExtensions**                    | `List<ExtensionsDataSource>`  | Sets the list of extension that need to be added in UI Kit                                                                            |

#### Example

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let uiKitSettings = UIKitSettings()
      .set(region: "your_region")
      .set(appID: "your_appId")
      .set(authKey: "your_authKey")
      .subscribePresenceForAllUsers()
      .autoEstablishSocketConnection(bool: true)

    CometChatUIKit.init(uiKitSettings: uikitSettings) { result in
      switch result{
      case .success(let bool):
        print( "Initialization success")
      case .failure(let error):
        print("CometChat exception: \(error)")
      }
    }
    ```
  </Tab>
</Tabs>

***

### Login using Auth Key

Only the `UID` of a user is needed to log in. This simple authentication procedure is useful for POC or development phases. For production apps, use [AuthToken](#login-using-auth-token) instead.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    CometChatUIKit.login(uid: "uid") { (result) in
      switch result {
      case .success(let user):
        print("CometChat user logged in: \(user)")
      case .onError(let error):
        print("CometChat exception: \(error)")
      }
    }
    ```
  </Tab>
</Tabs>

***

### Login using Auth Token

This advanced authentication procedure does not use the Auth Key directly in your client code, ensuring better security.

1. [Create a User](/docs/rest-api/chat-apis) via the CometChat API when the user signs up in your app.
2. [Create an Auth Token](/docs/rest-api/chat-apis) via the CometChat API for the new user and save the token in your database.
3. Load the Auth Token in your client and pass it to the `login(authToken:)` method.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    CometChatUIKit.login(authToken: "your_authToken") { (result) in
      switch result {
      case .success(let user):
        print("CometChat user logged in: \(user)")
      case .onError(let error):
        print("CometChat exception: \(error)")
      }
    }
    ```
  </Tab>
</Tabs>

***

### Logout

The CometChat UI Kit and Chat SDK handle the session of the logged-in user within the framework. Before a new user logs in, clean this data to avoid potential conflicts or unexpected behavior by invoking the `.logout(user:)` function.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let user = User(uid: "uid", name: "user_name")

    CometChatUIKit.logout(user: user) { (result) in
      switch result {
      case .success(let user):
        print("CometChat user logged out: \(user)")
      case .onError(let error):
        print("CometChat exception: \(error)")
      }
    }
    ```
  </Tab>
</Tabs>

***

### Create User

Dynamically create users on CometChat using the `.create(user:)` function. This is useful when users are registered or authenticated by your system and need to be created on CometChat.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let user = User(uid: "uid", name: "user_name")

    CometChatUIKit.create(user: user) { result in
      switch result {
      case .success(let user):
        print("CometChat user logged out: \(user)")
      case .onError(let error):
        print("CometChat exception: \(error)")
      }
    }
    ```
  </Tab>
</Tabs>

***

### Base Message

#### Text Message

To send a text message to a single user or a group, use the `sendTextMessage()` function. This function requires a `TextMessage` object containing the necessary information for delivering the message.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let textMessage = TextMessage(receiverUid: "uid", text: message, receiverType: .user)
    textMessage.muid =  "\(NSDate().timeIntervalSince1970)"
    textMessage.sentAt = Int(Date().timeIntervalSince1970)
    textMessage.senderUid = CometChat.getLoggedInUser()?.uid ?? ""
    textMessage.sender = CometChat.getLoggedInUser()
    textMessage.parentMessageId = parentMessageId

    CometChatUIKit.sendTextMessage(message: textMessage)
    ```
  </Tab>
</Tabs>

<Note>
  `CometChatUIKit.sendTextMessage()` automatically adds the message to the [MessagesComponent](/docs/ui-kit/ios/message-list) and [ConversationsComponent](/docs/ui-kit/ios/conversations), handling all related cases for you. In contrast, `CometChat.sendTextMessage()` only sends the message without updating these UI Kit components.
</Note>

***

#### Media Message

To send a media message to a single user or a group, use the `sendMediaMessage()` function. This function requires a `MediaMessage` object containing the necessary information for delivering the message.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let mediaMessage = MediaMessage(receiverUid: "uid", fileurl: url, messageType: type, receiverType: .user)
    mediaMessage.muid = "\(NSDate().timeIntervalSince1970)"
    mediaMessage.sentAt = Int(Date().timeIntervalSince1970)
    mediaMessage.sender = CometChat.getLoggedInUser()
    mediaMessage.metaData = ["fileURL": url]
    mediaMessage.senderUid = CometChat.getLoggedInUser()?.uid ?? ""
    mediaMessage.parentMessageId = parentMessageId

    CometChatUIKit.sendMediaMessage(message: MediaMessage)
    ```
  </Tab>
</Tabs>

<Note>
  `CometChatUIKit.sendMediaMessage()` automatically adds the message to the [MessagesComponent](/docs/ui-kit/ios/message-list) and [ConversationsComponent](/docs/ui-kit/ios/conversations), handling all related cases for you. In contrast, `CometChat.sendMediaMessage()` only sends the message without updating these UI Kit components.
</Note>

***

#### Custom Message

To send a custom message to a single user or a group, use the `sendCustomMessage()` function. This function requires a `CustomMessage` object containing the necessary information for delivering the message.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    var customData = [String: Any]()
    customData["key"] = "value"

    let customMessage = CustomMessage(receiverUid: "uid or guid", receiverType: .user, customData: customData, type: "custom message type")
    customMessage.muid = "\(Int(Date().timeIntervalSince1970))"
    customMessage.senderUid = CometChat.getLoggedInUser()?.uid
    customMessage.sender = CometChat.getLoggedInUser()

    CometChatUIKit.sendCustomMessage(message: CustomMessage)
    ```
  </Tab>
</Tabs>

<Note>
  `CometChatUIKit.sendCustomMessage()` automatically adds the message to the [MessagesComponent](/docs/ui-kit/ios/message-list) and [ConversationsComponent](/docs/ui-kit/ios/conversations), handling all related cases for you. In contrast, `CometChat.sendCustomMessage()` only sends the message without updating these UI Kit components.
</Note>

***

### Interactive Message

#### Form Message

To send a Form message to a single user or a group, use the `sendFormMessage()` function. This function requires a `FormMessage` object containing the necessary information to create a form bubble for that message.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let apiAction = APIAction()
    apiAction.url = "https://example.com/api"
    apiAction.method = .POST

    let submitButton = ButtonElement()
    submitButton.elementId = "1"
    submitButton.action = apiAction
    submitButton.buttonText = "Submit"

    let nameInput = TextInput()
    nameInput.elementId = "1"
    nameInput.placeHolder = "Please enter your name"

    let formMessage = FormMessage(title: "Title",receiverUid: receiverId,receiverType: .user, formFields: [nameInput],submitElement: submitButton)

    CometChatUIKit.sendFormMessage(formMessage) { form in
      print("Form message sent: \(form)")
    } onError: { error in
      print("CometChat exception: \(error)")
    }
    ```
  </Tab>
</Tabs>

***

#### Card Message

To send a Card message to a single user or a group, use the `sendCardMessage()` function. This function requires a `CardMessage` object containing the necessary information to create a card bubble for the message.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let apiAction = APIAction()
    apiAction.url = "https://example.com/api"
    apiAction.method = .POST

    let cardAction = ButtonElement()
    cardAction.elementId = "1"
    cardAction.action = apiAction
    cardAction.buttonText = "Click Me"

    let cardMessage = CardMessage(url:"ImageURL", receiverUid:"receiverId", receiverType:.user, cardActions:[cardAction],text: "This is a card")

    CometChatUIKit.sendCardMessage(cardMessage) { success in
      print("Card message sent: \(success)")
    } onError: { error in
      print("CometChat exception: \(error)")
    }
    ```
  </Tab>
</Tabs>

***

#### Scheduler Message

To send a Scheduler message to a single user or a group, use the `sendSchedulerMessage()` function. This function requires a `SchedulerMessage` object containing the necessary information to create a scheduler bubble for the message.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    var interactiveData = [String: Any]()
    interactiveData["key"] = "value"

    let schedulerMessage = SchedulerMessage(receiverUid: "receiver_uid", type: "scheduler message type", receiverType: .user, interactiveData: interactiveData)

    CometChatUIKit.sendSchedulerMessage(schedulerMessage: schedulerMessage) { scheduler in
      print("Scheduler message sent: \(scheduler)")
    } onError: { error in
      print("CometChat exception: \(error)")
    }
    ```
  </Tab>
</Tabs>

***

***

## Next Steps

<CardGroup>
  <Card title="Events" icon="bolt" href="/ui-kit/ios/events">
    Listen to UI Kit component events
  </Card>

  <Card title="Getting Started" icon="rocket" href="/ui-kit/ios/getting-started">
    Set up the iOS UI Kit from scratch
  </Card>

  <Card title="Components Overview" icon="puzzle-piece" href="/ui-kit/ios/components-overview">
    Explore all available UI components
  </Card>

  <Card title="SDK Overview" icon="code" href="/sdk/ios/overview">
    Explore the underlying CometChat SDK
  </Card>
</CardGroup>


# Notification Feed
Source: https://www.cometchat.com/docs/ui-kit/ios/notification-feed

Full-screen notification feed component with category filtering, card rendering, real-time updates, and engagement reporting.

`CometChatNotificationFeed` displays a scrollable notification feed where each item is rendered as a native card using the CometChat Cards library. It handles fetching, pagination, category filtering, real-time updates, and read/delivered/engagement reporting automatically. Present it in a `UINavigationController`, push it onto an existing navigation stack, or embed it in a tab bar.

Each notification gets its own section header with the category label on the left and a relative timestamp on the right:

| Condition                   | Display                          |
| --------------------------- | -------------------------------- |
| Today (\< 24 hours ago)     | Time only — 2:35 PM              |
| Yesterday (24–48 hours ago) | Yesterday                        |
| This week (2–7 days ago)    | Day name — Monday, Tuesday, etc. |
| Older (> 7 days)            | Full date — 25/05/2026           |

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let notificationFeed = CometChatNotificationFeed()
    notificationFeed.set(onItemClick: { feedItem in
        // Handle item tap (e.g., open detail or deep link)
    })

    let navController = UINavigationController(rootViewController: notificationFeed)
    self.present(navController, animated: true)
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let notificationFeed = CometChatNotificationFeed()
    let navController = UINavigationController(rootViewController: notificationFeed)
    self.present(navController, animated: true)
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()` and a user logged in.

***

## Filtering Feed Items

Control what loads using custom request builders:

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let notificationFeed = CometChatNotificationFeed()
    notificationFeed.set(notificationFeedRequestBuilder:
        NotificationFeedRequest.NotificationFeedRequestBuilder()
            .set(limit: 30)
            .set(readState: .unread)
            .set(category: "promotions")
    )
    ```
  </Tab>
</Tabs>

### Filter Options

| Builder Method                   | Description                          |
| -------------------------------- | ------------------------------------ |
| `.set(limit: Int)`               | Items per page (default 20).         |
| `.set(readState: FeedReadState)` | `.read`, `.unread`, or omit for all. |
| `.set(category: String)`         | Filter by category name.             |
| `.set(categoryId: String)`       | Filter by category ID.               |
| `.set(channelId: String)`        | Filter by channel.                   |
| `.set(tags: [String])`           | Filter by tags.                      |
| `.set(dateFrom: String)`         | ISO 8601 date lower bound.           |
| `.set(dateTo: String)`           | ISO 8601 date upper bound.           |

Pass the builder object, not the result of `.build()`. The component calls `.build()` internally.

***

## Actions and Events

### onItemClick

Fires when a feed item card is tapped.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(onItemClick: { feedItem in
        // feedItem.id, feedItem.content (Card JSON), feedItem.category
        print("Item tapped: \(feedItem.id)")
    })
    ```
  </Tab>
</Tabs>

***

### onActionClick

Fires when an interactive element (button, link) inside a card is tapped.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(onActionClick: { feedItem, actionEvent in
        // Report engagement on every action
        CometChat.reportFeedEngagement(feedItem, interactionString: "button_clicked", onSuccess: {}, onError: { _ in })

        // Handle the action
        switch actionEvent.action {
        case .openUrl(let url, _):
            if let link = URL(string: url) {
                UIApplication.shared.open(link)
            }
        case .chatWithUser(let uid):
            // Navigate to 1-on-1 chat
            break
        case .chatWithGroup(let guid):
            // Navigate to group chat
            break
        case .customCallback(let callbackId, let payload):
            // Custom app logic
            break
        default:
            break
        }
    })
    ```
  </Tab>
</Tabs>

***

### onError

Fires when an internal error occurs (network failure, SDK exception).

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(onError: { error in
        print("Feed error: \(error.errorDescription)")
    })
    ```
  </Tab>
</Tabs>

***

## Automatic Behaviors

The component handles these automatically — no manual setup needed:

| Behavior             | Description                                                   |
| -------------------- | ------------------------------------------------------------- |
| Real-time updates    | New items appear at the top via WebSocket listener.           |
| Delivery reporting   | Items are reported as delivered when fetched.                 |
| Read reporting       | Items are reported as read after 1 second of visibility.      |
| Unread count polling | Polls unread count every 30 seconds to update badges.         |
| Infinite scroll      | Fetches next page when scrolling near the bottom.             |
| Pull-to-refresh      | Resets and fetches fresh data on pull.                        |
| Timestamp grouping   | Groups items as "Today", "Yesterday", day name, or date.      |
| Category filtering   | Filter chips row for category-based filtering.                |
| Connection recovery  | Automatically refreshes when the app returns from background. |

***

## Functionality

| Method                                       | Description                                       |
| -------------------------------------------- | ------------------------------------------------- |
| `set(title: String)`                         | Header title text. Default "Notifications".       |
| `set(showBackButton: Bool)`                  | Toggle back button visibility. Default `true`.    |
| `set(showFilterChips: Bool)`                 | Toggle category filter chips. Default `true`.     |
| `set(cardThemeMode: String)`                 | Card rendering theme: "auto", "light", or "dark". |
| `set(notificationFeedRequestBuilder:)`       | Custom feed request builder.                      |
| `set(notificationCategoriesRequestBuilder:)` | Custom categories request builder.                |

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let notificationFeed = CometChatNotificationFeed()
    notificationFeed.set(title: "Activity")
    notificationFeed.set(showBackButton: false)
    notificationFeed.set(showFilterChips: true)
    notificationFeed.set(cardThemeMode: "dark")
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Show only unread items

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(notificationFeedRequestBuilder:
        NotificationFeedRequest.NotificationFeedRequestBuilder()
            .set(readState: .unread)
    )
    ```
  </Tab>
</Tabs>

### Hide filter chips

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(showFilterChips: false)
    ```
  </Tab>
</Tabs>

### Custom categories request

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(notificationCategoriesRequestBuilder:
        NotificationCategoriesRequest.NotificationCategoriesRequestBuilder()
            .set(limit: 10)
    )
    ```
  </Tab>
</Tabs>

### Embed in a Tab Bar

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let notificationFeed = CometChatNotificationFeed()
    notificationFeed.set(showBackButton: false)
    notificationFeed.tabBarItem = UITabBarItem(
        title: "Notifications",
        image: UIImage(systemName: "bell"),
        selectedImage: UIImage(systemName: "bell.fill")
    )

    // Add to tab bar controller
    let navController = UINavigationController(rootViewController: notificationFeed)
    tabBarController.viewControllers?.append(navController)
    ```
  </Tab>
</Tabs>

### Handle action + report engagement

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(onActionClick: { feedItem, actionEvent in
        // Always report engagement
        CometChat.reportFeedEngagement(feedItem, interactionString: actionEvent.elementId, onSuccess: {}, onError: { _ in })

        switch actionEvent.action {
        case .openUrl(let url, _):
            if let link = URL(string: url) {
                UIApplication.shared.open(link)
            }
        case .chatWithUser(let uid):
            // Open CometChat messages with user
            break
        default:
            break
        }
    })
    ```
  </Tab>
</Tabs>

***

## Next Steps

| Topic                                      | Description                                                    |
| ------------------------------------------ | -------------------------------------------------------------- |
| [Campaigns Feature](/docs/ui-kit/ios/campaigns) | Overview of how campaigns work end-to-end.                     |
| [SDK Campaigns API](/docs/sdk/ios/campaigns)    | Low-level SDK APIs for feed items, categories, and engagement. |


# Ongoing Call
Source: https://www.cometchat.com/docs/ui-kit/ios/ongoing-call

Display CometChat iOS UI Kit ongoing calls with video, call controls, participant management, recording, screen sharing, and callbacks.

The `CometChatOngoingCall` component provides users with a dedicated interface for managing real-time voice or video conversations. It includes features like a video display area for video calls, call controls for mic and camera management, participant information, call status indicators, and options for call recording and screen-sharing.

<Frame>
  <img />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatOngoingCall",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatCallsSDK",
    "description": "Displays active call interface with video, controls, and participant management",
    "inherits": "UIViewController",
    "primaryOutput": {
      "callback": "onCallEnded",
      "type": "(Call) -> Void"
    },
    "props": {
      "data": {
        "sessionID": { "type": "String", "required": true },
        "callSettingsBuilder": { "type": "CallSettingsBuilder?", "default": "nil" }
      },
      "callbacks": {
        "onCallEnded": "(Call) -> Void",
        "onError": "(CometChatException) -> Void"
      }
    },
    "events": [
      { "name": "onCallEnded", "payload": "Call", "description": "Fires when call ends" }
    ],
    "sdkListeners": [],
    "compositionExample": {
      "description": "OngoingCall is presented during an active call",
      "components": ["CometChatIncomingCall", "CometChatOutgoingCall", "CometChatOngoingCall"],
      "flow": "Call accepted → OngoingCall shown → Call ends → Returns to previous screen"
    }
  }
  ```
</Accordion>

| Field     | Value                  |
| --------- | ---------------------- |
| Component | `CometChatOngoingCall` |
| Package   | `CometChatUIKitSwift`  |
| Inherits  | `UIViewController`     |

***

## Usage

### Integration

`CometChatOngoingCall` is a custom view controller that offers versatility in its integration. It can be seamlessly launched via button clicks or any user-triggered action, enhancing the overall user experience and facilitating smoother interactions within the application.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // The sessionID should be received from CometChat SDK when the call was initiated or received
    let sessionID = "your_session_id"

    let cometChatOngoingCall = CometChatOngoingCall()
    cometChatOngoingCall.set(sessionID: sessionID)
    cometChatOngoingCall.modalPresentationStyle = .fullScreen
    self.present(cometChatOngoingCall, animated: true)
    ```
  </Tab>
</Tabs>

<Note>
  If you are already using a navigation controller, you can use the `pushViewController` function instead of presenting the view controller.
</Note>

### Actions

[Actions](/docs/ui-kit/ios/components-overview#actions) dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the component to fit your specific needs.

#### 1. SetOnCallEnded

The `setOnCallEnded` action is typically triggered when the call ends, carrying out default actions. You can customize or override this default behavior using the following code snippet:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let cometChatOngoingCall = CometChatOngoingCall()
    .setOnCallEnded { call in
      // Perform your action
    }
    ```
  </Tab>
</Tabs>

***

### Filters

Filters allow you to customize the data displayed in a list within a Component. You can filter the list based on your specific criteria for a more customized experience. Filters can be applied using RequestBuilders of the Chat SDK.

You can adjust the `callSettingsBuilder` in the OnGoing Call Component to customize the call. Numerous options are available to alter the builder to meet your specific needs. For additional details on `CallSettingsBuilder`, visit [CallSettingsBuilder](/docs/sdk/ios/direct-calling).

#### 1. CallSettingsBuilder

The [CallSettingsBuilder](/docs/sdk/ios/direct-calling) enables you to filter and customize the call list based on available parameters. This feature allows you to create more specific and targeted queries during the call.

| Methods                          | Description                                  | Code                                      |
| -------------------------------- | -------------------------------------------- | ----------------------------------------- |
| **setAudioModeButtonDisable**    | Disable the audio mode button                | `.setAudioModeButtonDisable(Bool)`        |
| **setAvatarMode**                | Set the avatar mode                          | `.setAvatarMode("")`                      |
| **setDefaultAudioMode**          | Set the default audio mode                   | `.setDefaultAudioMode("")`                |
| **setDefaultLayout**             | Set the default layout                       | `.setDefaultLayout(Bool)`                 |
| **setDelegate**                  | Set the calls events delegate                | `.setDelegate(CallsEventsDelegate)`       |
| **setEnableDraggableVideoTile**  | Enable draggable video tile                  | `.setEnableDraggableVideoTile(Bool)`      |
| **setEnableVideoTileClick**      | Enable click actions on video tile           | `.setEnableVideoTileClick(Bool)`          |
| **setEndCallButtonDisable**      | Disable the end call button                  | `.setEndCallButtonDisable(Bool)`          |
| **setIsAudioOnly**               | Set the call as audio only                   | `.setIsAudioOnly(Bool)`                   |
| **setIsSingleMode**              | Set the call as single mode                  | `.setIsSingleMode(Bool)`                  |
| **setMode**                      | Set the mode                                 | `.setMode("NSString")`                    |
| **setMuteAudioButtonDisable**    | Disable the mute audio button                | `.setMuteAudioButtonDisable(Bool)`        |
| **setPauseVideoButtonDisable**   | Disable the pause video button               | `.setPauseVideoButtonDisable(Bool)`       |
| **setShowRecordingButton**       | Show or hide the recording button            | `.setShowRecordingButton(Bool)`           |
| **setShowSwitchToVideoCall**     | Show or hide the switch to video call button | `.setShowSwitchToVideoCall(Bool)`         |
| **setStartAudioMuted**           | Start with audio muted                       | `.setStartAudioMuted(Bool)`               |
| **setStartRecordingOnCallStart** | Start recording when the call starts         | `.setStartRecordingOnCallStart(Bool)`     |
| **setStartVideoMuted**           | Start with video muted                       | `.setStartVideoMuted(Bool)`               |
| **setSwitchCameraButtonDisable** | Disable the switch camera button             | `.setSwitchCameraButtonDisable(Bool)`     |
| **setVideoContainer**            | Set the video container                      | `.setVideoContainer(NSMutableDictionary)` |
| **setVideoSettings**             | Set the video settings                       | `.setVideoSettings(NSMutableDictionary)`  |

#### Example

In the example below, we are applying a filter to the calls:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callBuilder = CallSettingsBuilder()
    .setAudioModeButtonDisable(true)
    .setEndCallButtonDisable(false)

    let cometChatOngoingCall = CometChatOngoingCall()
    .set(sessionId: "Your Session ID")
    .set(callSettingsBuilder: callBuilder)

    cometChatOngoingCall.modalPresentationStyle = .fullScreen
    self.present(cometChatOngoingCall, animated: true)
    ```
  </Tab>
</Tabs>

<Warning>
  Ensure to include an `NSMicrophoneUsageDescription` key with a descriptive string value in the app's Info.plist.
</Warning>

***

### Events

[Events](/docs/ui-kit/ios/components-overview#events) are emitted by a Component. By using events, you can extend existing functionality. Being global events, they can be applied in multiple locations and can be added or removed as needed.

| Event           | Description                                      |
| --------------- | ------------------------------------------------ |
| **onCallEnded** | Triggers when the ongoing or outgoing call ends. |

<Tabs>
  <Tab title="Add Listener">
    ```swift lines theme={null}
    // View controller from your project where you want to listen to events
    public class ViewController: UIViewController {

       public override func viewDidLoad() {
            super.viewDidLoad()

           // Subscribe to the listener for call events
            CometChatCallEvents.addListener("UNIQUE_ID", self as CometChatCallEventListener)
        }
    }

    // Listener for call events
    extension ViewController: CometChatCallEventListener {

        func onCallEnded(call: Call) {
            // Handle call ended
        }
    }
    ```

    ```swift Emitting Call Events theme={null}
    // Emit this when logged in user ends a call
    CometChatCallEvents.emitOnCallEnded(call: Call)
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Remove Listener">
    ```swift lines theme={null}
    public override func viewWillDisappear(_ animated: Bool) {
          // Unsubscribe from the listener
          CometChatCallEvents.removeListener("LISTENER_ID_USED_FOR_ADDING_THIS_LISTENER")
    }
    ```
  </Tab>
</Tabs>

***

## Customization

To fit your app's design requirements, you can customize the appearance of the component. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.

### Style

Using Style, you can customize the look and feel of the component in your app. These parameters typically control elements such as the color, size, shape, and fonts used within the component.

The OngoingCall component does not have any exposed Styles.

***

### Functionality

These are small functional customizations that allow you to fine-tune the overall experience of the component. With these, you can change text, set custom icons, and toggle the visibility of UI elements.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let cometChatOngoingCall = CometChatOngoingCall()
    .set(sessionId: "Your Session ID")
    .set(callWorkFlow: .defaultCalling)

    cometChatOngoingCall.modalPresentationStyle = .fullScreen
    self.present(cometChatOngoingCall, animated: true)
    ```
  </Tab>
</Tabs>

<Note>
  If you are already using a navigation controller, you can use the `pushViewController` function instead of presenting the view controller.
</Note>

| Property         | Description                                   | Code                      |
| ---------------- | --------------------------------------------- | ------------------------- |
| **CallWorkFlow** | Sets the call type to default or direct.      | `CallWorkFlow`            |
| **Session Id**   | Sets the session ID for CometChatOngoingCall. | `.set(sessionId: String)` |

### Advanced

For advanced-level customization, you can set custom views to the component. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your own views, layouts, and UI elements and then incorporate those into the component.

The `OngoingCall` component does not provide additional functionalities beyond this level of customization.

***

## Common Patterns

### Present Ongoing Call After Acceptance

Show the ongoing call screen after a call is accepted:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    func presentOngoingCall(sessionId: String) {
        let ongoingCall = CometChatOngoingCall()
        ongoingCall.set(sessionId: sessionId)
        ongoingCall.modalPresentationStyle = .fullScreen
        
        self.present(ongoingCall, animated: true)
    }
    ```
  </Tab>
</Tabs>

### Configure Call Settings for Video Call

Customize video call settings before starting:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let callSettingsBuilder = CallSettingsBuilder()
        .setIsAudioOnly(false)
        .setDefaultAudioMode("SPEAKER")
        .setShowSwitchToVideoCall(false)
        .setShowRecordingButton(true)
        .setStartVideoMuted(false)
        .setStartAudioMuted(false)

    let ongoingCall = CometChatOngoingCall()
    ongoingCall.set(sessionId: sessionId)
    ongoingCall.set(callSettingsBuilder: callSettingsBuilder)
    ```
  </Tab>
</Tabs>

### Audio-Only Call Configuration

Set up an audio-only call with speaker mode:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let audioCallSettings = CallSettingsBuilder()
        .setIsAudioOnly(true)
        .setDefaultAudioMode("SPEAKER")
        .setMuteAudioButtonDisable(false)
        .setEndCallButtonDisable(false)

    let ongoingCall = CometChatOngoingCall()
    ongoingCall.set(sessionId: sessionId)
    ongoingCall.set(callSettingsBuilder: audioCallSettings)
    ongoingCall.modalPresentationStyle = .fullScreen
    self.present(ongoingCall, animated: true)
    ```
  </Tab>
</Tabs>

### Listen for Call End Events

Use CometChatCallEvents to handle call end:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Subscribe to call events
    CometChatCallEvents.addListener("ongoing_call_listener", self as CometChatCallEventListener)

    // In CometChatCallEventListener extension
    func onCallEnded(call: Call) {
        DispatchQueue.main.async { [weak self] in
            self?.dismiss(animated: true) {
                // Show call summary
                let duration = call.duration ?? 0
                let minutes = duration / 60
                let seconds = duration % 60
                
                let alert = UIAlertController(
                    title: "Call Ended",
                    message: "Duration: \(minutes)m \(seconds)s",
                    preferredStyle: .alert
                )
                alert.addAction(UIAlertAction(title: "OK", style: .default))
                self?.present(alert, animated: true)
            }
        }
    }
    ```
  </Tab>
</Tabs>

***


# Outgoing Call
Source: https://www.cometchat.com/docs/ui-kit/ios/outgoing-call

Display CometChat iOS UI Kit outgoing call screens with recipient details, cancel actions, custom sounds, and outgoing call callbacks.

The `CometChatOutgoingCall` component is a visual representation of a user-initiated call, whether voice or video. It serves as an interface for managing outgoing calls, providing users with essential options to control the call experience.

<Frame>
  <img alt="CometChatOutgoingCall showing outgoing call interface with recipient avatar, name, and cancel button" />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatOutgoingCall",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "description": "Displays outgoing call interface while waiting for recipient to answer",
    "inherits": "UIViewController",
    "primaryOutput": {
      "callback": "onCancelClick",
      "type": "(Call, UIViewController) -> Void"
    },
    "props": {
      "data": {
        "call": { "type": "Call", "required": true }
      },
      "callbacks": {
        "onCancelClick": "(Call, UIViewController) -> Void",
        "onError": "(CometChatException) -> Void"
      },
      "sound": {
        "disableSoundForCalls": { "type": "Bool", "default": false },
        "customSoundForCalls": { "type": "URL?", "default": "nil" }
      },
      "viewSlots": {
        "listItemView": "(Call) -> UIView",
        "leadingView": "(Call) -> UIView",
        "titleView": "(Call) -> UIView"
      }
    },
    "events": [
      { "name": "onOutgoingCallAccepted", "payload": "Call", "description": "Fires when outgoing call is accepted" },
      { "name": "onOutgoingCallRejected", "payload": "Call", "description": "Fires when outgoing call is rejected" }
    ],
    "sdkListeners": [],
    "compositionExample": {
      "description": "OutgoingCall is presented when user initiates a call",
      "components": ["CometChatCallButtons", "CometChatOutgoingCall", "CometChatOngoingCall"],
      "flow": "User taps call → OutgoingCall shown → Recipient answers → OngoingCall starts"
    }
  }
  ```
</Accordion>

| Field     | Value                   |
| --------- | ----------------------- |
| Component | `CometChatOutgoingCall` |
| Package   | `CometChatUIKitSwift`   |
| Inherits  | `UIViewController`      |

***

## Usage

### Integration

`CometChatOutgoingCall` is a custom view controller that offers versatility in its integration. It can be seamlessly launched via button clicks or any user-triggered action, enhancing the overall user experience and facilitating smoother interactions within the application.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let cometChatOutgoingCall = CometChatOutgoingCall()
    cometChatOutgoingCall.set(call: call)

    cometChatOutgoingCall.modalPresentationStyle = .fullScreen
    self.present(cometChatOutgoingCall, animated: true)
    ```
  </Tab>
</Tabs>

<Note>
  If you are already using a navigation controller, you can use the `pushViewController` function instead of presenting the view controller.
</Note>

### Actions

[Actions](/docs/ui-kit/ios/components-overview#actions) dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the component to fit your specific needs.

#### 1. SetOnCancelClick

The `setOnCancelClick` action is typically triggered when the call is canceled, carrying out default actions. You can customize or override this default behavior using the following code snippet:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let cometChatOutgoingCall = CometChatOutgoingCall()
    cometChatOutgoingCall.set(onCancelClick: { call, controller in
        // Perform your action
    })
    ```
  </Tab>
</Tabs>

***

#### 2. OnError

You can customize error handling behavior by using the provided code snippet to override the `onError` callback:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let incomingCallConfiguration = CometChatOutgoingCall()
    .set(onError: { error in
        // Perform your action
    })
    ```
  </Tab>
</Tabs>

***

### Filters

Filters allow you to customize the data displayed in a list within a Component. You can filter the list based on your specific criteria for a more customized experience. Filters can be applied using RequestBuilders of the Chat SDK.

The OutgoingCall component does not have any exposed filters.

***

### Events

[Events](/docs/ui-kit/ios/components-overview#events) are emitted by a Component. By using events, you can extend existing functionality. Being global events, they can be applied in multiple locations and can be added or removed as needed.

| Event                      | Description                                  |
| -------------------------- | -------------------------------------------- |
| **onOutgoingCallAccepted** | Triggers when the outgoing call is accepted. |
| **onOutgoingCallRejected** | Triggers when the outgoing call is rejected. |

<Tabs>
  <Tab title="Add Listener">
    ```swift lines theme={null}
    // View controller from your project where you want to listen to events
    public class ViewController: UIViewController {

       public override func viewDidLoad() {
            super.viewDidLoad()

           // Subscribe to the listener for call events
            CometChatCallEvents.addListener("UNIQUE_ID", self as CometChatCallEventListener)
        }
    }

    // Listener for call events
    extension ViewController: CometChatCallEventListener {

        func onOutgoingCallAccepted(call: Call) {
            // Handle call accepted
        }

        func onOutgoingCallRejected(call: Call) {
            // Handle call rejected
        }
    }
    ```

    ```swift Emitting Call Events theme={null}
    // Emit this when the other user accepts the call
    CometChatCallEvents.emitOnOutgoingCallAccepted(call: Call)

    // Emit this when the other user rejects a call
    CometChatCallEvents.emitOnOutgoingCallRejected(call: Call)
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Remove Listener">
    ```swift lines theme={null}
    public override func viewWillDisappear(_ animated: Bool) {
          // Unsubscribe from the listener
          CometChatCallEvents.removeListener("LISTENER_ID_USED_FOR_ADDING_THIS_LISTENER")
    }
    ```
  </Tab>
</Tabs>

***

## Customization

To fit your app's design requirements, you can customize the appearance of the component. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.

### Style

Using Style, you can customize the look and feel of the component in your app. These parameters typically control elements such as the color, size, shape, and fonts used within the component.

#### 1. OutgoingCall Style

You can customize the appearance of the `OutgoingCall` Component by applying the `OutgoingCallStyle` to it.

**Global level styling**

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let customAvatarStyle = AvatarStyle()
    customAvatarStyle.backgroundColor = UIColor(hex: "#FBAA75")
    customAvatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)
            
    CometChatOutgoingCall.style.nameLabelFont = UIFont(name: "Times-New-Roman", size: 20)
    CometChatOutgoingCall.style.callLabelFont = UIFont(name: "Times-New-Roman", size: 14)
    CometChatOutgoingCall.style.declineButtonCornerRadius = .init(cornerRadius: 8)
    CometChatOutgoingCall.avatarStyle = customAvatarStyle
    ```
  </Tab>
</Tabs>

**Instance level styling**

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let customAvatarStyle = AvatarStyle()
    customAvatarStyle.backgroundColor = UIColor(hex: "#FBAA75")
    customAvatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)
            
    let outgoingCallStyle = OutgoingCallStyle()
    outgoingCallStyle.nameLabelFont = UIFont(name: "Times-New-Roman", size: 20)
    outgoingCallStyle.callLabelFont = UIFont(name: "Times-New-Roman", size: 14)
    outgoingCallStyle.declineButtonCornerRadius = .init(cornerRadius: 8)
            
    let outgoingCall = CometChatOutgoingCall()
    outgoingCall.style = outgoingCallStyle
    outgoingCall.avatarStyle = customAvatarStyle
    ```
  </Tab>
</Tabs>

<Frame>
  <img alt="CometChatOutgoingCall with custom styling showing custom fonts and rounded decline button" />
</Frame>

#### OutgoingCallStyle Properties

| Property                       | Description                                                                 | Code                                                                                     |
| ------------------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `backgroundColor`              | Sets the background color for the outgoing call view.                       | `CometChatOutgoingCall.style.backgroundColor = UIColor()`                                |
| `borderColor`                  | Sets the border color for the outgoing call view.                           | `CometChatOutgoingCall.style.borderColor = UIColor.clear`                                |
| `borderWidth`                  | Sets the border width for the outgoing call view.                           | `CometChatOutgoingCall.style.borderWidth = 0`                                            |
| `cornerRadius`                 | Sets the corner radius for the outgoing call view.                          | `CometChatOutgoingCall.style.cornerRadius = .init(cornerRadius: 0)`                      |
| `nameTextColor`                | Sets the text color for the name label in the outgoing call view.           | `CometChatOutgoingCall.style.nameTextColor = UIColor()`                                  |
| `nameTextFont`                 | Sets the font for the name label in the outgoing call view.                 | `CometChatOutgoingCall.style.nameTextFont = UIFont()`                                    |
| `callTextColor`                | Sets the text color for the call label in the outgoing call view.           | `CometChatOutgoingCall.style.callTextColor = UIColor()`                                  |
| `callTextFont`                 | Sets the font for the call label in the outgoing call view.                 | `CometChatOutgoingCall.style.callTextFont = UIFont()`                                    |
| `declineButtonBackgroundColor` | Sets the background color for the decline button in the outgoing call view. | `CometChatOutgoingCall.style.declineButtonBackgroundColor = UIColor()`                   |
| `declineButtonIconTint`        | Sets the tint color for the decline button icon.                            | `CometChatOutgoingCall.style.declineButtonIconTint = UIColor()`                          |
| `declineButtonIcon`            | Sets the icon for the decline button.                                       | `CometChatOutgoingCall.style.declineButtonIcon = UIImage(systemName: "phone.down.fill")` |
| `declineButtonCornerRadius`    | Sets the corner radius for the decline button.                              | `CometChatOutgoingCall.style.declineButtonCornerRadius: CometChatCornerStyle?`           |
| `declineButtonBorderColor`     | Sets the border color for the decline button.                               | `CometChatOutgoingCall.style.declineButtonBorderColor: UIColor?`                         |
| `declineButtonBorderWidth`     | Sets the border width for the decline button.                               | `CometChatOutgoingCall.style.declineButtonBorderWidth: CGFloat?`                         |

***

### Functionality

These are small functional customizations that allow you to fine-tune the overall experience of the component.

| Property               | Description                             | Code                            |
| ---------------------- | --------------------------------------- | ------------------------------- |
| disableSoundForCalls   | Disables sound for outgoing calls.      | `disableSoundForCalls = true`   |
| setCustomSoundForCalls | Sets a custom sound for outgoing calls. | `set(customSoundForCalls: URL)` |

### Advanced

For advanced-level customization, you can set custom views to the component. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your own views, layouts, and UI elements and then incorporate those into the component.

#### SetAvatarView

With this function, you can assign a custom view to the avatar of the OutgoingCall Component.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatOutgoingCall.set(avatarView: { call in
        let customView = CustomAvatarView()
        return customView
    })
    ```
  </Tab>
</Tabs>

**Demonstration**

<Frame>
  <img alt="CometChatOutgoingCall with custom avatar view showing profile image with star badge overlay" />
</Frame>

You can create a `CustomAvatarView` as a custom `UIView`:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit

    class CustomAvatarView: UIView {
        
        private let imageView: UIImageView = {
            let imageView = UIImageView(image: UIImage(named: "user_profile")) // Replace with actual image
            imageView.contentMode = .scaleAspectFill
            imageView.layer.cornerRadius = 50
            imageView.layer.masksToBounds = true
            imageView.translatesAutoresizingMaskIntoConstraints = false
            return imageView
        }()
        
        private let badgeView: UIView = {
            let view = UIView()
            view.backgroundColor = .yellow
            view.layer.cornerRadius = 14
            view.translatesAutoresizingMaskIntoConstraints = false
            return view
        }()
        
        private let starIcon: UIImageView = {
            let imageView = UIImageView(image: UIImage(systemName: "star.fill"))
            imageView.tintColor = .white
            imageView.translatesAutoresizingMaskIntoConstraints = false
            return imageView
        }()
        
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupView()
        }
        
        required init?(coder: NSCoder) {
            super.init(coder: coder)
            setupView()
        }
        
        private func setupView() {
            translatesAutoresizingMaskIntoConstraints = false
            
            addSubview(imageView)
            addSubview(badgeView)
            badgeView.addSubview(starIcon)
            
            NSLayoutConstraint.activate([
                imageView.centerXAnchor.constraint(equalTo: centerXAnchor),
                imageView.centerYAnchor.constraint(equalTo: centerYAnchor),
                imageView.widthAnchor.constraint(equalToConstant: 100),
                imageView.heightAnchor.constraint(equalToConstant: 100),
                
                badgeView.trailingAnchor.constraint(equalTo: imageView.trailingAnchor, constant: 5),
                badgeView.bottomAnchor.constraint(equalTo: imageView.bottomAnchor, constant: 5),
                badgeView.widthAnchor.constraint(equalToConstant: 28),
                badgeView.heightAnchor.constraint(equalToConstant: 28),
                
                starIcon.centerXAnchor.constraint(equalTo: badgeView.centerXAnchor),
                starIcon.centerYAnchor.constraint(equalTo: badgeView.centerYAnchor),
                starIcon.widthAnchor.constraint(equalToConstant: 14),
                starIcon.heightAnchor.constraint(equalToConstant: 14)
            ])
        }
    }
    ```
  </Tab>
</Tabs>

***

#### SetCancelView

You can modify the cancel call view of the Outgoing call component using the property below:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatOutgoingCall.set(cancelView: { call in
        let view = CustomCancelView()
        return view
    })
    ```
  </Tab>
</Tabs>

**Demonstration**

<Frame>
  <img alt="CometChatOutgoingCall with custom cancel view showing red End Call button with phone icon" />
</Frame>

You can create a `CustomCancelView` as a custom `UIView`:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit

    class EndCallButton: UIButton {
        
        private let phoneIcon: UIImageView = {
            let imageView = UIImageView(image: UIImage(systemName: "phone.down.fill"))
            imageView.tintColor = .white
            imageView.translatesAutoresizingMaskIntoConstraints = false
            return imageView
        }()
        
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupView()
        }
        
        required init?(coder: NSCoder) {
            super.init(coder: coder)
            setupView()
        }
        
        private func setupView() {
            setTitle("End Call", for: .normal)
            setTitleColor(.white, for: .normal)
            backgroundColor = .red
            layer.cornerRadius = 10
            titleLabel?.font = UIFont.systemFont(ofSize: 18)
            translatesAutoresizingMaskIntoConstraints = false
            
            let stackView = UIStackView(arrangedSubviews: [phoneIcon, titleLabel!])
            stackView.axis = .horizontal
            stackView.spacing = 5
            stackView.alignment = .center
            stackView.translatesAutoresizingMaskIntoConstraints = false
            
            addSubview(stackView)
            
            NSLayoutConstraint.activate([
                stackView.centerXAnchor.constraint(equalTo: centerXAnchor),
                stackView.centerYAnchor.constraint(equalTo: centerYAnchor)
            ])
            
            addTarget(self, action: #selector(endCallTapped), for: .touchUpInside)
        }
        
        @objc private func endCallTapped() {
            print("Call Ended")
        }
    }
    ```
  </Tab>
</Tabs>

***

#### SetTitleView

You can customize the title view of the outgoing call component using the property below:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatOutgoingCall.set(titleView: { call in
        let view = CustomTitleView()
        view.configure(call: call)
        return view
    })
    ```
  </Tab>
</Tabs>

**Demonstration**

<Frame>
  <img alt="CometChatOutgoingCall with custom title view showing call initiator and receiver names" />
</Frame>

You can create a `CustomTitleView` as a custom `UIView`:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit

    class CustomTitleView: UILabel {
        
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupView()
        }
        
        required init?(coder: NSCoder) {
            super.init(coder: coder)
            setupView()
        }
        
        private func setupView() {
            font = UIFont.boldSystemFont(ofSize: 22)
            textAlignment = .center
            translatesAutoresizingMaskIntoConstraints = false
        }

        func configure(call: Call) {
            text = "\(call.callInitiator) <> \(call.receiver)"
        }
    }
    ```
  </Tab>
</Tabs>

***

#### SetSubtitleView

You can modify the subtitle view of the outgoing call component using the property below:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatOutgoingCall.set(subtitleView: { call in
        let view = CustomSubtitleView()
        return view
    })
    ```
  </Tab>
</Tabs>

**Demonstration**

<Frame>
  <img alt="CometChatOutgoingCall with custom subtitle view showing phone icon and Calling status text" />
</Frame>

You can create a `CustomSubtitleView` as a custom `UIView`:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import UIKit

    class CustomSubtitleView: UIStackView {
        
        private let phoneIcon: UIImageView = {
            let imageView = UIImageView(image: UIImage(systemName: "phone.fill"))
            imageView.tintColor = .gray
            imageView.translatesAutoresizingMaskIntoConstraints = false
            return imageView
        }()
        
        private let callingLabel: UILabel = {
            let label = UILabel()
            label.text = "Calling..."
            label.textColor = .gray
            label.font = UIFont.systemFont(ofSize: 18)
            label.translatesAutoresizingMaskIntoConstraints = false
            return label
        }()
        
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupView()
        }
        
        required init(coder: NSCoder) {
            super.init(coder: coder)
            setupView()
        }
        
        private func setupView() {
            axis = .horizontal
            spacing = 5
            alignment = .center
            translatesAutoresizingMaskIntoConstraints = false
            
            addArrangedSubview(phoneIcon)
            addArrangedSubview(callingLabel)
        }
    }
    ```
  </Tab>
</Tabs>

***

## Props

All props are optional unless noted.

***

### call

The outgoing call object to display.

|         |             |
| ------- | ----------- |
| Type    | `Call`      |
| Default | `undefined` |

***

### disableSoundForCalls

Disables the outgoing call ringtone.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

***

### customSoundForCalls

Custom sound file URL for outgoing calls.

|         |        |
| ------- | ------ |
| Type    | `URL?` |
| Default | `nil`  |

***

### avatarStyle

Customizes the appearance of the recipient's avatar.

|         |                 |
| ------- | --------------- |
| Type    | `AvatarStyle`   |
| Default | `AvatarStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let customAvatarStyle = AvatarStyle()
customAvatarStyle.backgroundColor = UIColor.systemOrange
customAvatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)

let outgoingCall = CometChatOutgoingCall()
outgoingCall.avatarStyle = customAvatarStyle
```

***

## Events

Events emitted by the Outgoing Call component:

| Event                    | Description                                                  |
| ------------------------ | ------------------------------------------------------------ |
| `onOutgoingCallAccepted` | Triggers when the outgoing call is accepted by the recipient |
| `onOutgoingCallRejected` | Triggers when the outgoing call is rejected by the recipient |

***

## View Slots

| Slot           | Signature          | Replaces           |
| -------------- | ------------------ | ------------------ |
| `avatarView`   | `(Call) -> UIView` | Recipient avatar   |
| `cancelView`   | `(Call) -> UIView` | Cancel call button |
| `titleView`    | `(Call) -> UIView` | Recipient name     |
| `subtitleView` | `(Call) -> UIView` | "Calling..." text  |
| `leadingView`  | `(Call) -> UIView` | Left section       |
| `trailingView` | `(Call) -> UIView` | Right section      |

### leadingView

You can customize the leading view of an outgoing call component using the property below.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatOutgoingCall.set(leadingView: { call in
        let view = CustomLeadingView()
        return view
    })
    ```
  </Tab>
</Tabs>

### trailingView

You can customize the trailing view of an outgoing call component using the property below.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    cometChatOutgoingCall.set(trailingView: { call in
        let view = CustomTrailingView()
        return view
    })
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Initiate Call and Present Outgoing Screen

Start a call and show the outgoing call interface:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    func initiateCall(to user: User, callType: CometChat.CallType) {
        let call = Call(receiverId: user.uid ?? "", callType: callType, receiverType: .user)
        
        CometChat.initiateCall(call: call) { [weak self] initiatedCall in
            guard let initiatedCall = initiatedCall else { return }
            DispatchQueue.main.async {
                let outgoingCall = CometChatOutgoingCall()
                outgoingCall.set(call: initiatedCall)
                outgoingCall.modalPresentationStyle = .fullScreen
                self?.present(outgoingCall, animated: true)
            }
        } onError: { error in
            print("Call initiation failed: \(error?.errorDescription ?? "")")
        }
    }
    ```
  </Tab>
</Tabs>

### Handle Call Acceptance and Transition to Ongoing Call

Navigate to ongoing call when the recipient accepts:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Subscribe to call events
    CometChatCallEvents.addListener("outgoing_call_listener", self as CometChatCallEventListener)

    // In CometChatCallEventListener extension
    func onOutgoingCallAccepted(call: Call) {
        DispatchQueue.main.async { [weak self] in
            self?.dismiss(animated: false) {
                let ongoingCall = CometChatOngoingCall()
                ongoingCall.set(sessionId: call.sessionId ?? "")
                ongoingCall.modalPresentationStyle = .fullScreen
                self?.present(ongoingCall, animated: true)
            }
        }
    }
    ```
  </Tab>
</Tabs>

### Custom Cancel Action with Confirmation

Show confirmation before canceling an outgoing call:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let outgoingCall = CometChatOutgoingCall()
    outgoingCall.set(call: call)
    outgoingCall.set(onCancelClick: { [weak self] call, controller in
        let alert = UIAlertController(
            title: "Cancel Call",
            message: "Are you sure you want to cancel this call?",
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "No", style: .cancel))
        alert.addAction(UIAlertAction(title: "Yes", style: .destructive) { _ in
            CometChat.rejectCall(sessionID: call.sessionId ?? "", status: .cancelled) { _ in
                controller.dismiss(animated: true)
            } onError: { error in
                print("Failed to cancel: \(error?.errorDescription ?? "")")
            }
        })
        controller.present(alert, animated: true)
    })
    ```
  </Tab>
</Tabs>

***

## Related Components

<CardGroup>
  <Card title="Incoming Call" href="/ui-kit/ios/incoming-call">
    Display incoming call interface
  </Card>

  <Card title="Ongoing Call" href="/ui-kit/ios/ongoing-call">
    Display active call interface
  </Card>

  <Card title="Call Logs" href="/ui-kit/ios/call-logs">
    Display call history
  </Card>
</CardGroup>


# Search
Source: https://www.cometchat.com/docs/ui-kit/ios/search

Search CometChat iOS UI Kit conversations and messages with filters, scoped results, request builders, and selection callbacks.

The `CometChatSearch` component is a powerful and customizable search interface that allows users to search across conversations and messages in real time. It supports a wide variety of filters, scopes, and customization options.

<Frame>
  <img alt="CometChatSearch showing the search interface with search bar, filter options, and search results displaying conversations and messages" />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatSearch",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "description": "Provides search functionality across conversations and messages",
    "inherits": "UIViewController",
    "primaryOutput": {
      "callback": "onMessageClicked",
      "type": "(BaseMessage) -> Void"
    },
    "props": {
      "data": {
        "user": { "type": "User?", "default": "nil", "note": "Limits search to specific user" },
        "group": { "type": "Group?", "default": "nil", "note": "Limits search to specific group" },
        "conversationsRequestBuilder": { "type": "ConversationsRequest.ConversationsRequestBuilder", "default": "SDK default" },
        "messagesRequestBuilder": { "type": "MessagesRequest.MessageRequestBuilder", "default": "SDK default" }
      },
      "callbacks": {
        "onConversationClicked": "(Conversation, IndexPath) -> Void",
        "onMessageClicked": "(BaseMessage) -> Void",
        "onBack": "() -> Void",
        "onError": "(CometChatException) -> Void",
        "onEmpty": "() -> Void"
      },
      "visibility": {
        "hideNavigationBar": { "type": "Bool", "default": false },
        "hideBackButton": { "type": "Bool", "default": false },
        "hideUserStatus": { "type": "Bool", "default": false },
        "hideGroupType": { "type": "Bool", "default": false },
        "hideReceipts": { "type": "Bool", "default": false }
      },
      "search": {
        "searchFilters": { "type": "[SearchFilter]", "default": "All available filters" },
        "initialSearchFilter": { "type": "SearchFilter?", "default": "nil" },
        "searchIn": { "type": "[SearchScope]", "default": "[.conversations, .messages]" }
      },
      "viewSlots": {
        "listItemViewForConversation": "(Conversation) -> UIView",
        "leadingViewForConversation": "(Conversation) -> UIView",
        "titleViewForConversation": "(Conversation) -> UIView",
        "subtitleViewForConversation": "(Conversation) -> UIView",
        "tailViewForConversation": "(Conversation) -> UIView",
        "listItemViewForMessage": "(BaseMessage) -> UIView",
        "leadingViewForMessage": "(BaseMessage) -> UIView",
        "titleViewForMessage": "(BaseMessage) -> UIView",
        "subtitleViewForMessage": "(BaseMessage) -> UIView",
        "trailingViewForMessage": "(BaseMessage) -> UIView",
        "initialView": "UIView",
        "loadingView": "UIView",
        "emptyView": "UIView",
        "errorView": "UIView"
      }
    },
    "events": [],
    "sdkListeners": [],
    "compositionExample": {
      "description": "Search is typically accessed from conversation list or message header",
      "components": ["CometChatConversations", "CometChatSearch", "CometChatMessages"],
      "flow": "User taps search → enters query → taps result → navigates to conversation/message"
    }
  }
  ```
</Accordion>

| Field     | Value                 |
| --------- | --------------------- |
| Component | `CometChatSearch`     |
| Package   | `CometChatUIKitSwift` |
| Inherits  | `UIViewController`    |

***

## Usage

### Integration

`CometChatSearch` is a composite component that offers flexible integration options. It can be launched directly via button clicks or any user-triggered action.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let search = CometChatSearch()
    self.navigationController?.pushViewController(search, animated: true)
    ```
  </Tab>
</Tabs>

***

### Actions

[Actions](/docs/ui-kit/ios/components-overview#actions) dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type to tailor the behavior to fit your specific needs.

#### 1. onConversationClicked

Triggered when you click on a Conversation from the search result. This action doesn't have a predefined behavior—you can override it using the following code snippet:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let search = CometChatSearch()
    search.onConversationClicked = { conversation, indexPath in
        print("Conversation clicked:", conversation.conversationId)
    }
    ```
  </Tab>
</Tabs>

***

#### 2. onMessageClicked

Triggered when you click on a Message from the search result. This action doesn't have a predefined behavior—you can override it using the following code snippet:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let search = CometChatSearch()
    search.onMessageClicked = { message in
        print("Message clicked:", message.id)
    }
    ```
  </Tab>
</Tabs>

***

#### 3. onBack

Triggered when you click on the back button of the search component.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let search = CometChatSearch()
    search.onBack = {
        self.navigationController?.popViewController(animated: true)
    }
    ```
  </Tab>
</Tabs>

***

#### 4. onError

Listens for any errors that occur in the Search component. This action doesn't change the component's behavior.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let search = CometChatSearch()
    search.set(onError: { error in
        print("Search error:", error.localizedDescription)
    })
    ```
  </Tab>
</Tabs>

***

#### 5. onEmpty

Listens for the empty state of the Search component. This action doesn't change the component's behavior.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let search = CometChatSearch()
    search.set(onEmpty: {
        print("No results found")
    })
    ```
  </Tab>
</Tabs>

***

### Filters

Filters allow you to customize the data displayed in a list within a Component. You can filter the list based on your specific criteria using RequestBuilders of the Chat SDK.

#### SearchScope

The `SearchScope` enum defines what types of content to search:

| Value            | Description             |
| ---------------- | ----------------------- |
| `.conversations` | Search in conversations |
| `.messages`      | Search in messages      |

```swift lines theme={null}
import CometChatUIKitSwift

let search = CometChatSearch()

// Search only in messages
search.set(searchIn: [.messages])

// Search in both conversations and messages (default)
search.set(searchIn: [.conversations, .messages])
```

#### SearchFilter

The `SearchFilter` enum defines available filter options:

| Value        | Description                   |
| ------------ | ----------------------------- |
| `.unread`    | Filter by unread items        |
| `.groups`    | Filter by group conversations |
| `.photos`    | Filter by photo messages      |
| `.videos`    | Filter by video messages      |
| `.links`     | Filter by link messages       |
| `.documents` | Filter by document messages   |
| `.audio`     | Filter by audio messages      |

```swift lines theme={null}
import CometChatUIKitSwift

let search = CometChatSearch()

// Set available filters with an initial selection
search.set(searchFilters: [.unread, .groups, .photos, .videos], initialFilter: .photos)
```

#### 1. ConversationsRequestBuilder

Set the `ConversationsRequestBuilder` in the Search Component to filter the search results. For more options, refer to [ConversationRequestBuilder](/docs/sdk/ios/retrieve-conversations).

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift
    import CometChatSDK

    let convBuilder = ConversationsRequest.ConversationsRequestBuilder()
        .set(limit: 20)

    let search = CometChatSearch()
    search.set(conversationsRequestBuilder: convBuilder)
    ```
  </Tab>
</Tabs>

***

#### 2. MessagesRequestBuilder

Set the `MessagesRequestBuilder` in the Search Component to filter the search results. For more options, refer to [MessagesRequestBuilder](/docs/sdk/ios/additional-message-filtering).

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift
    import CometChatSDK

    let msgBuilder = MessagesRequest.MessageRequestBuilder()
        .set(limit: 30)
        .hide(deletedMessages: true)

    let search = CometChatSearch()
    search.set(messagesRequestBuilder: msgBuilder)
    ```
  </Tab>
</Tabs>

***

### Events

[Events](/docs/ui-kit/ios/components-overview#events) are emitted by a Component. By using events, you can extend existing functionality. Being global events, they can be applied in multiple locations and can be added or removed as needed.

The `CometChatSearch` component does not produce any events.

***

## Customization

To fit your app's design requirements, you can customize the appearance of the `CometChatSearch` component. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.

### Style

Using Style, you can customize the look and feel of the component in your app. These parameters typically control elements such as the color, size, shape, and fonts used within the component.

<Frame>
  <img alt="CometChatSearch with custom styling showing modified background color, list item styling, and custom fonts applied" />
</Frame>

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    // Instance-level styling
    let style = SearchStyle()
    style.backgroundColor = UIColor(hex: "#EDEAFA")
    style.listItemBackground = UIColor(hex: "#EDEAFA")
    style.listItemTitleFont = UIFont(name: "TimesNewRomanPS-Regular", size: 16)
    style.titleFont = UIFont(name: "TimesNewRomanPS-Bold", size: 12)
    style.searchBarPlaceholderTextFont = UIFont(name: "TimesNewRomanPS-Regular", size: 12)

    let searchVC = CometChatSearch()
    searchVC.style = style
    self?.navigationController?.pushViewController(searchVC, animated: true)

    // Global-level styling
    CometChatSearch.style.backgroundColor = UIColor(hex: "#EDEAFA")
    CometChatSearch.style.listItemBackground = UIColor(hex: "#EDEAFA")
    CometChatSearch.style.listItemTitleFont = UIFont(name: "TimesNewRomanPS-Regular", size: 16)
    CometChatSearch.style.titleFont = UIFont(name: "TimesNewRomanPS-Bold", size: 12)
    CometChatSearch.style.searchBarPlaceholderTextFont = UIFont(name: "TimesNewRomanPS-Regular", size: 12)
    ```
  </Tab>
</Tabs>

***

### Functionality

These are small functional customizations that allow you to fine-tune the overall experience of the component. With these, you can toggle the visibility of UI elements.

| Property                | Description                                      | Example                                                    |
| ----------------------- | ------------------------------------------------ | ---------------------------------------------------------- |
| user                    | Restrict search to a specific user chat          | `search.user = user`                                       |
| group                   | Restrict search to a group                       | `search.group = group`                                     |
| hideUserStatus          | Hide online/offline indicator                    | `search.hideUserStatus = true`                             |
| hideGroupType           | Hide group type icon                             | `search.hideGroupType = true`                              |
| hideBackButton          | Hide the back button                             | `search.hideBackButton = true`                             |
| hideReceipts            | Hide message read/delivery receipt indicators    | `search.hideReceipts = true`                               |
| searchFilters           | Filters like "Unread", "Groups", "Photos", etc.  | `search.set(searchFilters: [.unread, .groups, .photos])`   |
| initialSearchFilter     | Default filter to apply on load                  | `search.set(searchFilters: [...], initialFilter: .photos)` |
| searchIn (searchScopes) | Restrict search: messages / conversations / both | `search.set(searchIn: [.messages, .conversations])`        |
| loadingView             | Custom loader view                               | `search.set(loadingView: spinner)`                         |
| emptyView               | Custom empty result view                         | `search.set(emptyView: emptyView)`                         |
| errorView               | Custom error UI                                  | `search.set(errorView: errorView)`                         |
| initialView             | Custom view before search query is entered       | `search.set(initialView: initialView)`                     |
| disableTyping           | Disable typing indicators                        | `search.disableTyping = true`                              |
| disableSoundForMessages | Disable message sounds                           | `search.disableSoundForMessages = true`                    |
| customSoundForMessages  | Custom sound URL for messages                    | `search.customSoundForMessages = URL(string: "...")`       |

***

### Advanced

For advanced-level customization, you can set custom views to the component. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your own views, layouts, and UI elements and then incorporate those into the component.

#### Conversation View Customization

| Function                    | Description                                       |
| --------------------------- | ------------------------------------------------- |
| listItemViewForConversation | Assign a custom list item view to a conversation. |
| leadingViewForConversation  | Assign a custom leading view to a conversation.   |
| titleViewForConversation    | Assign a custom title view to a conversation.     |
| subtitleViewForConversation | Assign a custom subtitle view to a conversation.  |
| tailViewForConversation     | Assign a custom trailing view to a conversation.  |

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let searchVC = CometChatSearch()

    searchVC.set(listItemViewForConversation: { conversation in
        let customView = UIView()
        // Configure custom conversation view
        return customView
    })
    ```
  </Tab>
</Tabs>

#### Message View Customization

With message item view functions, you can assign custom views to different types of messages in the search result. For more information, refer to the [itemView](/docs/ui-kit/ios/message-list#itemview) prop of the `CometChatMessages` component.

Here's how you can override the default message item view with a custom one for text messages:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let searchVC = CometChatSearch()
    searchVC.set(listItemViewForMessage: { message in
        return SearchMessageItemView()
    })
    ```
  </Tab>
</Tabs>

<Frame>
  <img alt="CometChatSearch with custom message item view showing sender name and message text in a customized layout with purple accent styling" />
</Frame>

Custom view implementation:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    class SearchMessageItemView: UIView {

        // MARK: - UI Components
        
        private let containerView: UIView = {
            let view = UIView()
            view.backgroundColor = UIColor(red: 0.95, green: 0.93, blue: 0.98, alpha: 1.0)
            return view
        }()
        
        private let senderLabel: UILabel = {
            let label = UILabel()
            label.font = UIFont.boldSystemFont(ofSize: 16)
            label.textColor = UIColor(red: 0.37, green: 0.22, blue: 0.73, alpha: 1.0)
            return label
        }()
        
        private let messageLabel: UILabel = {
            let label = UILabel()
            label.font = UIFont.systemFont(ofSize: 16)
            label.textColor = UIColor.darkGray
            label.numberOfLines = 1
            label.lineBreakMode = .byTruncatingTail
            return label
        }()
        
        private let bottomLine: UIView = {
            let view = UIView()
            view.backgroundColor = UIColor(red: 0.37, green: 0.22, blue: 0.73, alpha: 1.0)
            return view
        }()
        
        private let stack: UIStackView = {
            let stack = UIStackView()
            stack.axis = .horizontal
            stack.spacing = 4
            stack.alignment = .center
            return stack
        }()
        
        // MARK: - Initialization
        
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupUI()
        }
        
        required init?(coder: NSCoder) {
            super.init(coder: coder)
            setupUI()
        }
        
        // MARK: - Setup
        
        private func setupUI() {
            addSubview(containerView)
            containerView.translatesAutoresizingMaskIntoConstraints = false
            
            containerView.addSubview(stack)
            stack.translatesAutoresizingMaskIntoConstraints = false
            
            containerView.addSubview(bottomLine)
            bottomLine.translatesAutoresizingMaskIntoConstraints = false
            
            stack.addArrangedSubview(senderLabel)
            stack.addArrangedSubview(messageLabel)

            NSLayoutConstraint.activate([
                containerView.topAnchor.constraint(equalTo: topAnchor),
                containerView.leadingAnchor.constraint(equalTo: leadingAnchor),
                containerView.trailingAnchor.constraint(equalTo: trailingAnchor),
                containerView.bottomAnchor.constraint(equalTo: bottomAnchor),
                
                stack.topAnchor.constraint(equalTo: containerView.topAnchor, constant: 12),
                stack.leadingAnchor.constraint(equalTo: containerView.leadingAnchor, constant: 12),
                stack.trailingAnchor.constraint(equalTo: containerView.trailingAnchor, constant: -12),
                
                bottomLine.heightAnchor.constraint(equalToConstant: 2),
                bottomLine.leadingAnchor.constraint(equalTo: containerView.leadingAnchor),
                bottomLine.trailingAnchor.constraint(equalTo: containerView.trailingAnchor),
                bottomLine.bottomAnchor.constraint(equalTo: containerView.bottomAnchor)
            ])
        }
        
        // MARK: - Configuration
        
        /// Configure view with sender name and message text
        /// - Parameters:
        ///   - sender: The sender's name
        ///   - message: The message content
        ///   - boldKeyword: Optional keyword to highlight in bold
        func configure(sender: String, message: String, boldKeyword: String?) {
            senderLabel.text = sender + ":"
            
            if let keyword = boldKeyword, message.contains(keyword) {
                let attributed = NSMutableAttributedString(string: message)
                let range = (message as NSString).range(of: keyword)
                attributed.addAttribute(.font, value: UIFont.boldSystemFont(ofSize: 16), range: range)
                messageLabel.attributedText = attributed
            } else {
                messageLabel.text = message
            }
        }
    }
    ```
  </Tab>
</Tabs>

Available message item view functions for customization:

| Function                | Message Type     |
| ----------------------- | ---------------- |
| listItemViewForMessage  | Text Message     |
| listItemViewForImage    | Image Message    |
| listItemViewForVideo    | Video Message    |
| listItemViewForAudio    | Audio Message    |
| listItemViewForDocument | Document Message |
| listItemViewForLink     | Link Message     |

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let searchVC = CometChatSearch()

    // Custom view for image messages
    searchVC.set(listItemViewForImage: { mediaMessage in
        let customView = UIView()
        // Configure custom image message view
        return customView
    })

    // Custom view for video messages
    searchVC.set(listItemViewForVideo: { mediaMessage in
        let customView = UIView()
        // Configure custom video message view
        return customView
    })

    // Custom view for audio messages
    searchVC.set(listItemViewForAudio: { mediaMessage in
        let customView = UIView()
        // Configure custom audio message view
        return customView
    })

    // Custom view for document messages
    searchVC.set(listItemViewForDocument: { mediaMessage in
        let customView = UIView()
        // Configure custom document message view
        return customView
    })

    // Custom view for link messages
    searchVC.set(listItemViewForLink: { mediaMessage in
        let customView = UIView()
        // Configure custom link message view
        return customView
    })
    ```
  </Tab>
</Tabs>

#### Message Granular View Customization

For more granular control over message search results, you can customize individual parts of the message item:

| Function               | Description                                |
| ---------------------- | ------------------------------------------ |
| leadingViewForMessage  | Replaces the message avatar / left section |
| titleViewForMessage    | Replaces the message title text            |
| subtitleViewForMessage | Replaces the message subtitle text         |
| trailingViewForMessage | Replaces the message trailing section      |

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let searchVC = CometChatSearch()

    // Custom leading view for messages (avatar area)
    searchVC.set(leadingViewForMessage: { message in
        let customView = UIView()
        customView.backgroundColor = .systemPurple
        customView.layer.cornerRadius = 24
        // Configure custom leading view
        return customView
    })

    // Custom title view for messages
    searchVC.set(titleViewForMessage: { message in
        let label = UILabel()
        label.text = message.sender?.name ?? "Unknown"
        label.font = .boldSystemFont(ofSize: 16)
        return label
    })

    // Custom subtitle view for messages
    searchVC.set(subtitleViewForMessage: { message in
        let label = UILabel()
        if let textMessage = message as? TextMessage {
            label.text = textMessage.text
        } else {
            label.text = message.type
        }
        label.textColor = .secondaryLabel
        return label
    })

    // Custom trailing view for messages
    searchVC.set(trailingViewForMessage: { message in
        let label = UILabel()
        let date = Date(timeIntervalSince1970: TimeInterval(message.sentAt))
        let formatter = DateFormatter()
        formatter.dateFormat = "HH:mm"
        label.text = formatter.string(from: date)
        label.font = .systemFont(ofSize: 12)
        label.textColor = .tertiaryLabel
        return label
    })
    ```
  </Tab>
</Tabs>

#### Initial View

Customize the view displayed before the user enters a search query using the `initialView` property.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let searchVC = CometChatSearch()

    // Create a custom initial view
    let initialView = UIView()
    let imageView = UIImageView(image: UIImage(systemName: "magnifyingglass"))
    imageView.tintColor = .systemGray
    imageView.contentMode = .scaleAspectFit
    imageView.translatesAutoresizingMaskIntoConstraints = false

    let label = UILabel()
    label.text = "Search for conversations and messages"
    label.textColor = .secondaryLabel
    label.textAlignment = .center
    label.translatesAutoresizingMaskIntoConstraints = false

    initialView.addSubview(imageView)
    initialView.addSubview(label)

    NSLayoutConstraint.activate([
        imageView.centerXAnchor.constraint(equalTo: initialView.centerXAnchor),
        imageView.centerYAnchor.constraint(equalTo: initialView.centerYAnchor, constant: -20),
        imageView.widthAnchor.constraint(equalToConstant: 60),
        imageView.heightAnchor.constraint(equalToConstant: 60),
        label.topAnchor.constraint(equalTo: imageView.bottomAnchor, constant: 16),
        label.leadingAnchor.constraint(equalTo: initialView.leadingAnchor, constant: 20),
        label.trailingAnchor.constraint(equalTo: initialView.trailingAnchor, constant: -20)
    ])

    searchVC.set(initialView: initialView)
    ```
  </Tab>
</Tabs>

***

#### Mention Configuration

Configure how @all mentions appear in search results using the `setMentionAllLabel` method.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let searchVC = CometChatSearch()

    // Set a custom label for @all mentions
    searchVC.setMentionAllLabel("all", "Everyone")
    ```
  </Tab>
</Tabs>

***

#### DateTime Formatters

By providing a custom implementation of the DateTimeFormatterCallback, you can configure how time and date values are displayed. This ensures consistent formatting for labels such as "Today", "Yesterday", "X minutes ago", and more.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import CometChatUIKitSwift

    let searchVC = CometChatSearch()

    searchVC.dateTimeFormatter.today = { timestamp in
        return "Today • \(formattedTime(timestamp))"
    }

    searchVC.dateTimeFormatter.otherDay = { timestamp in
        let df = DateFormatter()
        df.dateFormat = "dd MMM yyyy"
        return df.string(from: Date(timeIntervalSince1970: timestamp))
    }
    ```
  </Tab>
</Tabs>

***

#### Text Formatters

The `setTextFormatters` method enables developers to define and apply text formatters that dynamically modify or transform message content before rendering it in the UI. Text formatters can be used for:

* Automatically converting URLs into clickable links
* Applying Markdown or rich text styling
* Replacing certain words or patterns with emojis or predefined text
* Censoring specific words for moderation

By utilizing this method, developers can enhance readability, usability, and compliance with content guidelines. See the [MentionsFormatter Guide](/docs/ui-kit/ios/mentions-formatter-guide) for more details.

***

## Common Patterns

### Present Search from Conversations

Open the search screen from a conversations list:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    @objc func openSearch() {
        let searchVC = CometChatSearch()
        
        searchVC.onConversationClicked = { [weak self] conversation, indexPath in
            // Navigate to messages for the selected conversation
            let messagesVC = CometChatMessages()
            if let user = conversation.conversationWith as? User {
                messagesVC.user = user
            } else if let group = conversation.conversationWith as? Group {
                messagesVC.group = group
            }
            self?.navigationController?.pushViewController(messagesVC, animated: true)
        }
        
        searchVC.onMessageClicked = { [weak self] message in
            // Navigate to the message in context
            let messagesVC = CometChatMessages()
            if let user = message.sender {
                messagesVC.user = user
            }
            self?.navigationController?.pushViewController(messagesVC, animated: true)
        }
        
        navigationController?.pushViewController(searchVC, animated: true)
    }
    ```
  </Tab>
</Tabs>

### Search Within a Specific Conversation

Limit search to messages within a specific user or group chat:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Search within a specific user's conversation
    let searchVC = CometChatSearch()
    searchVC.user = user
    searchVC.set(searchIn: [.messages])  // Only search messages, not conversations

    // Or search within a group
    let groupSearchVC = CometChatSearch()
    groupSearchVC.group = group
    groupSearchVC.set(searchIn: [.messages])
    ```
  </Tab>
</Tabs>

### Filter Search by Media Type

Show only photo or video messages in search results:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let searchVC = CometChatSearch()

    // Set available filters with photos as the initial selection
    searchVC.set(searchFilters: [.photos, .videos, .documents, .audio], initialFilter: .photos)

    // Or programmatically filter messages
    let msgBuilder = MessagesRequest.MessageRequestBuilder()
        .set(categories: ["message"])
        .set(types: ["image", "video"])

    searchVC.set(messagesRequestBuilder: msgBuilder)
    ```
  </Tab>
</Tabs>

### Custom Search Result Actions

Handle search result selection with custom actions:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let searchVC = CometChatSearch()

    searchVC.onMessageClicked = { [weak self] message in
        // Show action sheet for the selected message
        let alert = UIAlertController(title: nil, message: nil, preferredStyle: .actionSheet)
        
        alert.addAction(UIAlertAction(title: "Go to Message", style: .default) { _ in
            self?.navigateToMessage(message)
        })
        
        alert.addAction(UIAlertAction(title: "Reply", style: .default) { _ in
            self?.replyToMessage(message)
        })
        
        alert.addAction(UIAlertAction(title: "Forward", style: .default) { _ in
            self?.forwardMessage(message)
        })
        
        alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
        
        self?.present(alert, animated: true)
    }
    ```
  </Tab>
</Tabs>

***

## Related Components

<CardGroup>
  <Card title="Conversations" href="/ui-kit/ios/conversations">
    Display conversation list
  </Card>

  <Card title="Message List" href="/ui-kit/ios/message-list">
    Display chat messages
  </Card>

  <Card title="Users" href="/ui-kit/ios/users">
    Display user list
  </Card>
</CardGroup>


# ShortCut Formatter
Source: https://www.cometchat.com/docs/ui-kit/ios/shortcut-formatter-guide

Implement message shortcuts using the ShortCutFormatter class in CometChat UI Kit for iOS

## Introduction

The `ShortCutFormatter` class extends the `CometChatTextFormatter` class to provide a mechanism for handling shortcuts within messages. This guide walks you through the process of using `ShortCutFormatter` to implement shortcut extensions in your CometChat application.

***

## Setup

### 1. Create the ShortCutFormatter Class

Define the `ShortCutFormatter` class by extending the `CometChatTextFormatter` class:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    class ShortcutFormatter: CometChatTextFormatter {
        
        // Store fetched shortcuts from the extension
        private var messageShortcuts: [String: String] = [:]
        
        // Store suggestion items for display
        private var shortcuts: [CometChatUIKitSwift.SuggestionItem] = []
    }
    ```
  </Tab>
</Tabs>

### 2. Initialize with Tracking Character

Set the `trackingCharacter` to `'!'` in the initializer:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    override init(trackingCharacter: Character) {
        super.init(trackingCharacter: "!")
    }
    ```
  </Tab>
</Tabs>

### 3. Define the Regex Pattern

Set the regular expression for shortcut detection in the `getRegex()` method:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    override func getRegex() -> String {
        return "(^|\\s)!\\w+"
    }
    ```
  </Tab>
</Tabs>

### 4. Return the Tracking Character

Define the `getTrackingCharacter()` method to return `'!'` as the shortcut tracking character:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    override func getTrackingCharacter() -> Character {
        return "!"
    }
    ```
  </Tab>
</Tabs>

### 5. Implement the Search Method

Override the `search()` method to search for shortcuts based on the entered query:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    override func search(string: String, suggestedItems: (([CometChatUIKitSwift.SuggestionItem]) -> ())? = nil) {
        
        // Fetch shortcuts from extension if not already cached
        if messageShortcuts.isEmpty {
            CometChat.callExtension(
                slug: "message-shortcuts",
                type: .get,
                endPoint: "v1/fetch",
                body: nil
            ) { [weak self] extensionResponseData in
                guard let self = self else { return }
                
                if let shortcutData = extensionResponseData?["shortcuts"] as? [String: String] {
                    self.messageShortcuts = shortcutData
                    
                    // Filter shortcuts matching the search string
                    let suggestedItemsList = self.messageShortcuts
                        .filter { $0.key.hasPrefix(string) }
                        .map { CometChatUIKitSwift.SuggestionItem(id: $0.key, name: $0.value, visibleText: $0.value) }
                    
                    suggestedItems?(suggestedItemsList)
                }
            } onError: { error in
                print("Error occurred while fetching shortcuts: \(error?.errorDescription ?? "Unknown error")")
            }
        } else {
            // Use cached shortcuts
            let suggestedItemsList = messageShortcuts
                .filter { $0.key.hasPrefix(string) }
                .map { CometChatUIKitSwift.SuggestionItem(id: $0.key, name: $0.value, visibleText: $0.value) }
            
            suggestedItems?(suggestedItemsList)
        }
    }
    ```
  </Tab>
</Tabs>

### 6. Handle Message String Preparation

Implement the `prepareMessageString()` method to convert the base chat message into an attributed string for display:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    override func prepareMessageString(
        baseMessage: BaseMessage,
        regexString: String,
        alignment: MessageBubbleAlignment = .left,
        formattingType: FormattingType
    ) -> NSAttributedString {
        let message = (baseMessage as? TextMessage)?.text ?? ""
        return NSAttributedString(string: message)
    }
    ```
  </Tab>
</Tabs>

### 7. Handle Text Tap Events

Override the `onTextTapped()` method if you need to handle tap events on formatted text:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    override func onTextTapped(baseMessage: BaseMessage, tappedText: String, controller: UIViewController?) {
        // Handle tap event on shortcut text
    }
    ```
  </Tab>
</Tabs>

***

## Complete Implementation

Here's the complete `ShortcutFormatter` class:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    import Foundation
    import CometChatSDK
    import CometChatUIKitSwift

    class ShortcutFormatter: CometChatTextFormatter {
        
        // MARK: - Properties
        
        private var messageShortcuts: [String: String] = [:]
        private var shortcuts: [CometChatUIKitSwift.SuggestionItem] = []
        
        // MARK: - Initialization
        
        override init(trackingCharacter: Character) {
            super.init(trackingCharacter: "!")
        }
        
        // MARK: - Override Methods
        
        override func getRegex() -> String {
            return "(^|\\s)!\\w+"
        }
        
        override func getTrackingCharacter() -> Character {
            return "!"
        }
        
        override func search(string: String, suggestedItems: (([CometChatUIKitSwift.SuggestionItem]) -> ())? = nil) {
            
            if messageShortcuts.isEmpty {
                CometChat.callExtension(
                    slug: "message-shortcuts",
                    type: .get,
                    endPoint: "v1/fetch",
                    body: nil
                ) { [weak self] extensionResponseData in
                    guard let self = self else { return }
                    
                    if let shortcutData = extensionResponseData?["shortcuts"] as? [String: String] {
                        self.messageShortcuts = shortcutData
                        
                        let suggestedItemsList = self.messageShortcuts
                            .filter { $0.key.hasPrefix(string) }
                            .map { CometChatUIKitSwift.SuggestionItem(id: $0.key, name: $0.value, visibleText: $0.value) }
                        
                        suggestedItems?(suggestedItemsList)
                    }
                } onError: { error in
                    print("Error occurred while fetching shortcuts: \(error?.errorDescription ?? "Unknown error")")
                }
            } else {
                let suggestedItemsList = messageShortcuts
                    .filter { $0.key.hasPrefix(string) }
                    .map { CometChatUIKitSwift.SuggestionItem(id: $0.key, name: $0.value, visibleText: $0.value) }
                
                suggestedItems?(suggestedItemsList)
            }
        }
        
        override func prepareMessageString(
            baseMessage: BaseMessage,
            regexString: String,
            alignment: MessageBubbleAlignment = .left,
            formattingType: FormattingType
        ) -> NSAttributedString {
            let message = (baseMessage as? TextMessage)?.text ?? ""
            return NSAttributedString(string: message)
        }
        
        override func onTextTapped(baseMessage: BaseMessage, tappedText: String, controller: UIViewController?) {
            // Handle tap event on shortcut text
        }
    }
    ```
  </Tab>
</Tabs>

***

## Usage

### 1. Initialize the Formatter

Create an instance of `ShortCutFormatter`:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let shortcutFormatter = ShortcutFormatter(trackingCharacter: "!")
    ```
  </Tab>
</Tabs>

### 2. Integrate with Message Composer

If you're using the [CometChatMessageComposer](/docs/ui-kit/ios/message-composer) component, integrate the `ShortCutFormatter` to manage shortcut functionalities:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let shortcutFormatter = ShortcutFormatter(trackingCharacter: "!")

    let cometChatMessageComposer = CometChatMessageComposer()
    cometChatMessageComposer.set(textFormatter: [shortcutFormatter])
    ```
  </Tab>
</Tabs>

<Note>
  Ensure to pass and present `cometChatConversationsWithMessages`. If a navigation controller is already in use, utilize the `pushViewController` function instead of directly presenting the view controller.
</Note>

***

## Example

<Frame>
  <img />
</Frame>

***

## Next Steps

<CardGroup>
  <Card title="Mentions Formatter" href="/ui-kit/ios/mentions-formatter-guide">
    Add @mentions with styled tokens and click handling.
  </Card>

  <Card title="Message Composer" href="/ui-kit/ios/message-composer">
    Customize the message input component.
  </Card>

  <Card title="Message List" href="/ui-kit/ios/message-list">
    Display and customize chat messages.
  </Card>

  <Card title="Message Template" href="/ui-kit/ios/message-template">
    Define custom message bubble structures.
  </Card>
</CardGroup>

***


# Threaded Messages Header
Source: https://www.cometchat.com/docs/ui-kit/ios/threaded-messages-header

Configure CometChat iOS UI Kit threaded message headers with parent message context, reply lists, composer layout, and back actions.

The `CometChatThreadedMessageHeader` component displays the header for threaded message conversations showing parent message info. By default, the parent message appears at the top, the message composer is at the bottom, and a message list containing all replies is displayed between them.

<Frame>
  <img />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatThreadedMessageHeader",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "description": "Displays the header for threaded message conversations showing parent message info",
    "inherits": "UIView",
    "primaryOutput": {
      "callback": "onBack",
      "type": "() -> Void"
    },
    "props": {
      "data": {
        "parentMessage": { "type": "BaseMessage", "required": true }
      },
      "callbacks": {
        "onBack": "() -> Void"
      }
    },
    "events": [],
    "sdkListeners": [],
    "compositionExample": {
      "description": "ThreadedMessageHeader is used within ThreadedMessages component",
      "components": ["CometChatThreadedMessageHeader", "CometChatMessageList", "CometChatMessageComposer"],
      "flow": "User opens thread → sees parent message in header → views/sends replies below"
    }
  }
  ```
</Accordion>

| Field     | Value                            |
| --------- | -------------------------------- |
| Component | `CometChatThreadedMessageHeader` |
| Package   | `CometChatUIKitSwift`            |
| Inherits  | `UIView`                         |

***

ThreadedMessages is composed of the following components:

| Component                                       | Description                                                                                                        |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [MessageList](/docs/ui-kit/ios/message-list)         | CometChatMessageList is a component that displays a list of Messages                                               |
| [MessageComposer](/docs/ui-kit/ios/message-composer) | CometChatMessageComposer is a component that helps in writing and editing of messages and also sending attachments |

***

## Usage

### Integration

Since `CometChatThreadedMessageHeader` is a view, you can add it to your view controller using the following code snippet:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let threadedMessage = CometChatThreadedMessageHeader()
    view.addSubview(threadedMessage)
    ```
  </Tab>
</Tabs>

<Note>
  Ensure to pass and present `threadedMessage`. If a navigation controller is already in use, utilize the pushViewController function instead of directly presenting the view controller.
</Note>

***

### Filters

Filters allow you to customize the data displayed in a list within a Component. You can filter the list based on your specific criteria for a more customized experience. Filters can be applied using RequestBuilders of Chat SDK.

ThreadedMessages does not have its own Filters. However, you can filter the messages list in ThreadedMessages Component using [MessageListConfiguration](#configuration).

**Example**

In this example, we are filtering messages and searching for messages that contain the keyword "payment":

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // MARK: - Filter messages by search keyword
    let messageRequestBuilder = MessagesRequest.MessageRequestBuilder()
        .set(uid: "your UID")
        .set(searchKeyword: "sure")

    let messageList = CometChatMessageList()
    messageList.set(user: user)
    messageList.set(messagesRequestBuilder: messageRequestBuilder)
    ```
  </Tab>
</Tabs>

***

### Events

[Events](/docs/ui-kit/ios/components-overview#events) are emitted by a Component. By using events, you can extend existing functionality. Being global events, they can be applied in multiple locations and are capable of being added or removed.

The MessageList Component does not emit any events of its own.

***

## Customization

To fit your app's design requirements, you can customize the appearance of the conversation component. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.

***

### Style

`ThreadedMessageHeaderStyle` contains various properties which can be used to customize the UI of `CometChatThreadedMessageHeader`.

**Global Level Styling**

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // MARK: - Apply global styling
    CometChatThreadedMessageHeader.style.backgroundColor = UIColor(hex: "#F76808")
    CometChatThreadedMessageHeader.style.dividerTintColor = UIColor(hex: "#F76808")
    CometChatThreadedMessageHeader.style.bubbleContainerBackgroundColor = UIColor(hex: "#F76808")
    ```
  </Tab>
</Tabs>

**Instance Level Styling**

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // MARK: - Apply instance-level styling
    let customThreadedHeaderStyle = ThreadedMessageHeaderStyle()
    customThreadedHeaderStyle.backgroundColor = UIColor(hex: "#F76808")
    customThreadedHeaderStyle.dividerTintColor = UIColor(hex: "#F76808")
    customThreadedHeaderStyle.bubbleContainerBackgroundColor = UIColor(hex: "#F76808")
            
    let threadedMessage = CometChatThreadedMessageHeader()
    threadedMessage.style = customThreadedHeaderStyle
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

List of properties available for configuring in ThreadedMessagesStyle:

| Property                          | Description                                | Code                                                                                             |
| --------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| Background Color                  | Background color for the header.           | `CometChatThreadedMessageHeader.style.backgroundColor = CometChatTheme.backgroundColor03`        |
| Border Color                      | Border color for the header.               | `CometChatThreadedMessageHeader.style.borderColor = UIColor.clear`                               |
| Border Width                      | Border width for the header.               | `CometChatThreadedMessageHeader.style.borderWith = 0`                                            |
| Corner Radius                     | Corner radius for the header.              | `CometChatThreadedMessageHeader.style.cornerRadius = CometChatCornerStyle?`                      |
| Bubble Container Background Color | Background color for the bubble container. | `CometChatThreadedMessageHeader.style.bubbleContainerBackgroundColor = UIColor.clear`            |
| Bubble Container Border Color     | Border color for the bubble container.     | `CometChatThreadedMessageHeader.style.bubbleContainerBorderColor = UIColor.clear`                |
| Bubble Container Border Width     | Border width for the bubble container.     | `CometChatThreadedMessageHeader.style.bubbleContainerBorderWidth = 0`                            |
| Bubble Container Corner Radius    | Corner radius for the bubble container.    | `CometChatThreadedMessageHeader.style.bubbleContainerCornerRadius = CometChatCornerStyle?`       |
| Divider Tint Color                | Tint color for the divider.                | `CometChatThreadedMessageHeader.style.dividerTintColor = CometChatTheme.extendedPrimaryColor100` |
| Count Text Color                  | Text color for the message count text.     | `CometChatThreadedMessageHeader.style.countTextColor = CometChatTheme.textColorSecondary`        |
| Count Text Font                   | Font for the message count text.           | `CometChatThreadedMessageHeader.style.countTextFont = CometChatTypography.Body.regular`          |

***

### Functionality

These are a set of small functional customizations that allow you to fine-tune the overall experience of the component. With these, you can set maximum lines the text area will show before scrolling in the composer, edit a message, add header view and footer view to the composer, and more.

Below is a list of customizations along with corresponding code snippets:

| Property            | Description                                            | Code                              |
| ------------------- | ------------------------------------------------------ | --------------------------------- |
| hideReplyCount      | Hides the reply count for threaded messages.           | `hideReplyCount = true`           |
| hideReplyCountBar   | Hides the reply count bar in the thread.               | `hideReplyCountBar = true`        |
| hideReceipts        | Hides read and delivery receipts for messages.         | `hideReceipts = true`             |
| hideAvatar          | Hides the avatar in the threaded message view.         | `hideAvatar = true`               |
| setMaxHeight        | Sets the maximum height for the threaded message view. | `setMaxHeight(300)`               |
| setMessageAlignment | Sets the alignment of messages (e.g., left or right).  | `setMessageAlignment(.right)`     |
| setParentMessage    | Sets the parent message for the threaded conversation. | `setParentMessage(parentMessage)` |

***

### Advanced

For advanced-level customization, you can set custom views to the component. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your views, layouts, and UI elements and then incorporate those into the component.

#### SetDatePattern

You can modify the date pattern to your requirement using `.set(datePattern:)`. This method accepts a function with a return type String. Inside the function, you can create your own pattern and return it as a String.

**Example**

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // MARK: - Custom date pattern
    let threadedMessageHeader = CometChatThreadedMessageHeader()
    threadedMessageHeader.set(datePattern: { timestamp in
        guard let timestamp = timestamp else {
            return ""
        }
        let date = Date(timeIntervalSince1970: TimeInterval(timestamp / 1000))
        let formatter = DateFormatter()
        formatter.dateFormat = "dd-MM-yyyy"
        return formatter.string(from: date)
    })
    ```
  </Tab>
</Tabs>

***

#### SetTextFormatters

This functionality dynamically assigns a list of text formatters. If a custom list is provided, it uses that list. Otherwise, it gracefully falls back to the default text formatters retrieved from the data source for seamless integration.

**Example**

This code customizes a CometChat text formatter to identify and style the word "sure", with handling options for interactions like string search, scrolling, and item clicks. The custom formatter is then applied to CometChat messages.

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // MARK: - Apply custom text formatter
    let myCustomTextFormatter = MyCustomTextFormatter(trackingCharacter: "#")

    let threadedMessageHeader = CometChatThreadedMessageHeader()
        .set(user: user)
        .set(textFormatter: [myCustomTextFormatter])
    ```
  </Tab>
</Tabs>

**Demonstration:**

<Tabs>
  <Tab title="MyCustomTextFormatter">
    ```swift lines theme={null}
    import Foundation
    import CometChatSDK
    import CometChatUIKitSwift

    class MyCustomTextFormatter: CometChatTextFormatter {
        
        // MARK: - Regex Pattern
        override func getRegex() -> String {
            return "(\\bsure\\b)"
        }

        // MARK: - Tracking Character
        override func getTrackingCharacter() -> Character {
            return "#"
        }

        // MARK: - Search
        override func search(string: String, suggestedItems: ((_: [SuggestionItem]) -> ())? = nil) {
            // This function would call an API or perform a local search
            // For now, it does nothing
        }

        // MARK: - Pagination
        override func onScrollToBottom(suggestionItemList: [SuggestionItem], listItem: ((_: [SuggestionItem]) -> ())?) {
            // This function would call the next page of an API
            // For now, it does nothing
        }

        // MARK: - Item Selection
        override func onItemClick(suggestedItem: SuggestionItem, user: User?, group: Group?) {
            // Do something with the clicked item
        }

        // MARK: - Pre-Send Processing
        override func handlePreMessageSend(baseMessage: BaseMessage, suggestionItemList: [SuggestionItem]) {
            // This function would modify the message before it's sent
            // For now, it does nothing
        }

        // MARK: - Message String Formatting
        override func prepareMessageString(
            baseMessage: BaseMessage,
            regexString: String,
            alignment: MessageBubbleAlignment = .left,
            formattingType: FormattingType
        ) -> NSAttributedString {
            let attrString = NSMutableAttributedString(string: "SURE")
            if alignment == .left {
                // Received message styling
                attrString.addAttribute(.foregroundColor, value: UIColor.blue, range: NSRange(location: 0, length: attrString.length))
            } else {
                // Sent message styling
                attrString.addAttribute(.foregroundColor, value: UIColor.green, range: NSRange(location: 0, length: attrString.length))
            }
            attrString.addAttribute(.font, value: UIFont.boldSystemFont(ofSize: 18), range: NSRange(location: 0, length: attrString.length))
            return attrString
        }

        // MARK: - Text Tap Handler
        override func onTextTapped(baseMessage: BaseMessage, tappedText: String, controller: UIViewController?) {
            // Your Action
        }
    }
    ```
  </Tab>
</Tabs>

***

#### SetTemplate and AddTemplate

[CometChatMessageTemplate](/docs/ui-kit/ios/message-template) is a pre-defined structure for creating message views that can be used as a starting point or blueprint for creating message views often known as message bubbles. For more information, you can refer to [CometChatMessageTemplate](/docs/ui-kit/ios/message-template).

***

## Common Patterns

### Open Thread from Message List

Present the threaded messages view when a user taps on a message's reply count:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // In your message list delegate or action handler
    func openThread(for parentMessage: BaseMessage) {
        // Create a view controller to host the threaded messages
        let threadVC = UIViewController()
        threadVC.view.backgroundColor = .systemBackground
        
        // Create threaded message header
        let threadedHeader = CometChatThreadedMessageHeader()
        threadedHeader.set(parentMessage: parentMessage)
        threadedHeader.set(controller: threadVC)
        threadedHeader.translatesAutoresizingMaskIntoConstraints = false
        
        // Create message list for thread replies
        let messageList = CometChatMessageList()
        if let user = parentMessage.sender {
            messageList.set(user: user)
        }
        messageList.set(parentMessage: parentMessage)
        messageList.set(controller: threadVC)
        messageList.translatesAutoresizingMaskIntoConstraints = false
        
        // Create composer for thread replies
        let composer = CometChatMessageComposer()
        if let user = parentMessage.sender {
            composer.set(user: user)
        }
        composer.set(parentMessage: parentMessage)
        composer.set(controller: threadVC)
        composer.translatesAutoresizingMaskIntoConstraints = false
        
        // Add to view
        threadVC.view.addSubview(threadedHeader)
        threadVC.view.addSubview(messageList)
        threadVC.view.addSubview(composer)
        
        // Layout constraints
        NSLayoutConstraint.activate([
            threadedHeader.topAnchor.constraint(equalTo: threadVC.view.safeAreaLayoutGuide.topAnchor),
            threadedHeader.leadingAnchor.constraint(equalTo: threadVC.view.leadingAnchor),
            threadedHeader.trailingAnchor.constraint(equalTo: threadVC.view.trailingAnchor),
            
            messageList.topAnchor.constraint(equalTo: threadedHeader.bottomAnchor),
            messageList.leadingAnchor.constraint(equalTo: threadVC.view.leadingAnchor),
            messageList.trailingAnchor.constraint(equalTo: threadVC.view.trailingAnchor),
            messageList.bottomAnchor.constraint(equalTo: composer.topAnchor),
            
            composer.leadingAnchor.constraint(equalTo: threadVC.view.leadingAnchor),
            composer.trailingAnchor.constraint(equalTo: threadVC.view.trailingAnchor),
            composer.bottomAnchor.constraint(equalTo: threadVC.view.safeAreaLayoutGuide.bottomAnchor)
        ])
        
        self.navigationController?.pushViewController(threadVC, animated: true)
    }
    ```
  </Tab>
</Tabs>

### Customize Thread Header with Parent Message Info

Display additional context about the parent message in the thread header:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    let threadedHeader = CometChatThreadedMessageHeader()
    threadedHeader.set(parentMessage: parentMessage)

    // Custom date formatting
    threadedHeader.set(datePattern: { timestamp in
        guard let timestamp = timestamp else { return "" }
        let date = Date(timeIntervalSince1970: TimeInterval(timestamp / 1000))
        let formatter = DateFormatter()
        formatter.dateFormat = "MMM d 'at' h:mm a"
        return formatter.string(from: date)
    })
    ```
  </Tab>
</Tabs>

### Filter Thread Replies

Show only specific types of messages in the thread:

<Tabs>
  <Tab title="Swift">
    ```swift lines theme={null}
    // Filter to show only text messages in thread
    let messageRequestBuilder = MessagesRequest.MessageRequestBuilder()
        .set(parentMessageId: parentMessage.id)
        .set(types: ["text"])
        .set(limit: 30)

    let messageList = CometChatMessageList()
    messageList.set(messagesRequestBuilder: messageRequestBuilder)
    ```
  </Tab>
</Tabs>

***

<Note>
  To ensure that the `CometChatThreadedMessageHeader` is properly configured, passing the controller is mandatory.

  ```swift lines theme={null}
  let threadedMessageHeader = CometChatThreadedMessageHeader()
  threadedMessageHeader.set(controller: UIViewController) // Passing the controller is required
  ```
</Note>


# Troubleshooting
Source: https://www.cometchat.com/docs/ui-kit/ios/troubleshooting

Troubleshoot CometChat iOS UI Kit setup, CocoaPods, Swift Package Manager, initialization, theming, permissions, and real-time updates.

<Accordion title="AI Integration Quick Reference">
  | Field         | Value                                                             |
  | ------------- | ----------------------------------------------------------------- |
  | Platform      | iOS UI Kit                                                        |
  | Common Issues | Initialization, theming, real-time updates, permissions           |
  | Key Checks    | CometChatUIKit.init(uiKitSettings:), user login, init/login order |
  | Permissions   | Camera, microphone, photo library (Info.plist)                    |
  | Debug         | Check SDK connection status, verify dashboard settings            |
</Accordion>

This guide covers common issues and solutions when working with the CometChat iOS UI Kit.

***

## CocoaPods Issues

| Issue                                | Solution                                                                                 |
| ------------------------------------ | ---------------------------------------------------------------------------------------- |
| "Could not find compatible versions" | Run `pod install --repo-update` to refresh spec repos                                    |
| Pod version not found                | Verify the version exists on [CocoaPods](https://cocoapods.org/pods/CometChatUIKitSwift) |
| Repo clone failures                  | Clean repos with commands below, then retry                                              |
| Build errors after pod install       | Open `.xcworkspace` file, not `.xcodeproj`                                               |

### Clean and Retry

```bash theme={null}
rm -rf Pods Podfile.lock
pod cache clean --all
pod install --repo-update
```

### Reset CocoaPods Completely

If repo errors persist:

```bash theme={null}
rm -rf ~/.cocoapods/repos
pod setup
pod install --repo-update
```

### Fallback to Swift Package Manager

If CocoaPods continues to fail, use SPM instead:

1. Remove Podfile and Pods folder
2. Open your `.xcodeproj` in Xcode
3. Go to **File → Add Package Dependencies**
4. Add `https://github.com/cometchat/cometchat-uikit-ios` with version `5.1.9`
5. Add `https://github.com/cometchat/chat-sdk-ios` with version `4.1.0`

***

## Initialization Issues

| Issue                  | Solution                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| SDK not initialized    | Call `CometChatUIKit.init(uiKitSettings:)` before any UI Kit operations                          |
| User not logged in     | Ensure `CometChatUIKit.login(uid:)` completes successfully before showing UI                     |
| Init/login order wrong | `init()` must complete before `login()`, and `login()` must complete before rendering components |
| Credentials invalid    | Verify App ID, Auth Key, and Region in CometChat Dashboard                                       |

***

## Theming & Styling

| Issue                     | Solution                                                   |
| ------------------------- | ---------------------------------------------------------- |
| Colors not applying       | Apply theme before `CometChatUIKit.init()`                 |
| Dark mode not working     | Use `UIColor { traitCollection in }` for dynamic colors    |
| Inconsistent colors       | Set all related colors (text, background, border) together |
| Styles not applying       | Apply global styles before `CometChatUIKit.init()`         |
| Instance style overridden | Instance styles take precedence over global styles         |
| Font not loading          | Verify font name is correct and font is added to project   |

***

## Conversations

| Issue                        | Solution                                                                    |
| ---------------------------- | --------------------------------------------------------------------------- |
| Empty conversation list      | Ensure user is logged in and has existing conversations                     |
| Conversations not updating   | Check SDK connection and real-time listeners                                |
| Navigation not working       | Verify `navigationController` is not nil; embed in `UINavigationController` |
| Custom views not appearing   | Ensure custom view has proper constraints and non-zero frame                |
| Typing indicator not showing | Verify `disableTyping` is not set to true                                   |

***

## Users

| Issue                           | Solution                                        |
| ------------------------------- | ----------------------------------------------- |
| Empty user list                 | Ensure SDK is initialized and user is logged in |
| Users not updating in real-time | Check SDK connection and presence listeners     |
| Search not working              | Verify `hideSearch` is not set to true          |
| Status not showing              | Check that `hideUserStatus` is not set to true  |
| Custom views not appearing      | Ensure custom view has proper constraints       |

***

## Groups

| Issue                            | Solution                                        |
| -------------------------------- | ----------------------------------------------- |
| Empty group list                 | Ensure SDK is initialized and user is logged in |
| Groups not updating in real-time | Check SDK connection and group listeners        |
| Search not working               | Verify `hideSearch` is not set to true          |
| Group type icons not showing     | Check that `hideGroupType` is not set to true   |
| Custom views not appearing       | Ensure custom view has proper constraints       |

***

## Group Members

| Issue                          | Solution                                                 |
| ------------------------------ | -------------------------------------------------------- |
| Empty member list              | Ensure group object is valid and has members             |
| Management options not showing | Check logged-in user's permissions (must be admin/owner) |
| Search not working             | Verify `hideSearch` is not set to true                   |
| Status not showing             | Check that `hideUserStatus` is not set to true           |
| Custom views not appearing     | Ensure custom view has proper constraints                |

***

## Message Header

| Issue                        | Solution                                                             |
| ---------------------------- | -------------------------------------------------------------------- |
| Header not showing user info | Ensure user or group is set on the header                            |
| Status not updating          | Check SDK connection and user presence listeners                     |
| Back button not working      | Verify `onBack` callback is set and `hideBackButton` is false        |
| Typing indicator not showing | Ensure typing events are enabled in SDK                              |
| Call buttons not appearing   | Check that `hideVideoCallButton` and `hideVoiceCallButton` are false |

***

## Message List

| Issue                         | Solution                                                     |
| ----------------------------- | ------------------------------------------------------------ |
| Messages not loading          | Ensure user/group is set and SDK is initialized              |
| Real-time updates not working | Check SDK connection status and listeners                    |
| Reactions not showing         | Verify reactions are enabled in dashboard                    |
| Thread replies not working    | Ensure `hideReplyInThreadOption` is not set to true          |
| Custom views not appearing    | Ensure custom view has proper constraints and non-zero frame |
| Scroll position issues        | Check `scrollToBottomOnNewMessages` setting                  |

***

## Message Composer

| Issue                       | Solution                                                |
| --------------------------- | ------------------------------------------------------- |
| Send button not working     | Ensure user or group is set on the composer             |
| Attachments not showing     | Check that attachment options are not hidden            |
| Voice recording not working | Verify microphone permissions are granted in Info.plist |
| Mentions not working        | Ensure `disableMentions` is not set to true             |
| Typing indicators not sent  | Check that `disableTypingEvents` is not set to true     |

***

## Calling

| Issue                     | Solution                                                       |
| ------------------------- | -------------------------------------------------------------- |
| Call buttons not showing  | Verify `CometChatCallsSDK` is in Podfile and run `pod install` |
| "Permission denied" error | Add camera/microphone permissions to Info.plist                |
| Calls not connecting      | Check network connection and CometChat credentials             |
| No incoming call UI       | Verify `CometChatCallsSDK` is installed and user is logged in  |
| Audio not working         | Check device is not on silent mode                             |

***

## AI Features

| Issue                             | Solution                                           |
| --------------------------------- | -------------------------------------------------- |
| AI features not appearing         | Enable them in CometChat Dashboard → AI            |
| Conversation starters not showing | Only appear for new conversations with no messages |
| Smart replies not appearing       | Ensure feature is enabled and messages exist       |
| Summary not generating            | Need sufficient messages in conversation           |
| AI Assistant empty                | Verify user has AI chat history                    |
| Only loading indicator shows      | Set `user` or `group` property                     |
| Styling not applied               | Apply style before presenting view                 |
| Callbacks not firing              | Set callbacks before pushing to navigation         |
| AI not responding                 | Verify AI features are enabled in dashboard        |
| Streaming not working             | Check network connectivity                         |
| Agent not detected                | Verify user has `isAgentic` property set to true   |

***

## Events

| Issue                 | Solution                                                           |
| --------------------- | ------------------------------------------------------------------ |
| Events not firing     | Verify listener is added before the action occurs                  |
| Duplicate events      | Check you're not adding the same listener multiple times           |
| Memory leaks          | Ensure `removeListener` is called in `viewWillDisappear`           |
| UI not updating       | Dispatch UI updates to main thread with `DispatchQueue.main.async` |
| Listener ID conflicts | Use unique, descriptive IDs for each listener                      |

***

## Permissions (Info.plist)

Add these keys to your `Info.plist` for full functionality:

```xml theme={null}
<!-- Camera access for video calls and image capture -->
<key>NSCameraUsageDescription</key>
<string>Camera access is required for video calls and capturing photos</string>

<!-- Microphone access for voice/video calls and audio messages -->
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is required for voice calls and audio messages</string>

<!-- Photo library access for sending images -->
<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access is required to send images</string>

<!-- Photo library save access -->
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Allow saving photos and videos to your device's photo library</string>
```

***

## Debug Checklist

When troubleshooting issues, verify the following:

1. **SDK Initialization**
   * `CometChatUIKit.init(uiKitSettings:)` called with correct App ID, Region, and Auth Key
   * Init must complete before calling `login()`

2. **User Authentication**
   * User is logged in via `CometChatUIKit.login(uid:)`
   * Auth token is valid and not expired (if using `loginWithAuthToken()`)

3. **Dashboard Settings**
   * Features are enabled (AI, Reactions, etc.)
   * API keys have correct permissions

4. **Network**
   * Device has internet connectivity
   * WebSocket connection is established

5. **Permissions**
   * Required permissions added to Info.plist
   * User has granted permissions at runtime

***

## Getting Help

<CardGroup>
  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5/SampleApp">
    Complete implementation example
  </Card>

  <Card title="UIKit Source" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5">
    CometChat UIKit iOS repository
  </Card>

  <Card title="Error Guide" href="/articles/error-guide">
    Complete list of error codes
  </Card>

  <Card title="Support" href="https://help.cometchat.com">
    Contact CometChat support
  </Card>
</CardGroup>


# Upgrading from V4 to V5
Source: https://www.cometchat.com/docs/ui-kit/ios/upgrading-from-v4

Migration guide for upgrading from CometChat iOS UI Kit v4 to v5 with breaking changes, property updates, and new patterns.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                                                                                 |
  | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package      | `CometChatUIKitSwift`                                                                                                                                                 |
  | Architecture | Composite components replaced with modular components                                                                                                                 |
  | Theming      | Direct static property assignment on `CometChatTheme` and `CometChatTypography`                                                                                       |
  | Key changes  | `CometChatConversationsWithMessages` → Individual components (`CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`) |
  | Style props  | Removed — use native theming system with direct property access                                                                                                       |
  | Config props | Removed — direct control over each component                                                                                                                          |
</Accordion>

The CometChat v5 iOS UI Kit introduces a modular architecture with smaller, focused components replacing composite components. This guide outlines the key differences and provides migration steps from v4 to v5.

***

## Overview of Changes

| Feature       | v4                                                                     | v5                                                                          |
| ------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Architecture  | Composite components (e.g., `CometChatConversationsWithMessages`)      | Modular components (`CometChatConversations`, `CometChatMessageList`, etc.) |
| Theming       | `CometChatTheme` with `Palette` and `Typography` classes               | Direct static property assignment                                           |
| Customization | Complex configuration objects                                          | Direct component properties and Swift APIs                                  |
| Style Props   | Inline style properties                                                | Native theming system                                                       |
| Custom Views  | `itemView`, `leadingView`, `trailingView`, `subtitleView`, `titleView` | Unified naming convention across components                                 |

***

## Integration

In v4, integration was straightforward due to composite components like `CometChatConversationsWithMessages`. This single component provided end-to-end functionality including listing conversations, handling clicks, loading messages, and supporting threaded messages. However, customization required deep understanding of internal flows, and configurations mixed custom view props, behavioral props, and style props.

With v5, composite components are replaced with smaller, modular components:

* `CometChatConversations`
* `CometChatMessageHeader`
* `CometChatMessageList`
* `CometChatMessageComposer`

This modular approach makes integration more flexible. Each component has a well-defined purpose, and developers can customize behavior and styling directly via component properties and Swift APIs.

<Note>
  Learn how to build a complete messaging UI using the v5 UI Kit by following the [Getting Started guide](/docs/ui-kit/ios/getting-started).
</Note>

***

## Components

### v4 Components

|                                    |                            |                             |
| ---------------------------------- | -------------------------- | --------------------------- |
| CometChatConversationsWithMessages | CometChatUsersWithMessages | CometChatGroupsWithMessages |
| CometChatMessages                  | CometChatMessageHeader     | CometChatMessageList        |
| CometChatMessageComposer           | CometChatThreadedMessages  | CometChatConversations      |
| CometChatUsers                     | CometChatGroups            | CometChatContacts           |
| CometChatDetails                   | CometChatGroupMembers      | CometChatAddMembers         |
| CometChatBannedMembers             | CometChatTransferOwnership | CometChatMessageInformation |
| CometChatIncomingCall              | CometChatOngoingCall       | CometChatOutgoingCall       |
| CometChatCallButtons               | CometChatCallLogs          | CometChatCallLogDetails     |
| CometChatCallLogHistory            |                            |                             |

### v5 Components

|                          |                                |                       |
| ------------------------ | ------------------------------ | --------------------- |
| CometChatConversations   | CometChatUsers                 | CometChatGroups       |
| CometChatGroupMembers    | CometChatMessageHeader         | CometChatMessageList  |
| CometChatMessageComposer | CometChatThreadedMessageHeader | CometChatIncomingCall |
| CometChatOutgoingCall    | CometChatCallButtons           | CometChatCallLogs     |

***

## Theming

### v4 Theming

In v4, theming required instantiating multiple objects and passing them through constructors:

```swift title="V4 UI Kit" theme={null}
let palette = Palette()
palette.set(background: .purple)
palette.set(accent: .cyan)
palette.set(primary: .green)
palette.set(error: .red)
palette.set(success: .yellow)
palette.set(secondary: .orange)

let family = CometChatFontFamily(
    regular: "CourierNewPSMT",
    medium: "CourierNewPS-BoldMT",
    bold: "CourierNewPS-BoldMT"
)
var typography = Typography()
typography.overrideFont(family: family)

let theme = CometChatTheme(typography: typography, palatte: palette)
```

### v5 Theming

In v5, theming uses direct static property assignment:

```swift title="V5 UI Kit" theme={null}
// Apply the global theme - typically in AppDelegate or SceneDelegate
CometChatTheme.primaryColor = UIColor.red
CometChatTheme.backgroundColor01 = .brown
CometChatTheme.backgroundColor02 = .green

// Apply custom typography
CometChatTypography.Body.regular = UIFont.systemFont(ofSize: 18, weight: .bold)
```

<Note>
  For detailed guidance on theming, refer to:

  * [Theming Documentation](/docs/ui-kit/ios/theme-introduction)
  * [Color Customization](/docs/ui-kit/ios/color-resources)
</Note>

***

## Properties

In v5, the approach to properties has been refined:

* **Style properties** — Replaced by a native theming system based on direct property access
* **Configuration properties** — Removed due to modular architecture; developers have direct control over each component
* **Custom view properties** — Restructured for consistency with unified naming: `itemView`, `leadingView`, `trailingView`, `subtitleView`, `titleView`

***

## Property Changes

### Conversations

#### New Properties

| Name                         | Type                       | Description                               |
| ---------------------------- | -------------------------- | ----------------------------------------- |
| hideNavigationBar            | Bool                       | Hides or shows the navigation bar         |
| hideSearch                   | Bool                       | Hides the search bar                      |
| hideLoadingState             | Bool                       | Hides the loading state indicator         |
| hideDeleteConversationOption | Bool                       | Hides the option to delete a conversation |
| hideGroupType                | Bool                       | Hides the group type indicator            |
| backgroundDrawable           | UIImage                    | Sets a background image                   |
| separatorColor               | UIColor                    | Sets the color of separators              |
| separatorWidth               | CGFloat                    | Sets the width of separators              |
| errorTextColor               | UIColor                    | Sets the color of error messages          |
| lastMessageTextColor         | UIColor                    | Sets the color of the last message text   |
| typingIndicatorColor         | UIColor                    | Sets the color of the typing indicator    |
| dateTimeFormatter            | CometChatDateTimeFormatter | Customizes date/time display              |
| set(OnItemLongClick:)        | Method                     | Triggered on long press                   |
| set(onEmpty:)                | Method                     | Triggered when list is empty              |

#### Renamed Properties

| v4 Name                     | v5 Name           | Description                                      |
| --------------------------- | ----------------- | ------------------------------------------------ |
| hide(error: Bool)           | hideErrorView     | Hides the error state view                       |
| show(backButton: Bool)      | hideBackButton    | Controls back button visibility (logic inverted) |
| hide(receipt: Bool)         | hideReceipts      | Hides message receipts                           |
| disable(userPresence: Bool) | hideUserStatus    | Hides online/offline status                      |
| setOnItemClick              | set(OnItemClick:) | Triggered on click                               |
| setOnBack                   | set(onBack:)      | Override back button action                      |
| setOnSelection              | set(onSelection:) | Triggered on selection                           |
| setOnError                  | set(onError:)     | Override error action                            |

#### Removed Properties

| Name                              | Description                         |
| --------------------------------- | ----------------------------------- |
| hide(separator: Bool)             | Replaced by style properties        |
| disable(typing: Bool)             | Toggled typing indicator visibility |
| setDatePattern                    | Replaced by dateTimeFormatter       |
| protectedGroupIcon                | Icon for password protected groups  |
| sentIcon, deliveredIcon, readIcon | Receipt icons                       |

***

### Users

#### New Properties

| Name              | Type                             | Description                  |
| ----------------- | -------------------------------- | ---------------------------- |
| set(options:)     | (User) -> \[CometChatUserOption] | Custom options for each user |
| set(leadingView:) | (User) -> UIView                 | Custom leading view          |
| set(titleView:)   | (User) -> UIView                 | Custom title view            |
| set(trailView:)   | (User) -> UIView                 | Custom trailing view         |
| set(onEmpty:)     | () -> Void                       | Triggered when list is empty |
| hideErrorView     | Bool                             | Hides the error state view   |
| hideNavigationBar | Bool                             | Hides the navigation bar     |
| hideBackButton    | Bool                             | Hides the back button        |
| hideLoadingState  | Bool                             | Hides loading indicator      |
| hideUserStatus    | Bool                             | Hides online/offline status  |
| hideSectionHeader | Bool                             | Hides section headers        |
| hideSearch        | Bool                             | Hides the search bar         |

#### Renamed Properties

| v4 Name            | v5 Name               | Description             |
| ------------------ | --------------------- | ----------------------- |
| setListItemView    | set(listItemView:)    | Custom list item view   |
| setSubtitleView    | set(subtitleView:)    | Custom subtitle view    |
| setEmptyStateView  | set(emptyView:)       | Custom empty state view |
| setErrorStateView  | set(errorView:)       | Custom error state view |
| setOnItemClick     | set(onItemClick:)     | Triggered on click      |
| setOnItemLongClick | set(onItemLongClick:) | Triggered on long press |
| setOnBack          | set(onBack:)          | Triggered on back press |
| setOnSelection     | set(onSelection:)     | Triggered on selection  |
| setOnError         | set(onError:)         | Triggered on error      |

#### Removed Properties

| Name                    | Description                    |
| ----------------------- | ------------------------------ |
| set(loadingStateView:)  | Set loading view icon size     |
| hide(errorText:)        | Hide error text                |
| show(backButton:)       | Toggle back button             |
| set(searchIcon:)        | Set search icon                |
| hide(search:)           | Toggle search box              |
| hide(separator:)        | Hide divider                   |
| disable(userPresence:)  | Control online indicator       |
| set(emptyStateText:)    | Custom empty text              |
| set(errorStateText:)    | Custom error text              |
| set(searchPlaceholder:) | Search placeholder             |
| set(title:mode:)        | Set title with display mode    |
| setOnLoad               | Triggered when list is fetched |

***

### Groups

#### New Properties

| Name                    | Type               | Description                    |
| ----------------------- | ------------------ | ------------------------------ |
| set(onSelection:)       | Closure            | Returns selected groups        |
| set(onEmpty:)           | Closure            | Triggered when list is empty   |
| setOnLoad               | Closure            | Triggered when list is fetched |
| listItemSelectedImage   | UIImage            | Selected checkbox image        |
| listItemDeSelectedImage | UIImage            | Deselected checkbox image      |
| hideErrorView           | Bool               | Hides error state view         |
| hideNavigationBar       | Bool               | Hides navigation bar           |
| hideSearch              | Bool               | Hides search bar               |
| hideBackButton          | Bool               | Hides back button              |
| hideLoadingState        | Bool               | Hides loading indicator        |
| set(leadingView:)       | (Group?) -> UIView | Custom leading view            |
| set(titleView:)         | (Group?) -> UIView | Custom title view              |
| set(trailView:)         | (Group?) -> UIView | Custom trailing view           |

#### Renamed Properties

| v4 Name            | v5 Name               | Description             |
| ------------------ | --------------------- | ----------------------- |
| SetOnItemClick     | set(onItemClick:)     | Triggered on click      |
| SetOnItemLongClick | set(OnItemLongClick:) | Triggered on long press |
| SetOnError         | set(onError:)         | Triggered on error      |
| SetOnBack          | set(onBack:)          | Triggered on back press |
| setListItemView    | SetListItemView       | Custom list item        |
| setSubtitleView    | SetSubTitleView       | Custom subtitle view    |

***

### Group Members

#### New Properties

| Name                  | Type                     | Description                    |
| --------------------- | ------------------------ | ------------------------------ |
| hideError             | Bool                     | Hides error state view         |
| hideUserStatus        | Bool                     | Hides online/offline status    |
| hideNavigationBar     | Bool                     | Hides navigation bar           |
| hideLoadingState      | Bool                     | Hides loading indicator        |
| hideBackIcon          | Bool                     | Hides back button              |
| hideKickMemberOption  | Bool                     | Hides kick member option       |
| hideBanMemberOption   | Bool                     | Hides ban member option        |
| hideScopeChangeOption | Bool                     | Hides scope change option      |
| hideSearch            | Bool                     | Hides search bar               |
| set(onSelection:)     | (\[GroupMember]) -> Void | Returns selected members       |
| set(onEmpty:)         | () -> Void               | Triggered when list is empty   |
| set(onLoad:)          | (\[GroupMember]) -> Void | Triggered when list is fetched |
| set(leadingView:)     | (GroupMember?) -> UIView | Custom leading view            |
| set(titleView:)       | (GroupMember?) -> UIView | Custom title view              |

#### Renamed Properties

| v4 Name                | v5 Name               | Description                 |
| ---------------------- | --------------------- | --------------------------- |
| background             | backgroundColor       | Background color            |
| disable(userPresence:) | hideUserStatus        | Hides online/offline status |
| hide(search:)          | hideSearch            | Hides search bar            |
| setOnItemClick         | set(onItemClick:)     | Triggered on click          |
| setOnItemLongClick     | set(onItemLongClick:) | Triggered on long press     |
| setOnError             | set(onError:)         | Triggered on error          |
| setOnBack              | set(onBack:)          | Triggered on back press     |

#### Removed Properties

| Name                    | Description                   |
| ----------------------- | ----------------------------- |
| backIconTint            | Back button tint color        |
| searchIconTint          | Search icon tint color        |
| avatarStyle             | Avatar component styles       |
| statusIndicatorStyle    | Status indicator styles       |
| listItemStyle           | List item view styles         |
| groupScopeStyle         | Change scope component styles |
| groupMembersStyle       | Component styles              |
| set(title:mode:)        | Custom title                  |
| set(backButtonTitle:)   | Back button text              |
| set(searchPlaceholder:) | Search placeholder            |
| show(backButton:)       | Show back button              |
| set(errorStateText:)    | Error state text              |
| selectionMode(mode:)    | Selection mode                |
| hide(separator:)        | Hide separator                |

***

### Message Header

#### New Properties

| Name                     | Type                         | Description             |
| ------------------------ | ---------------------------- | ----------------------- |
| titleTextColor           | UIColor                      | Header title text color |
| titleTextFont            | UIFont                       | Header title font       |
| subtitleTextColor        | UIColor                      | Subtitle text color     |
| subtitleTextFont         | UIFont                       | Subtitle font           |
| backButtonImageTintColor | UIColor                      | Back button tint        |
| hideBackButton           | Bool                         | Hides back button       |
| hideUserStatus           | Bool                         | Hides user status       |
| hideVideoCallButton      | Bool                         | Hides video call button |
| hideVoiceCallButton      | Bool                         | Hides voice call button |
| set(onBack:)             | () -> Void                   | Triggered on back press |
| set(onError:)            | (CometChatException) -> Void | Triggered on error      |
| set(listItemView:)       | (User?, Group?) -> UIView    | Custom list item        |
| set(leadingView:)        | (User?, Group?) -> UIView    | Custom leading view     |
| set(titleView:)          | (User?, Group?) -> UIView    | Custom title view       |
| set(trailView:)          | (User?, Group?) -> UIView    | Custom trailing view    |
| set(subtitleView:)       | (User?, Group?) -> UIView    | Custom subtitle view    |
| dateTimeFormatter        | CometChatDateTimeFormatter   | Date/time formatting    |

#### Renamed Properties

| v4 Name                    | v5 Name                  | Description          |
| -------------------------- | ------------------------ | -------------------- |
| background                 | backgroundColor          | Background color     |
| backIconTint               | backButtonImageTintColor | Back button tint     |
| hide(backButton:)          | hideBackButton           | Hides back button    |
| set(disableUsersPresence:) | hideUserStatus           | Hides user status    |
| setMenus                   | set(menus:)              | Custom menus         |
| setSubtitleView            | set(subtitleView:)       | Custom subtitle view |

#### Removed Properties

| Name                     | Description                      |
| ------------------------ | -------------------------------- |
| typingIndicatorTextFont  | Typing indicator font            |
| typingIndicatorTextColor | Typing indicator color           |
| detailIconTint           | Detail icon tint                 |
| onlineStatusColor        | Online status color              |
| set(protectedGroupIcon:) | Protected group icon             |
| set(privateGroupIcon:)   | Private group icon               |
| disable(typing:)         | Enable/disable typing indicators |

***

### Message List

#### New Properties

| Name                        | Type                                            | Description                       |
| --------------------------- | ----------------------------------------------- | --------------------------------- |
| hideAvatar                  | Bool                                            | Hides sender avatar               |
| hideGroupActionMessages     | Bool                                            | Hides group action messages       |
| hideReplyInThreadOption     | Bool                                            | Hides reply in thread option      |
| hideTranslateMessageOption  | Bool                                            | Hides translation option          |
| hideEditMessageOption       | Bool                                            | Hides edit option                 |
| hideDeleteMessageOption     | Bool                                            | Hides delete option               |
| hideReactionOption          | Bool                                            | Hides reaction option             |
| hideMessagePrivatelyOption  | Bool                                            | Hides message privately option    |
| hideCopyMessageOption       | Bool                                            | Hides copy option                 |
| hideMessageInfoOption       | Bool                                            | Hides message info option         |
| hideHeaderView              | Bool                                            | Hides header view                 |
| hideFooterView              | Bool                                            | Hides footer view                 |
| hideDateSeparator           | Bool                                            | Hides date separator              |
| scrollToBottomOnNewMessages | Bool                                            | Scrolls to bottom on new messages |
| hideReceipts                | Bool                                            | Hides read receipts               |
| disableSoundForMessages     | Bool                                            | Disables message sound            |
| hideEmptyView               | Bool                                            | Hides empty state view            |
| hideErrorView               | Bool                                            | Hides error view                  |
| hideLoadingView             | Bool                                            | Hides loading view                |
| hideNewMessageIndicator     | Bool                                            | Hides new message indicator       |
| set(onThreadRepliesClick:)  | (BaseMessage, CometChatMessageTemplate) -> Void | Thread click callback             |
| set(onReactionClick:)       | (CometChat.ReactionCount, BaseMessage?) -> Void | Reaction click callback           |
| set(onError:)               | (CometChatException) -> Void                    | Error callback                    |
| set(onEmpty:)               | () -> Void                                      | Empty state callback              |
| set(onLoad:)                | (\[BaseMessage]) -> Void                        | Load callback                     |
| set(headerView:)            | UIView                                          | Custom header view                |
| set(footerView:)            | UIView                                          | Custom footer view                |
| set(textFormatters:)        | \[CometChatTextFormatter]                       | Text formatters                   |
| dateTimeFormatter           | CometChatDateTimeFormatter                      | Date/time formatting              |

#### Renamed Properties

| v4 Name        | v5 Name                | Description        |
| -------------- | ---------------------- | ------------------ |
| hide(receipt:) | hideReceipts           | Hides receipts     |
| show(avatar:)  | hideAvatar             | Shows/hides avatar |
| background     | backgroundColor        | Background color   |
| alignment      | set(messageAlignment:) | Message alignment  |

#### Removed Properties

| Name                            | Description                  |
| ------------------------------- | ---------------------------- |
| loadingIconTint                 | Loading icon tint            |
| emptyTextFont                   | Empty state text font        |
| errorTextFont                   | Error text font              |
| emptyTextColor                  | Empty state text color       |
| errorTextColor                  | Error state text color       |
| nameTextColor                   | Sender name text color       |
| nameTextFont                    | Sender name font             |
| timestampTextColor              | Timestamp text color         |
| threadReplySeperatorColor       | Thread reply separator color |
| threadReplyTextColor            | Thread reply text color      |
| threadReplyTextFont             | Thread reply font            |
| hide(error:)                    | Hide error view              |
| messageInformationConfiguration | Message info configuration   |
| reactionsConfiguration          | Reactions configuration      |
| setDateSeparatorPattern         | Date separator pattern       |
| setDatePattern                  | Date pattern                 |

***

### Message Composer

#### New Properties

| Name                                   | Type                                                                    | Description                     |
| -------------------------------------- | ----------------------------------------------------------------------- | ------------------------------- |
| placeHolderTextFont                    | UIFont                                                                  | Placeholder font                |
| placeHolderTextColor                   | UIColor                                                                 | Placeholder color               |
| textFiledColor                         | UIColor                                                                 | Input text color                |
| textFiledFont                          | UIFont                                                                  | Input text font                 |
| sendButtonImage                        | UIImage                                                                 | Send button icon                |
| sendButtonImageTint                    | UIColor                                                                 | Send button tint                |
| activeSendButtonImageBackgroundColor   | UIColor                                                                 | Active send button background   |
| inactiveSendButtonImageBackgroundColor | UIColor                                                                 | Inactive send button background |
| attachmentImage                        | UIImage                                                                 | Attachment button icon          |
| attachmentImageTint                    | UIColor                                                                 | Attachment button tint          |
| voiceRecordingImage                    | UIImage                                                                 | Voice recording icon            |
| voiceRecordingImageTint                | UIColor                                                                 | Voice recording tint            |
| aiImage                                | UIImage                                                                 | AI button icon                  |
| aiImageTint                            | UIColor                                                                 | AI button tint                  |
| stickerImage                           | UIImage                                                                 | Sticker button icon             |
| stickerTint                            | UIColor                                                                 | Sticker button tint             |
| disableTypingEvents                    | Bool                                                                    | Disables typing indicators      |
| disableMentions                        | Bool                                                                    | Disables mentions               |
| hideImageAttachmentOption              | Bool                                                                    | Hides image attachment          |
| hideVideoAttachmentOption              | Bool                                                                    | Hides video attachment          |
| hideAudioAttachmentOption              | Bool                                                                    | Hides audio attachment          |
| hideFileAttachmentOption               | Bool                                                                    | Hides file attachment           |
| hidePollsOption                        | Bool                                                                    | Hides polls option              |
| hideCollaborativeDocumentOption        | Bool                                                                    | Hides collaborative document    |
| hideCollaborativeWhiteboardOption      | Bool                                                                    | Hides collaborative whiteboard  |
| hideAttachmentButton                   | Bool                                                                    | Hides attachment button         |
| hideVoiceRecordingButton               | Bool                                                                    | Hides voice recording button    |
| hideStickersButton                     | Bool                                                                    | Hides stickers button           |
| hideSendButton                         | Bool                                                                    | Hides send button               |
| set(onSendButtonClick:)                | (BaseMessage) -> Void                                                   | Send button callback            |
| set(onTextChangedListener:)            | (String) -> Void                                                        | Text change callback            |
| set(onError:)                          | (CometChatException) -> Void                                            | Error callback                  |
| set(attachmentOptions:)                | (User?, Group?, UIViewController?) -> \[CometChatMessageComposerAction] | Custom attachment options       |
| set(sendButtonView:)                   | (User?, Group?) -> UIView                                               | Custom send button              |
| set(headerView:)                       | (User?, Group?) -> UIView                                               | Custom header view              |
| set(footerView:)                       | (User?, Group?) -> UIView                                               | Custom footer view              |
| set(textFormatter:)                    | \[CometChatTextFormatter]                                               | Text formatters                 |
| mediaRecorderStyle                     | MediaRecorderStyle                                                      | Media recording styling         |
| aiOptionsStyle                         | AIOptionsStyle                                                          | AI options styling              |

#### Renamed Properties

| v4 Name                           | v5 Name                  | Description            |
| --------------------------------- | ------------------------ | ---------------------- |
| background                        | backgroundColor          | Background color       |
| hide(voiceRecording:)             | hideVoiceRecordingButton | Hides voice recording  |
| disable(disableTypingEvents:)     | disableTypingEvents      | Disables typing events |
| disable(disableSoundForMessages:) | disableSoundForMessages  | Disables message sound |
| setMentionsFormatters             | set(textFormatter:)      | Text formatters        |

#### Removed Properties

| Name                           | Description               |
| ------------------------------ | ------------------------- |
| inputBackground                | Input background color    |
| textFont                       | Input text font           |
| inputBoxPlaceholderFont        | Placeholder font          |
| attachmentIconTint             | Attachment icon tint      |
| sendIconTint                   | Send icon tint            |
| separatorTint                  | Separator color           |
| inputBorderWidth               | Input border width        |
| inputBorderColor               | Input border color        |
| actionSheetTitleColor          | Action sheet title color  |
| actionSheetTitleFont           | Action sheet title font   |
| voiceRecordingIconTint         | Voice recording icon tint |
| aiIconTint                     | AI icon tint              |
| set(background:)               | Background color          |
| set(placeholderText:)          | Placeholder text          |
| set(maxLines:)                 | Max lines                 |
| set(auxiliaryButtonAlignment:) | Auxiliary button position |
| set(customSoundForMessage:)    | Custom message sound      |
| set(liveReactionIconURL:)      | Live reaction icon        |
| set(disableMentions:)          | Disable mentions          |
| setOnSendButtonClick           | Send button callback      |
| hide(liveReaction:)            | Hide live reaction        |
| hide(footerView:)              | Hide footer view          |
| hide(headerView:)              | Hide header view          |
| hide(sendButton:)              | Hide send button          |
| setAttachmentOptions           | Attachment options        |
| setAuxilaryButtonView          | Auxiliary button view     |
| setSecondaryButtonView         | Secondary button view     |
| setSendButtonView              | Send button view          |

***

## Next Steps

<CardGroup>
  <Card title="Getting Started" href="/ui-kit/ios/getting-started">
    Fresh v5 setup guide for iOS
  </Card>

  <Card title="Components Overview" href="/ui-kit/ios/components-overview">
    Explore all v5 prebuilt UI components
  </Card>

  <Card title="Theme Introduction" href="/ui-kit/ios/theme-introduction">
    New direct property-based theming system
  </Card>

  <Card title="Color Resources" href="/ui-kit/ios/color-resources">
    Customize colors and dark mode
  </Card>
</CardGroup>


# Users
Source: https://www.cometchat.com/docs/ui-kit/ios/users

Display CometChat iOS UI Kit users with avatars, online status, search, filtering, selection callbacks, and conversation navigation.

The `CometChatUsers` component displays a searchable list of all available users. It shows user names, avatars, and online/offline status indicators. Users can be filtered, searched, and selected for starting conversations.

<Frame>
  <img alt="CometChatUsers showing a searchable list of users with avatars, names, and online/offline status indicators" />
</Frame>

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatUsers",
    "package": "CometChatUIKitSwift",
    "import": "import CometChatUIKitSwift\nimport CometChatSDK",
    "description": "Displays a searchable list of all available users with avatars, names, and online/offline status indicators.",
    "inherits": "UIViewController",
    "primaryOutput": {
      "callback": "onItemClick",
      "type": "(User, IndexPath) -> Void"
    },
    "props": {
      "data": {
        "usersRequestBuilder": {
          "type": "UsersRequest.UsersRequestBuilder?",
          "default": "nil",
          "note": "Custom request builder for filtering users"
        },
        "searchRequestBuilder": {
          "type": "UsersRequest.UsersRequestBuilder?",
          "default": "nil",
          "note": "Custom request builder for search"
        }
      },
      "callbacks": {
        "onItemClick": "(User, IndexPath) -> Void",
        "onItemLongClick": "(User, IndexPath) -> Void",
        "onBack": "() -> Void",
        "onSelection": "([User]) -> Void",
        "onSelectedItemProceed": "([User]) -> Void",
        "onError": "(CometChatException) -> Void",
        "onEmpty": "() -> Void",
        "onLoad": "([[User]]) -> Void"
      },
      "visibility": {
        "hideSearch": { "type": "Bool", "default": false },
        "hideNavigationBar": { "type": "Bool", "default": false },
        "hideBackButton": { "type": "Bool", "default": false },
        "hideUserStatus": { "type": "Bool", "default": false },
        "hideSectionHeader": { "type": "Bool", "default": false },
        "hideErrorView": { "type": "Bool", "default": false },
        "hideLoadingState": { "type": "Bool", "default": false }
      },
      "selection": {
        "selectionMode": { "type": "SelectionMode", "default": ".none" },
        "selectionLimit": { "type": "Int", "default": 0, "note": "0 means unlimited" },
        "selectedCellCount": { "type": "Int", "default": 0, "note": "Read-only count of selected users" }
      },
      "styling": {
        "avatarStyle": { "type": "AvatarStyle", "default": "AvatarStyle()" },
        "statusIndicatorStyle": { "type": "StatusIndicatorStyle", "default": "StatusIndicatorStyle()" }
      },
      "viewSlots": {
        "listItemView": "(User) -> UIView",
        "leadingView": "(User) -> UIView",
        "titleView": "(User?) -> UIView",
        "subtitleView": "(User?) -> UIView",
        "trailingView": "(User?) -> UIView",
        "emptyStateView": "() -> UIView",
        "errorStateView": "() -> UIView",
        "loadingStateView": "() -> UIView"
      }
    },
    "methods": {
      "swipeActions": {
        "set(options:)": "((User?) -> [CometChatUserOption])? - Sets custom swipe actions",
        "add(options:)": "((User?) -> [CometChatUserOption])? - Adds additional swipe actions"
      },
      "dataManipulation": {
        "add(user:)": "User - Adds a user to the list",
        "update(user:)": "User - Updates a user in the list",
        "remove(user:)": "User - Removes a user from the list",
        "getSelectedUsers()": "[User] - Returns selected users"
      }
    },
    "events": [
      {
        "name": "ccUserBlocked",
        "payload": "User",
        "description": "Fires when a user is blocked"
      },
      {
        "name": "ccUserUnblocked",
        "payload": "User",
        "description": "Fires when a user is unblocked"
      }
    ],
    "sdkListeners": [
      "onUserOnline",
      "onUserOffline"
    ],
    "compositionExample": {
      "description": "Users list for starting new conversations",
      "components": ["CometChatUsers", "CometChatMessages"],
      "flow": "User taps on a user → onItemClick fires → Navigate to CometChatMessages with selected user"
    },
    "types": {
      "User": {
        "uid": "String",
        "name": "String",
        "avatar": "String?",
        "status": "UserStatus",
        "role": "String?"
      },
      "UserStatus": {
        "online": "User is currently online",
        "offline": "User is currently offline"
      }
    }
  }
  ```
</Accordion>

| Field     | Value                 |
| --------- | --------------------- |
| Component | `CometChatUsers`      |
| Package   | `CometChatUIKitSwift` |
| Inherits  | `UIViewController`    |

***

## Where It Fits

`CometChatUsers` displays all available users for starting new conversations. It's typically used as a standalone screen or within a tab view controller.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class UsersViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupUsers()
    }
    
    private func setupUsers() {
        let usersController = CometChatUsers()
        
        // Handle user selection - start a conversation
        usersController.set(onItemClick: { [weak self] user, indexPath in
            self?.startConversation(with: user)
        })
        
        let navController = UINavigationController(rootViewController: usersController)
        present(navController, animated: true)
    }
    
    private func startConversation(with user: User) {
        let messagesVC = CometChatMessages()
        messagesVC.set(user: user)
        navigationController?.pushViewController(messagesVC, animated: true)
    }
}
```

<Frame>
  <img alt="CometChatUsers displaying the user list within a navigation controller hierarchy" />
</Frame>

***

## Minimal Render

```swift lines theme={null}
import CometChatUIKitSwift

let users = CometChatUsers()
let navController = UINavigationController(rootViewController: users)
present(navController, animated: true)
```

<Frame>
  <img alt="CometChatUsers showing the minimal render with default configuration" />
</Frame>

***

## Filtering

Use `UsersRequest.UsersRequestBuilder` to filter which users appear in the list. The builder pattern allows chaining multiple filter conditions.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

// Create a custom request builder
let usersRequestBuilder = UsersRequest.UsersRequestBuilder(limit: 30)
    .friendsOnly(true)

let users = CometChatUsers(usersRequestBuilder: usersRequestBuilder)
```

### Filter Recipes

| Recipe             | Code                                  |
| ------------------ | ------------------------------------- |
| Friends only       | `.friendsOnly(true)`                  |
| Online users only  | `.set(status: .online)`               |
| Search by name     | `.set(searchKeyword: "John")`         |
| Filter by role     | `.set(roles: ["admin", "moderator"])` |
| Filter by tags     | `.set(tags: ["premium"])`             |
| Hide blocked users | `.hideBlockedUsers(true)`             |
| Limit results      | `UsersRequestBuilder(limit: 20)`      |
| Specific UIDs      | `.set(UIDs: ["user1", "user2"])`      |

***

## Actions and Events

### Callback Props

#### onItemClick

Fires when a user taps on a user in the list. Use this to start a conversation.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

users.set(onItemClick: { [weak self] user, indexPath in
    guard let self = self else { return }
    
    let messagesVC = CometChatMessages()
    messagesVC.set(user: user)
    self.navigationController?.pushViewController(messagesVC, animated: true)
})
```

#### onItemLongClick

Fires when a user long-presses on a user. Use this to show additional options.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

users.set(onItemLongClick: { [weak self] user, indexPath in
    guard let self = self else { return }
    
    let alert = UIAlertController(title: user.name, message: nil, preferredStyle: .actionSheet)
    
    alert.addAction(UIAlertAction(title: "View Profile", style: .default) { _ in
        // View profile
    })
    
    alert.addAction(UIAlertAction(title: "Block User", style: .destructive) { _ in
        // Block user
    })
    
    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
    self.present(alert, animated: true)
})
```

#### onBack

Fires when the back button is pressed.

```swift lines theme={null}
import CometChatUIKitSwift

let users = CometChatUsers()

users.set(onBack: { [weak self] in
    self?.navigationController?.popViewController(animated: true)
})
```

#### onSelection

Fires when users are selected in selection mode.

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()
users.selectionMode = .multiple

users.set(onSelection: { [weak self] selectedUsers in
    print("Selected \(selectedUsers.count) users")
})
```

#### onError

Fires when an error occurs while loading users.

```swift lines theme={null}
import CometChatUIKitSwift

let users = CometChatUsers()

users.set(onError: { error in
    print("Error loading users: \(error.errorDescription)")
})
```

#### onEmpty

Fires when the user list is empty.

```swift lines theme={null}
import CometChatUIKitSwift

let users = CometChatUsers()

users.set(onEmpty: {
    print("No users found")
})
```

#### onLoad

Fires when users are successfully loaded. The callback receives a nested array where each inner array represents a section of users (grouped alphabetically).

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

users.set(onLoad: { userSections in
    let totalUsers = userSections.flatMap { $0 }.count
    print("Loaded \(totalUsers) users across \(userSections.count) sections")
})
```

### Actions Reference

| Method                  | Description                           | Example            |
| ----------------------- | ------------------------------------- | ------------------ |
| `set(onItemClick:)`     | Triggered when a user is tapped       | Start conversation |
| `set(onItemLongClick:)` | Triggered on long press               | Show options menu  |
| `set(onBack:)`          | Triggered when back button is pressed | Custom navigation  |
| `set(onSelection:)`     | Triggered in selection mode           | Multi-select users |
| `set(onError:)`         | Triggered when an error occurs        | Show error alert   |
| `set(onEmpty:)`         | Triggered when list is empty          | Show empty state   |
| `set(onLoad:)`          | Triggered when users load             | Analytics tracking |

### Global UI Events

| Event             | Fires when          | Payload |
| ----------------- | ------------------- | ------- |
| `ccUserBlocked`   | A user is blocked   | `User`  |
| `ccUserUnblocked` | A user is unblocked | `User`  |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

class MyViewController: UIViewController, CometChatUserEventListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CometChatUserEvents.addListener("my-listener", self)
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        CometChatUserEvents.removeListener("my-listener")
    }
    
    func onUserBlock(user: User) {
        print("User blocked: \(user.name ?? "")")
    }
    
    func onUserUnblock(user: User) {
        print("User unblocked: \(user.name ?? "")")
    }
}
```

### SDK Events (Real-Time, Automatic)

| SDK Listener    | Internal behavior                   |
| --------------- | ----------------------------------- |
| `onUserOnline`  | Updates status indicator to online  |
| `onUserOffline` | Updates status indicator to offline |

***

## Custom View Slots

| Slot               | Signature           | Replaces               |
| ------------------ | ------------------- | ---------------------- |
| `listItemView`     | `(User) -> UIView`  | Entire user row        |
| `leadingView`      | `(User) -> UIView`  | Avatar / left section  |
| `titleView`        | `(User?) -> UIView` | Name / title text      |
| `subtitleView`     | `(User?) -> UIView` | Status / subtitle text |
| `trailingView`     | `(User?) -> UIView` | Right side content     |
| `emptyStateView`   | `() -> UIView`      | Empty state display    |
| `errorStateView`   | `() -> UIView`      | Error state display    |
| `loadingStateView` | `() -> UIView`      | Loading state display  |

### listItemView

Replace the entire user row with a custom design.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

users.set(listItemView: { user in
    let customView = UIView()
    customView.backgroundColor = UIColor.systemBackground
    
    let avatar = CometChatAvatar(image: UIImage())
    avatar.setAvatar(avatarUrl: user.avatar, with: user.name ?? "")
    
    let nameLabel = UILabel()
    nameLabel.text = user.name
    nameLabel.font = UIFont.systemFont(ofSize: 16, weight: .semibold)
    
    let statusLabel = UILabel()
    statusLabel.text = user.status == .online ? "🟢 Online" : "⚫ Offline"
    statusLabel.font = UIFont.systemFont(ofSize: 12)
    statusLabel.textColor = UIColor.secondaryLabel
    
    customView.addSubview(avatar)
    customView.addSubview(nameLabel)
    customView.addSubview(statusLabel)
    
    return customView
})
```

### leadingView

Customize the leading view (avatar area) of a user cell.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

users.set(leadingView: { user in
    let view = CustomLeadingView(image: UIImage(named: "avatar"))
    return view
})
```

<Frame>
  <img alt="CometChatUsers with custom leadingView showing user avatars with a star badge overlay" />
</Frame>

You can create a `CustomLeadingView` as a custom `UIView`:

```swift lines theme={null}
import UIKit

class CustomLeadingView: UIView {
    
    // MARK: - UI Components
    private let imageView: UIImageView = {
        let imageView = UIImageView()
        imageView.contentMode = .scaleAspectFill
        imageView.clipsToBounds = true
        imageView.layer.cornerRadius = 10
        return imageView
    }()
    
    private let badgeView: UIView = {
        let view = UIView()
        view.backgroundColor = .orange
        view.layer.cornerRadius = 12
        view.layer.borderWidth = 2
        view.layer.borderColor = UIColor.white.cgColor
        
        let icon = UIImageView(image: UIImage(systemName: "star.fill"))
        icon.tintColor = .white
        icon.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(icon)
        
        NSLayoutConstraint.activate([
            icon.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            icon.centerYAnchor.constraint(equalTo: view.centerYAnchor),
            icon.widthAnchor.constraint(equalToConstant: 14),
            icon.heightAnchor.constraint(equalToConstant: 14)
        ])
        
        return view
    }()
    
    // MARK: - Initialization
    init(image: UIImage?) {
        super.init(frame: .zero)
        imageView.image = image
        
        addSubview(imageView)
        addSubview(badgeView)
        
        imageView.translatesAutoresizingMaskIntoConstraints = false
        badgeView.translatesAutoresizingMaskIntoConstraints = false
        
        NSLayoutConstraint.activate([
            imageView.topAnchor.constraint(equalTo: topAnchor),
            imageView.leadingAnchor.constraint(equalTo: leadingAnchor),
            imageView.trailingAnchor.constraint(equalTo: trailingAnchor),
            imageView.bottomAnchor.constraint(equalTo: bottomAnchor),
            
            badgeView.widthAnchor.constraint(equalToConstant: 24),
            badgeView.heightAnchor.constraint(equalToConstant: 24),
            badgeView.bottomAnchor.constraint(equalTo: imageView.bottomAnchor, constant: -4),
            badgeView.trailingAnchor.constraint(equalTo: imageView.trailingAnchor, constant: -4)
        ])
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
}
```

### titleView

Customize the title view of a user cell.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

users.set(titleView: { user in
    let view = CustomTitleView(name: user.name ?? "", role: "Teacher")
    return view
})
```

<Frame>
  <img alt="CometChatUsers with custom titleView showing user names with a green Teacher badge" />
</Frame>

You can create a `CustomTitleView` as a custom `UIView`:

```swift lines theme={null}
import UIKit

class CustomTitleView: UIView {
    
    // MARK: - UI Components
    private let nameLabel: UILabel = {
        let label = UILabel()
        label.font = UIFont.boldSystemFont(ofSize: 18)
        label.textColor = .black
        return label
    }()
    
    private let badgeLabel: UILabel = {
        let label = UILabel()
        label.font = UIFont.systemFont(ofSize: 14)
        label.textColor = .white
        label.backgroundColor = .systemGreen
        label.text = "Teacher"
        label.textAlignment = .center
        label.layer.cornerRadius = 8
        label.layer.masksToBounds = true
        return label
    }()
    
    // MARK: - Initialization
    init(name: String, role: String) {
        super.init(frame: .zero)
        nameLabel.text = name
        badgeLabel.text = " \(role) "
        
        let stackView = UIStackView(arrangedSubviews: [nameLabel, badgeLabel])
        stackView.axis = .horizontal
        stackView.spacing = 8
        stackView.alignment = .center
        
        addSubview(stackView)
        stackView.translatesAutoresizingMaskIntoConstraints = false
        
        NSLayoutConstraint.activate([
            stackView.leadingAnchor.constraint(equalTo: leadingAnchor),
            stackView.trailingAnchor.constraint(equalTo: trailingAnchor),
            stackView.topAnchor.constraint(equalTo: topAnchor),
            stackView.bottomAnchor.constraint(equalTo: bottomAnchor)
        ])
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
}
```

### subtitleView

Customize the subtitle area below the user name.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

users.set(subtitleView: { user in
    let view = CustomSubtitleView(lastActiveDate: "2 hours ago")
    return view
})
```

<Frame>
  <img alt="CometChatUsers with custom subtitleView showing last active timestamp below user names" />
</Frame>

You can create a `CustomSubtitleView` as a custom `UIView`:

```swift lines theme={null}
import UIKit

class CustomSubtitleView: UILabel {
    
    init(lastActiveDate: String) {
        super.init(frame: .zero)
        self.text = "Last Active at: \(lastActiveDate)"
        self.textColor = UIColor.gray
        self.font = UIFont.systemFont(ofSize: 14)
        self.numberOfLines = 1
    }
    
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
}
```

### trailingView

Customize the trailing view (right side) of a user cell.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

users.set(trailView: { user in
    let view = CustomTrailView()
    return view
})
```

<Frame>
  <img alt="CometChatUsers with custom trailingView showing a purple PRO badge with star icon" />
</Frame>

You can create a `CustomTrailView` as a custom `UIView`:

```swift lines theme={null}
import UIKit

class CustomTrailView: UIView {
    
    // MARK: - UI Components
    private let badgeView: UIView = {
        let view = UIView()
        view.backgroundColor = .purple
        view.layer.cornerRadius = 12
        view.translatesAutoresizingMaskIntoConstraints = false
        return view
    }()
    
    private let icon: UIImageView = {
        let imageView = UIImageView(image: UIImage(systemName: "star.fill"))
        imageView.tintColor = .white
        imageView.translatesAutoresizingMaskIntoConstraints = false
        return imageView
    }()
    
    private let label: UILabel = {
        let label = UILabel()
        label.text = "PRO"
        label.font = UIFont.boldSystemFont(ofSize: 14)
        label.textColor = .white
        label.translatesAutoresizingMaskIntoConstraints = false
        return label
    }()
    
    // MARK: - Initialization
    init() {
        super.init(frame: .zero)
        
        addSubview(badgeView)
        badgeView.addSubview(icon)
        badgeView.addSubview(label)
        
        NSLayoutConstraint.activate([
            badgeView.leadingAnchor.constraint(equalTo: leadingAnchor),
            badgeView.trailingAnchor.constraint(equalTo: trailingAnchor),
            badgeView.topAnchor.constraint(equalTo: topAnchor),
            badgeView.bottomAnchor.constraint(equalTo: bottomAnchor),
            
            icon.centerXAnchor.constraint(equalTo: badgeView.centerXAnchor),
            icon.topAnchor.constraint(equalTo: badgeView.topAnchor, constant: 4),
            icon.widthAnchor.constraint(equalToConstant: 16),
            icon.heightAnchor.constraint(equalToConstant: 16),
            
            label.centerXAnchor.constraint(equalTo: badgeView.centerXAnchor),
            label.topAnchor.constraint(equalTo: icon.bottomAnchor, constant: 2),
            label.bottomAnchor.constraint(equalTo: badgeView.bottomAnchor, constant: -4)
        ])
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
}
```

### loadingStateView

Customize the loading state view displayed while data is being fetched.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let users = CometChatUsers()

let loadingIndicator = UIActivityIndicatorView(style: .medium)
loadingIndicator.startAnimating()
users.set(loadingView: loadingIndicator)
```

### errorStateView

Customize the error state view displayed when an error occurs.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let users = CometChatUsers()

let errorLabel = UILabel()
errorLabel.text = "Something went wrong!"
errorLabel.textColor = .red
users.set(errorView: errorLabel)
```

### emptyStateView

Customize the empty state view displayed when no users are available.

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

let users = CometChatUsers()

let emptyLabel = UILabel()
emptyLabel.text = "No users found"
emptyLabel.textColor = .gray
emptyLabel.textAlignment = .center
users.set(emptyView: emptyLabel)
```

***

## Methods

### Swipe Action Methods

#### set(options:)

Sets custom swipe actions for user list items, replacing the default options. These options appear when the user swipes on a user cell.

```swift lines theme={null}
@discardableResult
public func set(options: ((_ user: User?) -> [CometChatUserOption])?) -> Self
```

| Parameter | Type                                  | Description                                                      |
| --------- | ------------------------------------- | ---------------------------------------------------------------- |
| `options` | `((User?) -> [CometChatUserOption])?` | Closure that returns an array of swipe action options for a user |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

users.set(options: { user in
    var options = [CometChatUserOption]()
    
    // Add block option
    let blockOption = CometChatUserOption(
        id: "block",
        title: "Block",
        icon: UIImage(systemName: "hand.raised"),
        backgroundColor: .systemRed
    ) { selectedUser in
        // Handle block action
        print("Block user: \(selectedUser?.name ?? "")")
    }
    options.append(blockOption)
    
    // Add message option
    let messageOption = CometChatUserOption(
        id: "message",
        title: "Message",
        icon: UIImage(systemName: "message"),
        backgroundColor: .systemBlue
    ) { selectedUser in
        // Handle message action
        print("Message user: \(selectedUser?.name ?? "")")
    }
    options.append(messageOption)
    
    return options
})
```

#### add(options:)

Adds additional swipe actions to the existing default options.

```swift lines theme={null}
@discardableResult
public func add(options: ((_ user: User?) -> [CometChatUserOption])?) -> Self
```

| Parameter | Type                                  | Description                                                    |
| --------- | ------------------------------------- | -------------------------------------------------------------- |
| `options` | `((User?) -> [CometChatUserOption])?` | Closure that returns additional swipe action options to append |

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

users.add(options: { user in
    var options = [CometChatUserOption]()
    
    // Add favorite option
    let favoriteOption = CometChatUserOption(
        id: "favorite",
        title: "Favorite",
        icon: UIImage(systemName: "star.fill"),
        backgroundColor: .systemOrange
    ) { selectedUser in
        print("Favorite user: \(selectedUser?.name ?? "")")
    }
    options.append(favoriteOption)
    
    return options
})
```

### Data Manipulation Methods

#### add(user:)

Adds a new user to the user list.

```swift lines theme={null}
@discardableResult
public func add(user: User) -> Self
```

| Parameter | Type   | Description                 |
| --------- | ------ | --------------------------- |
| `user`    | `User` | The user to add to the list |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

// Add a user programmatically
let newUser = User(uid: "user-123", name: "John Doe")
users.add(user: newUser)
```

#### update(user:)

Updates an existing user in the list.

```swift lines theme={null}
@discardableResult
public func update(user: User) -> Self
```

| Parameter | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| `user`    | `User` | The user with updated information |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

// Update a user's information
if var existingUser = userToUpdate {
    existingUser.name = "Updated Name"
    users.update(user: existingUser)
}
```

#### remove(user:)

Removes a user from the list.

```swift lines theme={null}
@discardableResult
public func remove(user: User) -> Self
```

| Parameter | Type   | Description                      |
| --------- | ------ | -------------------------------- |
| `user`    | `User` | The user to remove from the list |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

// Remove a user from the UI
users.remove(user: userToRemove)
```

#### getSelectedUsers()

Returns an array of currently selected users when in selection mode.

```swift lines theme={null}
public func getSelectedUsers() -> [User]
```

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()
users.selectionMode = .multiple

// Get all selected users
let selectedUsers = users.getSelectedUsers()
print("Selected \(selectedUsers.count) users")

for user in selectedUsers {
    print("User: \(user.name ?? "")")
}
```

***

## Custom ListItem

For more complex or unique list items, you can create a custom `UIView` file named `CustomListItem` and integrate it into the `set(listItemView:)` method.

<Frame>
  <img alt="CometChatUsers with custom listItemView showing a simplified user row with avatar and name" />
</Frame>

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class CustomListItem: UIView {
    
    // MARK: - UI Components
    private var profileImageView: CometChatAvatar = {
        let imageView = CometChatAvatar(image: UIImage())
        imageView.translatesAutoresizingMaskIntoConstraints = false
        return imageView
    }()

    private var nameLabel: UILabel = {
        let label = UILabel()
        label.translatesAutoresizingMaskIntoConstraints = false
        return label
    }()

    // MARK: - Initialization
    override init(frame: CGRect) {
        super.init(frame: frame)
        setupUI()
    }

    required init?(coder aDecoder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    // MARK: - Setup
    private func setupUI() {
        addSubview(profileImageView)
        addSubview(nameLabel)

        NSLayoutConstraint.activate([
            // Profile image constraints
            profileImageView.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 8),
            profileImageView.centerYAnchor.constraint(equalTo: centerYAnchor),
            profileImageView.widthAnchor.constraint(equalToConstant: 40),
            profileImageView.heightAnchor.constraint(equalToConstant: 40),
            
            // Name label constraints
            nameLabel.leadingAnchor.constraint(equalTo: profileImageView.trailingAnchor, constant: 8),
            nameLabel.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -8),
            nameLabel.centerYAnchor.constraint(equalTo: centerYAnchor)
        ])
    }

    // MARK: - Configuration
    func set(user: User) {
        nameLabel.text = user.name
        profileImageView.setAvatar(avatarUrl: user.avatar, with: user.name)
    }
}
```

Usage:

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()

users.set(listItemView: { user in
    let customItem = CustomListItem()
    customItem.set(user: user)
    return customItem
})
```

***

## Styling

### Style Hierarchy

1. Global styles (`CometChatUsers.style`) apply to all instances
2. Instance styles override global for specific instances

### Global Level Styling

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

// Apply global styles that affect all CometChatUsers instances
CometChatUsers.style.backgroundColor = UIColor.systemBackground
CometChatUsers.style.titleColor = UIColor.label
CometChatUsers.style.titleFont = UIFont.systemFont(ofSize: 34, weight: .bold)
CometChatUsers.style.listItemTitleTextColor = UIColor.label
CometChatUsers.style.listItemSubTitleTextColor = UIColor.secondaryLabel

// Custom avatar style
let avatarStyle = AvatarStyle()
avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 20)
CometChatUsers.avatarStyle = avatarStyle
```

### Instance Level Styling

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

// Create a custom style for a specific instance
var customStyle = UsersStyle()
customStyle.backgroundColor = UIColor(red: 0.95, green: 0.95, blue: 0.97, alpha: 1.0)
customStyle.titleColor = UIColor.darkGray
customStyle.listItemBackground = UIColor.white

let users = CometChatUsers()
users.style = customStyle
```

<Frame>
  <img alt="CometChatUsers with custom styling showing modified background colors and text appearance" />
</Frame>

### Key Style Properties

| Property                    | Type       | Default                               | Description            |
| --------------------------- | ---------- | ------------------------------------- | ---------------------- |
| `backgroundColor`           | `UIColor`  | `CometChatTheme.backgroundColor01`    | Background color       |
| `titleColor`                | `UIColor`  | `CometChatTheme.textColorPrimary`     | Navigation title color |
| `titleFont`                 | `UIFont`   | `CometChatTypography.Heading4.medium` | Navigation title font  |
| `listItemTitleTextColor`    | `UIColor`  | `CometChatTheme.textColorPrimary`     | User name color        |
| `listItemTitleFont`         | `UIFont`   | `CometChatTypography.Heading4.medium` | User name font         |
| `listItemSubTitleTextColor` | `UIColor`  | `CometChatTheme.textColorSecondary`   | Status text color      |
| `listItemSubTitleFont`      | `UIFont`   | `CometChatTypography.Body.regular`    | Status text font       |
| `listItemBackground`        | `UIColor`  | `.clear`                              | List item background   |
| `searchBarBackgroundColor`  | `UIColor?` | `nil`                                 | Search bar background  |
| `searchBarTextColor`        | `UIColor?` | `nil`                                 | Search bar text color  |
| `headerTitleColor`          | `UIColor`  | `CometChatTheme.textColorHighlight`   | Section header color   |
| `headerTitleFont`           | `UIFont`   | `CometChatTypography.Heading4.medium` | Section header font    |

### Customization Matrix

| What to change    | Where     | Property/API               | Example                            |
| ----------------- | --------- | -------------------------- | ---------------------------------- |
| Background color  | Style     | `backgroundColor`          | `UIColor.systemBackground`         |
| Title appearance  | Style     | `titleColor`, `titleFont`  | Custom colors and fonts            |
| List item look    | Style     | `listItemBackground`       | `UIColor.white`                    |
| Avatar appearance | Style     | `avatarStyle`              | `AvatarStyle()` with custom radius |
| Search bar        | Style     | `searchBarBackgroundColor` | Custom background                  |
| Hide search       | Property  | `hideSearch`               | `users.hideSearch = true`          |
| Hide status       | Property  | `hideUserStatus`           | `users.hideUserStatus = true`      |
| Custom row        | View Slot | `set(listItemView:)`       | See Custom View Slots              |

***

## Props

All props are optional. Sorted alphabetically.

### avatarStyle

Customizes the appearance of avatars in user list items.

|         |                 |
| ------- | --------------- |
| Type    | `AvatarStyle`   |
| Default | `AvatarStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let users = CometChatUsers()

let avatarStyle = AvatarStyle()
avatarStyle.backgroundColor = UIColor.systemBlue
avatarStyle.cornerRadius = CometChatCornerStyle(cornerRadius: 8)
avatarStyle.borderWidth = 1
avatarStyle.borderColor = UIColor.systemGray4

users.set(avatarStyle: avatarStyle)
```

### hideBackButton

Hides the back button in the navigation bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideErrorView

Hides the error state view.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideLoadingState

Hides the loading state indicator.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideNavigationBar

Hides the entire navigation bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideSearch

Hides the search bar.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideSectionHeader

Hides the alphabetical section headers.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### hideUserStatus

Hides online/offline status indicators.

|         |         |
| ------- | ------- |
| Type    | `Bool`  |
| Default | `false` |

### onSelectedItemProceed

Callback triggered when the user confirms their selection in selection mode. Use this to handle the selected users.

|         |                       |
| ------- | --------------------- |
| Type    | `(([User]) -> Void)?` |
| Default | `nil`                 |

```swift lines theme={null}
import CometChatUIKitSwift
import CometChatSDK

let users = CometChatUsers()
users.selectionMode = .multiple
users.selectionLimit = 5

users.onSelectedItemProceed = { selectedUsers in
    print("Proceeding with \(selectedUsers.count) users")
    
    // Process the selected users
    for user in selectedUsers {
        print("User: \(user.name ?? "")")
    }
}
```

### searchRequestBuilder

Custom request builder for search functionality.

|         |                                     |
| ------- | ----------------------------------- |
| Type    | `UsersRequest.UsersRequestBuilder?` |
| Default | `nil`                               |

### selectedCellCount

Returns the count of currently selected users in selection mode.

|         |       |
| ------- | ----- |
| Type    | `Int` |
| Default | `0`   |

### selectionLimit

Sets the maximum number of users that can be selected in selection mode. When the limit is reached, further selections are disabled.

|         |                 |
| ------- | --------------- |
| Type    | `Int`           |
| Default | `0` (unlimited) |

```swift lines theme={null}
import CometChatUIKitSwift

let users = CometChatUsers()
users.selectionMode = .multiple

// Limit selection to 5 users
users.selectionLimit = 5

// Handle selection confirmation
users.onSelectedItemProceed = { selectedUsers in
    print("Selected \(selectedUsers.count) users")
    
    // Process the selected users
    for user in selectedUsers {
        print("User: \(user.name ?? "")")
    }
}
```

### selectionMode

Sets the selection mode for multi-select functionality.

|         |                 |
| ------- | --------------- |
| Type    | `SelectionMode` |
| Default | `.none`         |

### statusIndicatorStyle

Customizes the appearance of online/offline status indicators.

|         |                          |
| ------- | ------------------------ |
| Type    | `StatusIndicatorStyle`   |
| Default | `StatusIndicatorStyle()` |

```swift lines theme={null}
import CometChatUIKitSwift

let users = CometChatUsers()

let statusIndicatorStyle = StatusIndicatorStyle()
statusIndicatorStyle.backgroundColor = UIColor.systemGreen
statusIndicatorStyle.borderWidth = 2
statusIndicatorStyle.borderColor = UIColor.white

users.set(statusIndicatorStyle: statusIndicatorStyle)
```

### usersRequestBuilder

Custom request builder for filtering users.

|         |                                     |
| ------- | ----------------------------------- |
| Type    | `UsersRequest.UsersRequestBuilder?` |
| Default | `nil`                               |

***

## Events

| Event             | Payload | Fires when          |
| ----------------- | ------- | ------------------- |
| `ccUserBlocked`   | `User`  | A user is blocked   |
| `ccUserUnblocked` | `User`  | A user is unblocked |

***

## Common Patterns

### Friends-only list

```swift lines theme={null}
let friendsBuilder = UsersRequest.UsersRequestBuilder(limit: 30)
    .friendsOnly(true)

let users = CometChatUsers()
users.set(usersRequestBuilder: friendsBuilder)
```

### Online users only

```swift lines theme={null}
let onlineBuilder = UsersRequest.UsersRequestBuilder(limit: 30)
    .set(status: .online)

let users = CometChatUsers()
users.set(usersRequestBuilder: onlineBuilder)
```

### Custom empty state with CTA

```swift lines theme={null}
let users = CometChatUsers()

users.set(emptyStateView: {
    let emptyView = UIView()
    
    let label = UILabel()
    label.text = "No users found"
    label.textAlignment = .center
    label.textColor = .secondaryLabel
    
    let button = UIButton(type: .system)
    button.setTitle("Invite friends", for: .normal)
    
    // Add subviews and constraints...
    return emptyView
})
```

### Hide all chrome — minimal list

```swift lines theme={null}
let users = CometChatUsers()
users.hideSearch = true
users.hideUserStatus = true
users.hideSectionHeader = true
```

### Multi-select users

```swift lines theme={null}
let users = CometChatUsers()
users.selectionMode = .multiple

users.set(onSelection: { selectedUsers in
    print("Selected \(selectedUsers.count) users")
    // Create group with selected users, etc.
})
```

***

## Related Components

* [Messages](/docs/ui-kit/ios/message-list) - Display messages with a user
* [Conversations](/docs/ui-kit/ios/conversations) - List all conversations
* [Groups](/docs/ui-kit/ios/groups) - List all groups
* [Users With Messages](/docs/ui-kit/ios/users) - Combined users and messages view


# AI Assistant Chat History
Source: https://www.cometchat.com/docs/ui-kit/android/ai-assistant-chat-history

Displays the conversation history between users and an AI assistant for easy review of past interactions.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatAIAssistantChatHistory",
    "package": "com.cometchat.uikit.kotlin.presentation.aiassistantchathistory",
    "xmlElement": "<com.cometchat.uikit.kotlin.presentation.aiassistantchathistory.ui.CometChatAIAssistantChatHistory />",
    "description": "Displays the conversation history between users and an AI assistant for easy review of past interactions.",
    "primaryOutput": {
      "method": "setOnItemClickListener",
      "type": "OnItemClickListener<BaseMessage>"
    },
    "methods": {
      "data": {
        "setUser": {
          "type": "User",
          "required": true,
          "note": "User must have role set to @agentic"
        }
      },
      "callbacks": {
        "setOnItemClickListener": "OnItemClickListener<BaseMessage>",
        "setOnItemLongClickListener": "OnItemLongClickListener<BaseMessage>",
        "setOnNewChatClickListener": "OnClick",
        "setOnCloseClickListener": "OnClick"
      },
      "visibility": {
        "setErrorStateVisibility": { "type": "int (View.VISIBLE | View.GONE)", "default": "View.VISIBLE" },
        "setEmptyStateVisibility": { "type": "int (View.VISIBLE | View.GONE)", "default": "View.VISIBLE" }
      },
      "style": {
        "setStyle": {
          "type": "@StyleRes int",
          "parent": "CometChatAIAssistantChatHistoryStyle"
        }
      }
    },
    "events": [],
    "sdkListeners": []
  }
  ```
</Accordion>

## Quick Start

1. Open your layout XML file.
2. Add the `CometChatAIAssistantChatHistory` XML element:

```xml lines theme={null}
<com.cometchat.uikit.kotlin.presentation.aiassistantchathistory.ui.CometChatAIAssistantChatHistory
    android:id="@+id/cometchat_ai_assistant_chat_history"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>
```

> **What this does:** Adds the `CometChatAIAssistantChatHistory` component to your layout. It fills the available width and height and renders the AI assistant chat history list.

3. In your Activity or Fragment, create a `User` object with the role set to `@agentic` and pass it to the component:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val user = User()
    user.uid = "userId"
    user.name = "User Name"
    user.role = "@agentic" // User role must be @agentic to use AI Assistant features

    binding.cometChatAiAssistantChatHistory.setUser(user)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.compose.presentation.aiassistantchathistory.ui.CometChatAIAssistantChatHistory

    @Composable
    fun AIAssistantChatHistoryScreen() {
        CometChatAIAssistantChatHistory(
            modifier = Modifier.fillMaxSize(),
            onCloseClick = { /* handle close */ },
            onNewChatClick = { /* handle new chat */ },
            onItemClick = { message -> /* handle item click */ }
        )
    }
    ```
  </Tab>
</Tabs>

> **What this does:** Creates a `User` object with the `@agentic` role and sets it on the `CometChatAIAssistantChatHistory` component. This is required for the component to fetch and display the AI assistant chat histories for that user.

4. Build and run your app.
5. Verify that the AI assistant chat history list appears with past conversation items.

<Frame>
  <img />
</Frame>

## Core Concepts

* **`CometChatAIAssistantChatHistory`**: The main component class that renders the AI assistant chat history list. It is a Composite Component that can be launched via button clicks or any user-triggered action.
* **Actions**: Callbacks such as `setOnItemClickListener`, `setOnItemLongClickListener`, `setOnNewChatClickListener`, and `setOnCloseClickListener` that let you respond to user interactions.
* **Style**: XML theme styles applied via `setStyle()` to customize colors, fonts, and visual appearance of the chat history.
* **Functionality**: Methods like `setUser`, `setErrorStateVisibility`, and `setEmptyStateVisibility` that configure the component's behavior and state visibility.

## Actions and Events

### Callback Methods

What you're changing: How the component responds to user interactions such as taps, long-presses, new chat clicks, and close clicks.

* **Where**: Activity or Fragment where you hold a reference to `CometChatAIAssistantChatHistory`.
* **Applies to**: `CometChatAIAssistantChatHistory`.
* **Default behavior**: Predefined actions execute automatically when the user interacts with the component.
* **Override**: Call the corresponding setter method to replace the default behavior with your own logic.

#### `setOnItemClickListener`

Function invoked when a chat history item is clicked, used to open an AI assistant chat screen.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin YourActivity.kt lines theme={null}
    binding.cometchatAiAssistantChatHistory.setOnItemClickListener { view, position, message ->

            }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.compose.presentation.aiassistantchathistory.ui.CometChatAIAssistantChatHistory

    CometChatAIAssistantChatHistory(
        onItemClick = { message ->
            Log.i(TAG, "Item clicked: ${message.id}")
        }
    )
    ```
  </Tab>
</Tabs>

> **What this does:** Replaces the default item-click behavior. When a user taps a chat history item, your custom lambda executes instead of the built-in navigation.

#### `setOnItemLongClickListener`

Function executed when a chat history item is long-pressed, allowing additional actions like delete or block.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin YourActivity.kt lines theme={null}
    binding.cometchatAiAssistantChatHistory.setOnItemLongClickListener { view, position, message ->

            }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatAIAssistantChatHistory(
        onItemLongClick = { message ->
            Log.i(TAG, "Item long clicked: ${message.id}")
        }
    )
    ```
  </Tab>
</Tabs>

> **What this does:** Replaces the default long-press behavior. When a user long-presses a chat history item, your custom lambda executes.

#### `setOnNewChatClickListener`

Function triggered when the new chat button is clicked, used to start a new conversation with the AI assistant.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin YourActivity.kt lines theme={null}
    binding.cometchatAiAssistantChatHistory.setOnNewChatClickListener {

            }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatAIAssistantChatHistory(
        onNewChatClick = {
            Log.i(TAG, "New chat clicked")
        }
    )
    ```
  </Tab>
</Tabs>

> **What this does:** Replaces the default new-chat-click behavior. When the user taps the new chat button, your custom logic runs instead of the built-in action.

#### `setOnCloseClickListener`

Function activated when the close button is clicked, used to exit the chat history view.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin YourActivity.kt lines theme={null}
    binding.cometchatAiAssistantChatHistory.setOnCloseClickListener {

            }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatAIAssistantChatHistory(
        onCloseClick = {
            Log.i(TAG, "Close clicked")
        }
    )
    ```
  </Tab>
</Tabs>

> **What this does:** Replaces the default close-click behavior. When the user taps the close button, your custom logic runs instead of the built-in exit action.

* **Verify**: After setting an action callback, trigger the corresponding user interaction (tap, long-press, new chat, close) and confirm your custom logic executes instead of the default behavior.

## Styling

What you're changing: The visual appearance of the AI Assistant Chat History component using XML theme styles.

* **Where**: `themes.xml` for style definitions, and your Activity/Fragment for applying the style.
* **Applies to**: `CometChatAIAssistantChatHistory`.
* **Default behavior**: The component uses its default style.
* **Override**: Define a custom style in `themes.xml`, then call `setStyle()` on the component.

<Frame>
  <img />
</Frame>

* **Code**:

```xml themes.xml lines theme={null}
<style name="CustomAIAssistantChatHistoryStyle">
    <item name="cometChatAIAssistantChatHistoryBackgroundColor">#FFFAF6</item>
    <item name="cometChatAIAssistantChatHistoryHeaderBackgroundColor">#FFFAF6</item>
    <item name="cometChatAIAssistantChatHistoryHeaderTextColor">?attr/cometchatTextColorPrimary</item>
    <item name="cometChatAIAssistantChatHistoryHeaderTextAppearance">@style/textStyleTimesNewRoman</item>
    <item name="cometChatAIAssistantChatHistoryNewChatBackgroundColor">#FFFAF6</item>
    <item name="cometChatAIAssistantChatHistoryNewChatTextColor">?attr/cometchatTextColorPrimary</item>
    <item name="cometChatAIAssistantChatHistoryNewChatTextAppearance">@style/textStyleTimesNewRoman</item>
    <item name="cometChatAIAssistantChatHistoryDateSeparatorTextAppearance">@style/textStyleTimesNewRoman</item>
    <item name="cometChatAIAssistantChatHistoryDateSeparatorTextColor">?attr/cometchatTextColorTertiary</item>
    <item name="cometChatAIAssistantChatHistoryDateSeparatorBackgroundColor">#FFFAF6</item>
    <item name="cometChatAIAssistantChatHistoryItemBackgroundColor">#FFFAF6</item>
    <item name="cometChatAIAssistantChatHistoryItemTextAppearance">@style/textStyleTimesNewRoman</item>
    <item name="cometChatAIAssistantChatHistoryItemTextColor">?attr/cometchatTextColorPrimary</item>
</style>

<style name="textStyleTimesNewRoman">
    <item name="android:fontFamily">@font/times_new_roman_regular</item>
</style>
```

> **What this does:** Defines a custom style `CustomAIAssistantChatHistoryStyle` that sets the background color to `#FFFAF6` for the component, header, new chat area, date separator, and items. It applies a Times New Roman font to the header, new chat text, date separator, and item text. A helper style `textStyleTimesNewRoman` defines the font family.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatAiAssistantChatHistory.setStyle(R.style.CustomAIAssistantChatHistoryStyle);
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.compose.presentation.aiassistantchathistory.style.CometChatAIAssistantChatHistoryStyle

    CometChatAIAssistantChatHistory(
        style = CometChatAIAssistantChatHistoryStyle.default().copy(
            chatHistoryBackgroundColor = Color(0xFFEDEAFA)
        )
    )
    ```
  </Tab>
</Tabs>

> **What this does:** Applies the `CustomAIAssistantChatHistoryStyle` theme to the `CometChatAIAssistantChatHistory` component, changing the background colors and fonts.

To know more such attributes, visit the [attributes file](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_ai_assistant_chat_history.xml).

* **Verify**: The chat history component displays with the `#FFFAF6` background color and Times New Roman font for header text, new chat text, date separator text, and item text.

## Functionality

What you're changing: Small functional customizations such as setting the user and toggling visibility of UI states.

* **Where**: Activity or Fragment where you hold a reference to `CometChatAIAssistantChatHistory`.
* **Applies to**: `CometChatAIAssistantChatHistory`.
* **Default behavior**: All UI states are visible with default settings.
* **Override**: Call the corresponding method on the component instance.

| Methods                   | Description                                                                                                                                                                 | Code                                   |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `setUser`                 | Sets the user whose chat histories with the AI assistant need to be fetched. This is a required property for the component to function. The user's role must be `@agentic`. | `.setUser(user);`                      |
| `setErrorStateVisibility` | Toggles the visibility of the error state of the component                                                                                                                  | `.setErrorStateVisibility(View.GONE);` |
| `setEmptyStateVisibility` | Toggles the visibility of the empty state of the component                                                                                                                  | `.setEmptyStateVisibility(View.GONE);` |

* **Verify**: After calling `setUser(user)`, confirm the component fetches and displays the AI assistant chat histories for that user. After calling a visibility method, confirm the corresponding UI state is shown or hidden.

## Customization Matrix

| What you want to change           | Where             | Property/API                                                  | Example                                                                                                        |
| --------------------------------- | ----------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Component background color        | `themes.xml`      | `cometChatAIAssistantChatHistoryBackgroundColor`              | `<item name="cometChatAIAssistantChatHistoryBackgroundColor">#FFFAF6</item>`                                   |
| Header background color           | `themes.xml`      | `cometChatAIAssistantChatHistoryHeaderBackgroundColor`        | `<item name="cometChatAIAssistantChatHistoryHeaderBackgroundColor">#FFFAF6</item>`                             |
| Header text color                 | `themes.xml`      | `cometChatAIAssistantChatHistoryHeaderTextColor`              | `<item name="cometChatAIAssistantChatHistoryHeaderTextColor">?attr/cometchatTextColorPrimary</item>`           |
| Header text appearance            | `themes.xml`      | `cometChatAIAssistantChatHistoryHeaderTextAppearance`         | `<item name="cometChatAIAssistantChatHistoryHeaderTextAppearance">@style/textStyleTimesNewRoman</item>`        |
| New chat background color         | `themes.xml`      | `cometChatAIAssistantChatHistoryNewChatBackgroundColor`       | `<item name="cometChatAIAssistantChatHistoryNewChatBackgroundColor">#FFFAF6</item>`                            |
| New chat text color               | `themes.xml`      | `cometChatAIAssistantChatHistoryNewChatTextColor`             | `<item name="cometChatAIAssistantChatHistoryNewChatTextColor">?attr/cometchatTextColorPrimary</item>`          |
| New chat text appearance          | `themes.xml`      | `cometChatAIAssistantChatHistoryNewChatTextAppearance`        | `<item name="cometChatAIAssistantChatHistoryNewChatTextAppearance">@style/textStyleTimesNewRoman</item>`       |
| Date separator text appearance    | `themes.xml`      | `cometChatAIAssistantChatHistoryDateSeparatorTextAppearance`  | `<item name="cometChatAIAssistantChatHistoryDateSeparatorTextAppearance">@style/textStyleTimesNewRoman</item>` |
| Date separator text color         | `themes.xml`      | `cometChatAIAssistantChatHistoryDateSeparatorTextColor`       | `<item name="cometChatAIAssistantChatHistoryDateSeparatorTextColor">?attr/cometchatTextColorTertiary</item>`   |
| Date separator background color   | `themes.xml`      | `cometChatAIAssistantChatHistoryDateSeparatorBackgroundColor` | `<item name="cometChatAIAssistantChatHistoryDateSeparatorBackgroundColor">#FFFAF6</item>`                      |
| Item background color             | `themes.xml`      | `cometChatAIAssistantChatHistoryItemBackgroundColor`          | `<item name="cometChatAIAssistantChatHistoryItemBackgroundColor">#FFFAF6</item>`                               |
| Item text appearance              | `themes.xml`      | `cometChatAIAssistantChatHistoryItemTextAppearance`           | `<item name="cometChatAIAssistantChatHistoryItemTextAppearance">@style/textStyleTimesNewRoman</item>`          |
| Item text color                   | `themes.xml`      | `cometChatAIAssistantChatHistoryItemTextColor`                | `<item name="cometChatAIAssistantChatHistoryItemTextColor">?attr/cometchatTextColorPrimary</item>`             |
| Apply a custom style              | Activity/Fragment | `setStyle(int styleRes)`                                      | `binding.cometchatAiAssistantChatHistory.setStyle(R.style.CustomAIAssistantChatHistoryStyle);`                 |
| Set the user for fetching history | Activity/Fragment | `setUser(User)`                                               | `.setUser(user);`                                                                                              |
| Error state visibility            | Activity/Fragment | `setErrorStateVisibility(int)`                                | `.setErrorStateVisibility(View.GONE);`                                                                         |
| Empty state visibility            | Activity/Fragment | `setEmptyStateVisibility(int)`                                | `.setEmptyStateVisibility(View.GONE);`                                                                         |

## Next Steps

<CardGroup>
  <Card title="Message List" icon="messages" href="/ui-kit/android/message-list">
    Display messages in a conversation
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/android/conversations">
    Browse recent conversations
  </Card>

  <Card title="Users" icon="user" href="/ui-kit/android/users">
    Browse and search available users
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/ui-kit/android/search">
    Search across conversations and messages
  </Card>
</CardGroup>


# Smart Chat Features
Source: https://www.cometchat.com/docs/ui-kit/android/ai-features

Integrate AI-powered conversation starters, smart replies, and conversation summaries into your Android chat app.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                               |
  | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Packages       | `com.cometchat:chatuikit-kotlin-android` (Java), `com.cometchat:chatuikit-kotlin-android` (Kotlin XML), `com.cometchat:chatuikit-compose-android` (Jetpack Compose) |
  | Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login()` + AI features enabled in [CometChat Dashboard](/docs/fundamentals/ai-user-copilot/overview)                        |
  | AI features    | Conversation Starter, Smart Replies, Conversation Summary                                                                                                           |
  | Key components | [Message List](/docs/ui-kit/android/message-list) (Conversation Starter), [Message Composer](/docs/ui-kit/android/message-composer) (Smart Replies, Summary)                  |
  | Activation     | Enable each AI feature from the CometChat Dashboard — UI Kit auto-integrates them, no additional code required                                                      |
  | Related        | [Core Features](/docs/ui-kit/android/core-features), [Extensions](/docs/ui-kit/android/extensions), [AI Agent Guide](/docs/ui-kit/android/guide-ai-agent)                          |
</Accordion>

CometChat's AI capabilities greatly enhance user interaction and engagement in your application. Here's how the Android UI Kit integrates these features.

<Frame>
  <img />
</Frame>

## Conversation Starter

When a user initiates a new chat, the UI kit displays a list of suggested opening lines that users can select, making it easier for them to start a conversation. These suggestions are powered by CometChat's AI, which predicts contextually relevant conversation starter options.

For a comprehensive understanding and guide on implementing and using the Conversation Starter, refer to our specific guide on the [Conversation Starter](/docs/fundamentals/ai-user-copilot/conversation-starter).

Once you have successfully activated the [Conversation Starter](/docs/fundamentals/ai-user-copilot/conversation-starter) from your CometChat Dashboard, the feature will automatically be incorporated into the [MessageList](/docs/ui-kit/android/message-list) Component of UI Kits.

<Frame>
  <img />
</Frame>

## Smart Replies

Smart Replies are AI-generated responses to messages. They can predict what a user might want to say next by analyzing the context of the conversation. This allows for quicker and more convenient responses, especially on mobile devices.

For a comprehensive understanding and guide on implementing and using the Smart Replies, refer to our specific guide on the [Smart Replies](/docs/fundamentals/ai-user-copilot/smart-replies).

Once you have successfully activated the [Smart Replies](/docs/fundamentals/ai-user-copilot/smart-replies) from your CometChat Dashboard, the feature will automatically be incorporated into the Action sheet of [MessageComposer](/docs/ui-kit/android/message-composer) Component of UI Kits.

<Frame>
  <img />
</Frame>

## Conversation Summary

The Conversation Summary feature provides concise summaries of long conversations, allowing users to catch up quickly on missed chats. This feature uses natural language processing to determine the main points in a conversation.

For a comprehensive understanding and guide on implementing and using the Conversation Summary, refer to our specific guide on the [Conversation Summary](/docs/fundamentals/ai-user-copilot/conversation-summary).

Once you have successfully activated the [Conversation Summary](/docs/fundamentals/ai-user-copilot/conversation-summary) from your CometChat Dashboard, the feature will automatically be incorporated into the Action sheet of [MessageComposer](/docs/ui-kit/android/message-composer) Component of UI Kits.

<Frame>
  <img />
</Frame>


# Architecture & Data Flow
Source: https://www.cometchat.com/docs/ui-kit/android/architecture-data-flow

How chatuikit-core, chatuikit-jetpack, and chatuikit-kotlin modules are structured using Clean Architecture.

The UI Kit is split into three modules that follow Clean Architecture principles. `chatuikit-core` holds all business logic, data access, and state management. The UI modules (`chatuikit-jetpack` and `chatuikit-kotlin`) provide platform-specific rendering on top of the shared core.

## Module Structure

```mermaid theme={null}
graph TD
    subgraph UI["UI Modules"]
        A["<b>chatuikit-jetpack</b><br/><i>Jetpack Compose UI</i><br/>Composables, Themes"]
        B["<b>chatuikit-kotlin</b><br/><i>XML Views / ViewBinding</i><br/>Custom Views, Adapters"]
    end

    subgraph Core["chatuikit-core"]
        D["domain/ — usecase, repository interfaces, models"]
        E["data/ — datasource, repository implementations"]
        F["viewmodel/ — shared ViewModels"]
        G["state/ — sealed UIState classes"]
        H["events/ — CometChatEvents SharedFlow bus"]
        I["factory/ — ViewModel factories"]
        J["formatter, mentions, resources, utils"]
    end

    K["<b>CometChat SDK</b><br/>Chat SDK 4.x · Calls SDK 4.x"]

    A -->|depends on| Core
    B -->|depends on| Core
    Core -->|calls| K

```

## 4-Layer Architecture

Every feature follows the same layered flow: **View → ViewModel → Repository → DataSource**.

```mermaid theme={null}
block-beta
    columns 1
    A["View / Composable\nchatuikit-kotlin or chatuikit-jetpack"]
    B["ViewModel\nchatuikit-core"]
    C["Repository\nchatuikit-core"]
    D["DataSource\nchatuikit-core → CometChat SDK"]

    A --> B
    B --> C
    C --> D
```

The ViewModel lives in `chatuikit-core` and is shared by both UI modules. This means the same `CometChatConversationsViewModel` drives both the XML View and the Composable — only the rendering layer differs.

## Clean Architecture Layers (chatuikit-core)

### Data Layer

The data layer wraps the CometChat SDK behind interfaces, making it swappable and testable.

**DataSource** — defines the contract for raw SDK operations:

```kotlin theme={null}
// Interface (contract)
interface ConversationsDataSource {
    suspend fun fetchConversations(request: ConversationsRequest): List<Conversation>
    suspend fun deleteConversation(conversationWith: String, conversationType: String): String
    suspend fun markAsDelivered(message: BaseMessage)
}

// Implementation (calls CometChat SDK)
class ConversationsDataSourceImpl : ConversationsDataSource {
    override suspend fun fetchConversations(request: ConversationsRequest): List<Conversation> {
        // Wraps CometChat.fetchConversations() in a coroutine
    }
}
```

Every feature has a DataSource pair: `ConversationsDataSource` / `ConversationsDataSourceImpl`, `UsersDataSource` / `UsersDataSourceImpl`, etc.

**Repository Implementation** — coordinates data sources and handles error wrapping:

```kotlin theme={null}
class ConversationsRepositoryImpl(
    private val dataSource: ConversationsDataSource
) : ConversationsRepository {

    private var hasMore = true

    override suspend fun getConversations(
        request: ConversationsRequest
    ): Result<List<Conversation>> {
        return try {
            val conversations = dataSource.fetchConversations(request)
            hasMore = conversations.isNotEmpty()
            Result.success(conversations)
        } catch (e: CometChatException) {
            Result.failure(e)
        }
    }
}
```

Repositories wrap raw SDK exceptions into Kotlin `Result` types, track pagination state, and coordinate between data sources.

### Domain Layer

The domain layer defines contracts and single-purpose use cases. It has no dependency on the SDK or Android framework.

**Repository Interfaces** — contracts that the data layer implements:

```kotlin theme={null}
interface ConversationsRepository {
    suspend fun getConversations(request: ConversationsRequest): Result<List<Conversation>>
    suspend fun deleteConversation(conversationWith: String, conversationType: String): Result<Unit>
    suspend fun markAsDelivered(conversation: Conversation): Result<Unit>
    fun hasMoreConversations(): Boolean
}
```

**Use Cases** — encapsulate a single business action:

```kotlin theme={null}
open class GetConversationsUseCase(
    private val repository: ConversationsRepository
) {
    open suspend operator fun invoke(
        request: ConversationsRequest
    ): Result<List<Conversation>> {
        return repository.getConversations(request)
    }

    open fun hasMore(): Boolean = repository.hasMoreConversations()
}
```

Use cases are `open` so they can be overridden for testing or custom behavior. Each use case does one thing:

| Use Case                                                                          | Action                        |
| --------------------------------------------------------------------------------- | ----------------------------- |
| `GetConversationsUseCase`                                                         | Fetch paginated conversations |
| `DeleteConversationUseCase`                                                       | Delete a conversation         |
| `RefreshConversationsUseCase`                                                     | Clear and re-fetch            |
| `FetchUsersUseCase` / `SearchUsersUseCase`                                        | Fetch or search users         |
| `FetchGroupsUseCase`                                                              | Fetch groups                  |
| `FetchGroupMembersUseCase` / `SearchGroupMembersUseCase`                          | Fetch or search group members |
| `BanGroupMemberUseCase` / `KickGroupMemberUseCase`                                | Member moderation             |
| `ChangeMemberScopeUseCase`                                                        | Change member role            |
| `SendTextMessageUseCase` / `SendMediaMessageUseCase` / `SendCustomMessageUseCase` | Send messages                 |
| `EditMessageUseCase`                                                              | Edit a sent message           |
| `FetchCallLogsUseCase`                                                            | Fetch call history            |
| `InitiateCallUseCase` / `InitiateUserCallUseCase` / `StartGroupCallUseCase`       | Start calls                   |
| `FetchReactionsUseCase` / `RemoveReactionUseCase`                                 | Reaction management           |
| `CreatePollUseCase`                                                               | Create a poll                 |
| `GetStickersUseCase`                                                              | Fetch sticker sets            |
| `JoinGroupUseCase` / `GetGroupUseCase` / `GetUserUseCase`                         | Entity lookups                |

### ViewModel Layer

ViewModels receive use cases via constructor injection and expose `StateFlow` / sealed `UIState` classes to the UI:

```kotlin theme={null}
class CometChatConversationsViewModel(
    private val getConversationsUseCase: GetConversationsUseCase,
    private val deleteConversationUseCase: DeleteConversationUseCase,
    private val refreshConversationsUseCase: RefreshConversationsUseCase,
    private val enableListeners: Boolean = true
) : ViewModel() {

    // UI observes this sealed state
    private val _uiState = MutableStateFlow<UIState>(UIState.Loading)
    val uiState: StateFlow<UIState> = _uiState

    fun fetchConversations() {
        viewModelScope.launch {
            getConversationsUseCase(request)
                .onSuccess { conversations ->
                    _uiState.value = if (conversations.isEmpty()) UIState.Empty
                                     else UIState.Content(conversations)
                }
                .onFailure { _uiState.value = UIState.Error(it) }
        }
    }
}
```

### State Management (StateFlow + Sealed Classes)

Each feature has a dedicated sealed UIState class. All state is exposed via `StateFlow` — not LiveData:

```kotlin theme={null}
sealed class UIState {
    object Loading : UIState()
    object Empty : UIState()
    data class Error(val exception: CometChatException) : UIState()
    data class Content(val conversations: List<Conversation>) : UIState()
}
```

Feature-specific states include additional fields:

| State Class                                                          | Feature           | Extra Fields                  |
| -------------------------------------------------------------------- | ----------------- | ----------------------------- |
| `ConversationStarterUIState`                                         | Conversation list | —                             |
| `MessageListUIState`                                                 | Message list      | scroll position, reply state  |
| `MessageComposerUIState`                                             | Composer          | attachment state, edit mode   |
| `MessageHeaderUIState`                                               | Header            | typing indicator, user status |
| `GroupsUIState`                                                      | Groups            | —                             |
| `UsersUIState`                                                       | Users             | —                             |
| `GroupMembersUIState`                                                | Group members     | scope change state            |
| `CallLogsUIState`                                                    | Call logs         | —                             |
| `CallButtonsUIState`                                                 | Call buttons      | call initiation state         |
| `IncomingCallUIState` / `OutgoingCallUIState` / `OngoingCallUIState` | Calls             | call session state            |
| `ReactionListUIState`                                                | Reactions         | —                             |
| `CreatePollUIState`                                                  | Polls             | form validation state         |
| `StickerKeyboardUIState`                                             | Stickers          | sticker sets                  |

### ListOperations Interface

List-based ViewModels implement the `ListOperations` interface, which provides a standard contract for manipulating list data:

```kotlin theme={null}
interface ListOperations<T> {
    fun addAtIndex(index: Int, item: T)
    fun updateAtIndex(index: Int, item: T)
    fun removeAtIndex(index: Int)
    fun moveToTop(item: T)
}
```

This ensures consistent list manipulation across Conversations, Users, Groups, Group Members, and Call Logs.

## Dependency Injection via Factories

ViewModels are created through `ViewModelProvider.Factory` classes that wire up the dependency chain:

```kotlin theme={null}
class CometChatConversationsViewModelFactory(
    private val repository: ConversationsRepository = ConversationsRepositoryImpl(
        ConversationsDataSourceImpl()
    ),
    private val enableListeners: Boolean = true
) : ViewModelProvider.Factory {

    override fun <T : ViewModel> create(modelClass: Class<T>): T {
        val getUseCase = GetConversationsUseCase(repository)
        val deleteUseCase = DeleteConversationUseCase(repository)
        val refreshUseCase = RefreshConversationsUseCase(repository)

        return CometChatConversationsViewModel(
            getConversationsUseCase = getUseCase,
            deleteConversationUseCase = deleteUseCase,
            refreshConversationsUseCase = refreshUseCase,
            enableListeners = enableListeners
        ) as T
    }
}
```

Default implementations are provided, but you can inject custom repositories:

```kotlin theme={null}
// Custom repository for testing or caching
val factory = CometChatConversationsViewModelFactory(
    repository = MyCustomConversationRepository(),
    enableListeners = false  // disable for previews
)
```

## Data Flow: End to End

### Fetching Conversations

```mermaid theme={null}
graph TD
    A["UI — Composable / View<br/><i>collects uiState</i>"] --> B["CometChatConversationsViewModel<br/><i>calls getConversationsUseCase</i>"]
    B --> C["GetConversationsUseCase<br/><i>calls repository.getConversations</i>"]
    C --> D["ConversationsRepositoryImpl<br/><i>calls dataSource, wraps Result, tracks pagination</i>"]
    D --> E["ConversationsDataSourceImpl<br/><i>calls CometChat SDK</i>"]
    E --> F["CometChat SDK → REST API → Response"]

```

### Real-Time Updates

```mermaid theme={null}
graph TD
    A["CometChat SDK — WebSocket<br/><i>onTextMessageReceived / onTypingStarted</i>"] --> B["ViewModel — SDK listener<br/><i>processes event, updates internal list</i>"]
    B --> C["Emits new UIState.Content — updatedList"]
    C --> D["UI recomposes / rebinds automatically"]

```

### User Action (Delete Conversation)

```mermaid theme={null}
graph TD
    A["UI — user swipes to delete"] --> B["ViewModel.deleteConversation"]
    B --> C["DeleteConversationUseCase"]
    C --> D["ConversationsRepositoryImpl"]
    D --> E["DataSource → CometChat SDK → REST API → 200 OK"]
    E --> F["ViewModel removes item → emits updated UIState"]

```

## Component ↔ Core Mapping

| UI Component      | Core ViewModel                         | Use Cases                                    | Repository                     | DataSource                     |
| ----------------- | -------------------------------------- | -------------------------------------------- | ------------------------------ | ------------------------------ |
| Conversation List | `CometChatConversationsViewModel`      | Get, Delete, Refresh                         | `ConversationsRepository`      | `ConversationsDataSource`      |
| Message List      | `CometChatMessageListViewModel`        | (message fetching)                           | `MessageListRepository`        | `MessageListDataSource`        |
| Message Composer  | `CometChatMessageComposerViewModel`    | SendText, SendMedia, SendCustom, Edit        | `MessageComposerRepository`    | `MessageComposerDataSource`    |
| Message Header    | `CometChatMessageHeaderViewModel`      | —                                            | `MessageHeaderRepository`      | `MessageHeaderDataSource`      |
| Users             | `CometChatUsersViewModel`              | FetchUsers, SearchUsers                      | `UsersRepository`              | `UsersDataSource`              |
| Groups            | `CometChatGroupsViewModel`             | FetchGroups, JoinGroup                       | `GroupsRepository`             | `GroupsDataSource`             |
| Group Members     | `CometChatGroupMembersViewModel`       | FetchMembers, Search, Ban, Kick, ChangeScope | `GroupMembersRepository`       | `GroupMembersDataSource`       |
| Call Logs         | `CometChatCallLogsViewModel`           | FetchCallLogs                                | `CallLogsRepository`           | `CallLogsDataSource`           |
| Call Buttons      | `CometChatCallButtonsViewModel`        | InitiateCall, StartGroupCall                 | `CallButtonsRepository`        | `CallButtonsDataSource`        |
| Reactions         | `CometChatReactionListViewModel`       | FetchReactions, RemoveReaction               | `ReactionListRepository`       | `ReactionListDataSource`       |
| Message Info      | `CometChatMessageInformationViewModel` | —                                            | `MessageInformationRepository` | `MessageInformationDataSource` |

## Events (Cross-Component Communication)

The `CometChatEvents` singleton in `chatuikit-core` provides a typed event bus using Kotlin `SharedFlow` for communication between components that don't share a ViewModel:

| Event Flow                           | Emitted When                               |
| ------------------------------------ | ------------------------------------------ |
| `CometChatEvents.messageEvents`      | Message sent, edited, deleted, reacted     |
| `CometChatEvents.conversationEvents` | Conversation deleted                       |
| `CometChatEvents.groupEvents`        | Group created, member added/removed/banned |
| `CometChatEvents.userEvents`         | User blocked/unblocked                     |
| `CometChatEvents.callEvents`         | Call initiated, accepted, rejected         |
| `CometChatEvents.uiEvents`           | UI-level events (show dialog, navigate)    |

See the [Events reference](/docs/ui-kit/android/events) for sealed class types and subscription examples.

## Component-Level Overrides

Every layer in the architecture is designed to be replaceable. You can override at the level that makes sense for your use case — from swapping the entire data source to just tweaking a single use case.

### Override Points

```mermaid theme={null}
graph TD
    A["UI Component"] --> B["ViewModel ← inject via custom Factory"]
    B --> C["UseCase ← subclass (open classes)"]
    C --> D["Repository ← implement interface"]
    D --> E["DataSource ← implement interface"]
```

### 1. Custom Repository

The most common override. Implement the repository interface and pass it to the factory.

```kotlin theme={null}
class OfflineUsersRepository : UsersRepository {

    private val cachedUsers = listOf(/* local data */)

    override suspend fun getUsers(request: UsersRequest): Result<List<User>> {
        return Result.success(cachedUsers)
    }

    override fun hasMoreUsers(): Boolean = false
}
```

Wire it in:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    val factory = CometChatUsersViewModelFactory(
        repository = OfflineUsersRepository(),
        enableListeners = false
    )
    val viewModel = ViewModelProvider(this, factory)[CometChatUsersViewModel::class.java]

    val usersView = findViewById<CometChatUsers>(R.id.users)
    usersView.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    val factory = CometChatUsersViewModelFactory(
        repository = OfflineUsersRepository(),
        enableListeners = false
    )
    val viewModel: CometChatUsersViewModel = viewModel(factory = factory)

    CometChatUsers(
        usersViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

### 2. Custom DataSource

Override at the lowest level to change how SDK calls are made — useful for caching, offline support, or wrapping a different backend.

```kotlin theme={null}
class CachedUsersDataSource(
    private val sdkDataSource: UsersDataSourceImpl = UsersDataSourceImpl(),
    private val cache: UserCache
) : UsersDataSource {

    override suspend fun fetchUsers(request: UsersRequest): List<User> {
        val cached = cache.get(request)
        if (cached != null) return cached

        val users = sdkDataSource.fetchUsers(request)
        cache.put(request, users)
        return users
    }
}
```

Then wrap it in the default repository implementation:

```kotlin theme={null}
val dataSource = CachedUsersDataSource(cache = myCache)
val repository = UsersRepositoryImpl(dataSource)
val factory = CometChatUsersViewModelFactory(repository = repository)
```

### 3. Custom Use Cases

Use cases are `open` classes, so you can subclass them to add validation, logging, or transformation:

```kotlin theme={null}
class LoggingGetConversationsUseCase(
    repository: ConversationsRepository
) : GetConversationsUseCase(repository) {

    override suspend operator fun invoke(
        request: ConversationsRequest
    ): Result<List<Conversation>> {
        Log.d("Conversations", "Fetching conversations...")
        val result = super.invoke(request)
        result.onSuccess { Log.d("Conversations", "Fetched ${it.size} items") }
        result.onFailure { Log.e("Conversations", "Fetch failed", it) }
        return result
    }
}
```

### 4. Passing a Custom ViewModel to the UI Component

Both `chatuikit-jetpack` (Compose) and `chatuikit-kotlin` (XML Views) accept a pre-built ViewModel. This is the entry point for all overrides.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    class MyUsersActivity : AppCompatActivity() {
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.activity_users)

            val factory = CometChatUsersViewModelFactory(
                repository = MyCustomUsersRepository()
            )
            val viewModel = ViewModelProvider(this, factory)[CometChatUsersViewModel::class.java]

            val usersView = findViewById<CometChatUsers>(R.id.users)
            usersView.setViewModel(viewModel)
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    @Composable
    fun MyUsersScreen() {
        val factory = CometChatUsersViewModelFactory(
            repository = MyCustomUsersRepository(),
            enableListeners = true
        )
        val viewModel: CometChatUsersViewModel = viewModel(factory = factory)

        CometChatUsers(
            usersViewModel = viewModel,
            style = CometChatUsersStyle.default(),
            hideToolbar = false,
            hideSearchBox = false
        )
    }
    ```
  </Tab>
</Tabs>

### 5. Disabling Listeners for Previews and Testing

Every factory accepts `enableListeners = false`. When disabled, the ViewModel won't register SDK listeners or UIKit event subscriptions — useful for Compose previews, unit tests, or showcase screens:

```kotlin theme={null}
val factory = CometChatConversationsViewModelFactory(
    repository = FakeConversationRepository(),
    enableListeners = false  // No WebSocket listeners, no event subscriptions
)
```

### Override Summary by Component

| Component         | Factory Class                              | Repository Interface        | Key Use Cases                                |
| ----------------- | ------------------------------------------ | --------------------------- | -------------------------------------------- |
| Conversation List | `CometChatConversationsViewModelFactory`   | `ConversationsRepository`   | Get, Delete, Refresh                         |
| Users             | `CometChatUsersViewModelFactory`           | `UsersRepository`           | FetchUsers, SearchUsers                      |
| Groups            | `CometChatGroupsViewModelFactory`          | `GroupsRepository`          | FetchGroups, JoinGroup                       |
| Group Members     | `CometChatGroupMembersViewModelFactory`    | `GroupMembersRepository`    | FetchMembers, Search, Ban, Kick, ChangeScope |
| Message List      | `CometChatMessageListViewModelFactory`     | `MessageListRepository`     | (message fetching)                           |
| Message Composer  | `CometChatMessageComposerViewModelFactory` | `MessageComposerRepository` | SendText, SendMedia, SendCustom, Edit        |
| Call Logs         | `CometChatCallLogsViewModelFactory`        | `CallLogsRepository`        | FetchCallLogs                                |
| Call Buttons      | `CometChatCallButtonsViewModelFactory`     | `CallButtonsRepository`     | InitiateCall, StartGroupCall                 |
| Reactions         | `CometChatReactionListViewModelFactory`    | `ReactionListRepository`    | FetchReactions, RemoveReaction               |

## Related

* [Events](/docs/ui-kit/android/events) — Cross-component communication via `CometChatEvents` SharedFlow
* [Methods](/docs/ui-kit/android/methods) — UI Kit wrapper methods for init, auth, and messaging


# Call Buttons
Source: https://www.cometchat.com/docs/ui-kit/android/call-buttons

Voice and video call buttons that initiate calls for a given user or group.

`CometChatCallButtons` renders voice and video call buttons and initiates calls for the bound `User` or `Group`. Place it in a `CometChatMessageHeader` or anywhere a call action is needed.

***

## Where It Fits

`CometChatCallButtons` is a utility component. Wire it into a `CometChatMessageHeader` or place it standalone wherever a call action is needed.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_chat.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.callbuttons.CometChatCallButtons
        android:id="@+id/call_buttons"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content" />
    ```

    ```kotlin lines theme={null}
    val callButtons = findViewById<CometChatCallButtons>(R.id.call_buttons)
    callButtons.setUser(user)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallButtons(
        user = user
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add to your layout XML:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.callbuttons.CometChatCallButtons
        android:id="@+id/call_buttons"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content" />
    ```

    Set a `User` or `Group` — required before calls can be initiated:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.your_layout)

        val callButtons = findViewById<CometChatCallButtons>(R.id.call_buttons)
        callButtons.setUser(user)
        // or callButtons.setGroup(group)
    }
    ```

    Or programmatically:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val callButtons = CometChatCallButtons(this)
        callButtons.setUser(user)
        setContentView(callButtons)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    @Composable
    fun CallButtonsScreen() {
        CometChatCallButtons(
            user = user
            // or group = group
        )
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

> You must call `setUser(User)` or `setGroup(Group)` before the buttons can initiate a call. Without a target, button clicks have no effect.

***

## Actions and Events

### Callback Methods

#### `onVoiceCallClick`

Fires when the voice call button is tapped. Replaces the default behavior of initiating an audio call.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callButtons.setOnVoiceCallClick { user, group ->
        // Custom voice call logic
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallButtons(
        user = user,
        onVoiceCallClick = { u, g ->
            // Custom voice call logic
        }
    )
    ```
  </Tab>
</Tabs>

#### `onVideoCallClick`

Fires when the video call button is tapped. Replaces the default behavior of initiating a video call.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callButtons.setOnVideoCallClick { user, group ->
        // Custom video call logic
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallButtons(
        user = user,
        onVideoCallClick = { u, g ->
            // Custom video call logic
        }
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callButtons.setOnError { exception ->
        Log.e("CallButtons", "Error: ${exception.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallButtons(
        user = user,
        onError = { exception ->
            Log.e("CallButtons", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

### Global UI Events (CometChatCallEvents)

| Event            | Fires when                          | Payload |
| ---------------- | ----------------------------------- | ------- |
| `ccOutgoingCall` | An outgoing call is initiated       | `Call`  |
| `ccCallAccepted` | A call is accepted by the recipient | `Call`  |
| `ccCallRejected` | A call is rejected by the recipient | `Call`  |
| `ccCallEnded`    | A call is ended                     | `Call`  |

***

## Functionality

| Method (Kotlin XML)                       | Compose Parameter            | Description                                      |
| ----------------------------------------- | ---------------------------- | ------------------------------------------------ |
| `setUser(user)`                           | `user = user`                | Set the user to call (required for 1-on-1)       |
| `setGroup(group)`                         | `group = group`              | Set the group to call (required for group calls) |
| `setOnVoiceCallClick { }`                 | `onVoiceCallClick = { }`     | Override voice call button behavior              |
| `setOnVideoCallClick { }`                 | `onVideoCallClick = { }`     | Override video call button behavior              |
| `setOnError { }`                          | `onError = { }`              | Error callback                                   |
| `setVoiceCallButtonVisibility(View.GONE)` | `hideVoiceCallButton = true` | Toggle voice call button                         |
| `setVideoCallButtonVisibility(View.GONE)` | `hideVideoCallButton = true` | Toggle video call button                         |

***

## Style

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Define a custom style in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="CustomCallButtonsStyle" parent="CometChatCallButtonsStyle">
        <item name="cometchatCallButtonsVoiceCallIconTint">#4CAF50</item>
        <item name="cometchatCallButtonsVideoCallIconTint">#2196F3</item>
        <item name="cometchatCallButtonsVoiceCallBackgroundColor">#E8F5E9</item>
        <item name="cometchatCallButtonsVideoCallBackgroundColor">#E3F2FD</item>
    </style>
    ```

    ```kotlin lines theme={null}
    callButtons.setStyle(R.style.CustomCallButtonsStyle)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallButtons(
        user = user,
        style = CometChatCallButtonsStyle.default().copy(
            voiceCallIconTint = Color(0xFF4CAF50),
            videoCallIconTint = Color(0xFF2196F3),
            voiceCallBackgroundColor = Color(0xFFE8F5E9),
            videoCallBackgroundColor = Color(0xFFE3F2FD)
        )
    )
    ```
  </Tab>
</Tabs>

See [Component Styling](/docs/ui-kit/android/component-styling) for the full reference.

***

## ViewModel

```kotlin lines theme={null}
val viewModel = ViewModelProvider(this)
    .get(CometChatCallButtonsViewModel::class.java)
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callButtons.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallButtons(
        user = user,
        callButtonsViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

See [ViewModel & Data](/docs/ui-kit/android/customization-viewmodel-data) for state observation and custom repositories.

***

## Next Steps

<CardGroup>
  <Card title="Call Logs" icon="clock-rotate-left" href="/ui-kit/android/call-logs">
    View call history
  </Card>

  <Card title="Incoming Call" icon="phone-arrow-down-left" href="/ui-kit/android/incoming-call">
    Incoming call notification with accept/reject
  </Card>

  <Card title="Outgoing Call" icon="phone-arrow-up-right" href="/ui-kit/android/outgoing-call">
    Outgoing call screen with end-call button
  </Card>

  <Card title="Message Header" icon="heading" href="/ui-kit/android/message-header">
    Display user/group info in the toolbar
  </Card>
</CardGroup>


# Call
Source: https://www.cometchat.com/docs/ui-kit/android/call-features

Add one-on-one and group audio/video calling to your Android app using the CometChat Calls SDK and UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field              | Value                                                                                                                                                                |
  | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Kotlin (XML Views) | `com.cometchat:chatuikit-kotlin-android` + `com.cometchat:calls-sdk-android`                                                                                         |
  | Jetpack Compose    | `com.cometchat:chatuikit-compose-android` + `com.cometchat:calls-sdk-android`                                                                                        |
  | Required setup     | `CometChatUIKit.init()` then `CometChatUIKit.login()` — Calls SDK must also be installed                                                                             |
  | Call features      | Incoming Call, Outgoing Call, Call Logs, Call Buttons, Ongoing Call                                                                                                  |
  | Key components     | `CometChatCallButtons`, `CometChatIncomingCall`, `CometChatOutgoingCall`, `CometChatCallLogs`, `CometChatOngoingCall`                                                |
  | Auto-detection     | UI Kit automatically detects the Calls SDK and enables call UI components                                                                                            |
  | Related            | [Getting Started](/docs/ui-kit/android/getting-started), [Core Features](/docs/ui-kit/android/core-features), [Call Log Details Guide](/docs/ui-kit/android/guide-call-log-details) |
</Accordion>

CometChat's Calls feature allows you to seamlessly integrate one-on-one as well as group audio and video calling capabilities into your application. This document provides a technical overview of these features, as implemented in the Android UI Kit.

## Integration

First, make sure that you've correctly integrated the UI Kit library into your project. If you haven't done this yet or are facing difficulties, refer to our [Getting Started](/docs/ui-kit/android/getting-started) guide.

Once you've successfully integrated the UI Kit, the next step is to add the CometChat Calls SDK to your project. This is necessary to enable the calling features in the UI Kit.

### Step 1: Add Calls SDK Dependency

Add the following dependency to your `build.gradle.kts` file:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin build.gradle.kts theme={null}
    dependencies {
        implementation("com.cometchat:chatuikit-kotlin-android:6.0.3")
        implementation("com.cometchat:calls-sdk-android:5.0.1")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin build.gradle.kts theme={null}
    dependencies {
        implementation("com.cometchat:chatuikit-compose-android:6.0.3")
        implementation("com.cometchat:calls-sdk-android:5.0.1")
    }
    ```
  </Tab>
</Tabs>

After adding this dependency, sync your project. The Android UI Kit will automatically detect the Calls SDK and activate the calling features.

### Step 2: Verify Call Buttons Appear

Once the Calls SDK is integrated, you will see the `CometChatCallButtons` component automatically rendered in the [MessageHeader](/docs/ui-kit/android/message-header) component. This provides users with quick access to initiate audio and video calls.

<Frame>
  <img />
</Frame>

### Step 3: Add Call Listener for Incoming Calls

To receive incoming calls globally in your app, you will need to add a `CallListener`. This should be added before you initialize the CometChat UI Kit. We recommend creating a custom Application class and adding the call listener there.

When an incoming call is received, you can display the `CometChatIncomingCall` component using the current activity context.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    class BaseApplication : Application() {

        companion object {
            private val LISTENER_ID = "${BaseApplication::class.java.simpleName}${System.currentTimeMillis()}"
        }

        override fun onCreate() {
            super.onCreate()

            CometChat.addCallListener(LISTENER_ID, object : CometChat.CallListener {
                override fun onIncomingCallReceived(call: Call) {
                    // Get the current activity context
                    val currentActivity = getCurrentActivity() // Implement this method

                    currentActivity?.let {
                        // Create and display the incoming call component
                        val incomingCallView = CometChatIncomingCall(it)
                        incomingCallView.call = call
                        incomingCallView.fitsSystemWindows = true
                        incomingCallView.onError = OnError { exception ->
                            // Handle errors
                        }

                        // Display the component (e.g., as dialog or snackbar)
                    }
                }

                override fun onOutgoingCallAccepted(call: Call) {
                    // Handle outgoing call acceptance
                }

                override fun onOutgoingCallRejected(call: Call) {
                    // Handle outgoing call rejection
                }

                override fun onIncomingCallCancelled(call: Call) {
                    // Handle incoming call cancellation
                }
            })
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    class BaseApplication : Application() {

        companion object {
            private val LISTENER_ID = "${BaseApplication::class.java.simpleName}${System.currentTimeMillis()}"
        }

        override fun onCreate() {
            super.onCreate()

            CometChat.addCallListener(LISTENER_ID, object : CometChat.CallListener {
                override fun onIncomingCallReceived(call: Call) {
                    CometChatCallActivity.launchIncomingCallScreen(this@BaseApplication, call, null)
                    // Pass null or IncomingCallConfiguration if need to configure CometChatIncomingCall component
                }

                override fun onOutgoingCallAccepted(call: Call) {
                    // Handle outgoing call acceptance
                }

                override fun onOutgoingCallRejected(call: Call) {
                    // Handle outgoing call rejection
                }

                override fun onIncomingCallCancelled(call: Call) {
                    // Handle incoming call cancellation
                }
            })
        }
    }
    ```
  </Tab>
</Tabs>

## Call Components

The CometChat Android UI Kit provides five main components for implementing calling features in your app. Each component handles a specific part of the calling experience.

### Call Buttons

The `CometChatCallButtons` component provides users with quick access to initiate audio and video calls. This component is automatically rendered in the [MessageHeader](/docs/ui-kit/android/message-header) when the Calls SDK is integrated.

<Frame>
  <img />
</Frame>

[Learn more about Call Buttons →](/docs/ui-kit/android/call-buttons)

### Incoming Call

The `CometChatIncomingCall` component displays when a user receives an incoming call. It provides a full-screen interface showing caller information and call controls.

<Frame>
  <img />
</Frame>

[Learn more about Incoming Call →](/docs/ui-kit/android/incoming-call)

### Outgoing Call

The `CometChatOutgoingCall` component manages the outgoing call experience. It displays while waiting for the recipient to answer and automatically transitions to the active call screen once accepted.

<Frame>
  <img />
</Frame>

[Learn more about Outgoing Call →](/docs/ui-kit/android/outgoing-call)

### Call Logs

The `CometChatCallLogs` component displays a history of all call activities, including missed, received, and dialed calls. Users can view call details and initiate new calls from the log.

<Frame>
  <img />
</Frame>

[Learn more about Call Logs →](/docs/ui-kit/android/call-logs)

### Ongoing Call

The `CometChatOngoingCall` component renders the active call screen with video feeds, mute/unmute controls, camera toggle, and end-call actions.

### Call Log Details

For detailed information about individual calls, including participants, join/leave history, and recordings, see the [Call Log Details](/docs/ui-kit/android/guide-call-log-details) guide.


# Call Logs
Source: https://www.cometchat.com/docs/ui-kit/android/call-logs

Scrollable list of call logs for the logged-in user with caller names, avatars, call status, and timestamps.

`CometChatCallLogs` renders a scrollable list of call logs for the logged-in user with caller names, avatars, call status indicators, and timestamps.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatCallLogs` is a list component. It renders the user's call history and emits the selected `CallLog` via `onItemClick`. Use it as a standalone call history screen or as a tab in a tabbed layout alongside conversations and contacts.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_call_logs.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.calllogs.ui.CometChatCallLogs
        android:id="@+id/call_logs"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    ```kotlin lines theme={null}
    val callLogs = findViewById<CometChatCallLogs>(R.id.call_logs)

    callLogs.setOnItemClick { callLog ->
        // Navigate to call detail or initiate call
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        modifier = Modifier.fillMaxSize(),
        onItemClick = { callLog ->
            // Navigate to call detail or initiate call
        }
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add to your layout XML:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.calllogs.ui.CometChatCallLogs
        android:id="@+id/call_logs"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    Or programmatically:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(CometChatCallLogs(this))
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    @Composable
    fun CallLogsScreen() {
        CometChatCallLogs(
            modifier = Modifier.fillMaxSize()
        )
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, the UI Kit dependency added, and the CometChat Calls SDK configured.

Or in a Fragment:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
        return CometChatCallLogs(requireContext())
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
        return ComposeView(requireContext()).apply {
            setContent { CometChatCallLogs() }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Filtering Call Logs

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Pass a `CallLogRequest.CallLogRequestBuilder` to control what loads:

    ```kotlin lines theme={null}
    callLogs.setCallLogRequestBuilder(
        CallLogRequest.CallLogRequestBuilder()
            .setLimit(20)
            .setCallCategory(CometChatConstants.CALL_CATEGORY_CALL)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        callLogRequestBuilder = CallLogRequest.CallLogRequestBuilder()
            .setLimit(20)
            .setCallCategory(CometChatConstants.CALL_CATEGORY_CALL)
    )
    ```
  </Tab>
</Tabs>

### Filter Recipes

| Recipe           | Builder method                                            |
| ---------------- | --------------------------------------------------------- |
| Limit per page   | `.setLimit(10)`                                           |
| Audio calls only | `.setCallType(CometChatConstants.CALL_TYPE_AUDIO)`        |
| Video calls only | `.setCallType(CometChatConstants.CALL_TYPE_VIDEO)`        |
| Call category    | `.setCallCategory(CometChatConstants.CALL_CATEGORY_CALL)` |

<Warning>
  Pass the builder object, not the result of `.build()`. The component calls `.build()` internally. Default page size is 30 with infinite scroll.
</Warning>

***

## Actions and Events

### Callback Methods

#### `onItemClick`

Fires when a call log row is tapped. Primary navigation hook.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setOnItemClick { callLog ->
        // Navigate to call detail
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        onItemClick = { callLog ->
            // Navigate to call detail
        }
    )
    ```
  </Tab>
</Tabs>

> Replaces the default item-click behavior. Your custom lambda executes instead of the built-in navigation.

#### `onItemLongClick`

Fires when a call log row is long-pressed.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setOnItemLongClick { callLog ->
        // Show context menu
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        onItemLongClick = { callLog ->
            // Show context menu
        }
    )
    ```
  </Tab>
</Tabs>

#### `onBackPress`

Fires when the user presses the back button in the toolbar.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setOnBackPress {
        finish()
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        onBackPress = { /* navigate back */ }
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setOnError { exception ->
        Log.e("CallLogs", "Error: ${exception.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        onError = { exception ->
            Log.e("CallLogs", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched and loaded.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setOnLoad { callLogList ->
        Log.d("CallLogs", "Loaded ${callLogList.size}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        onLoad = { callLogList ->
            Log.d("CallLogs", "Loaded ${callLogList.size}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setOnEmpty {
        Log.d("CallLogs", "No call logs")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        onEmpty = { /* no call logs */ }
    )
    ```
  </Tab>
</Tabs>

***

## Functionality

| Method (Kotlin XML)                   | Compose Parameter        | Description            |
| ------------------------------------- | ------------------------ | ---------------------- |
| `setBackIconVisibility(View.VISIBLE)` | `hideBackIcon = false`   | Toggle back button     |
| `setToolbarVisibility(View.GONE)`     | `hideToolbar = true`     | Toggle toolbar         |
| `setSeparatorVisibility(View.GONE)`   | `hideSeparator = true`   | Toggle list separators |
| `setTitle("Call History")`            | `title = "Call History"` | Custom toolbar title   |

***

## Custom View Slots

### Leading View

Replace the avatar / left section.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setLeadingView(object : CallLogsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return ImageView(context).apply {
                layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp)
            }
        }

        override fun bindView(
            context: Context, createdView: View, callLog: CallLog,
            holder: RecyclerView.ViewHolder, callLogList: List<CallLog>, position: Int
        ) {
            val imageView = createdView as ImageView
            // Load caller avatar
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        leadingView = { callLog ->
            CometChatAvatar(
                imageUrl = callLog.initiator?.avatar,
                name = callLog.initiator?.name
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Title View

Replace the name / title text.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setTitleView(object : CallLogsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return TextView(context)
        }

        override fun bindView(
            context: Context, createdView: View, callLog: CallLog,
            holder: RecyclerView.ViewHolder, callLogList: List<CallLog>, position: Int
        ) {
            (createdView as TextView).text = callLog.initiator?.name ?: ""
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        titleView = { callLog ->
            Text(
                text = callLog.initiator?.name ?: "",
                style = CometChatTheme.typography.heading4Medium
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

Replace the subtitle text below the caller's name.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setSubtitleView(object : CallLogsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return TextView(context).apply { maxLines = 1; ellipsize = TextUtils.TruncateAt.END }
        }

        override fun bindView(
            context: Context, createdView: View, callLog: CallLog,
            holder: RecyclerView.ViewHolder, callLogList: List<CallLog>, position: Int
        ) {
            (createdView as TextView).text = callLog.status ?: "Unknown"
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        subtitleView = { callLog ->
            Text(
                text = callLog.status ?: "Unknown",
                maxLines = 1,
                overflow = TextOverflow.Ellipsis
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Trailing View

Replace the right section of each call log item.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setTrailingView(object : CallLogsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return TextView(context)
        }

        override fun bindView(
            context: Context, createdView: View, callLog: CallLog,
            holder: RecyclerView.ViewHolder, callLogList: List<CallLog>, position: Int
        ) {
            (createdView as TextView).text = SimpleDateFormat("h:mm a", Locale.getDefault())
                .format(Date(callLog.initiatedAt * 1000))
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        trailingView = { callLog ->
            Text(
                text = SimpleDateFormat("h:mm a", Locale.getDefault())
                    .format(Date(callLog.initiatedAt * 1000))
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Item View

Replace the entire list item row.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setItemView(object : CallLogsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return LayoutInflater.from(context).inflate(R.layout.custom_call_log_item, null)
        }

        override fun bindView(
            context: Context, createdView: View, callLog: CallLog,
            holder: RecyclerView.ViewHolder, callLogList: List<CallLog>, position: Int
        ) {
            val avatar = createdView.findViewById<CometChatAvatar>(R.id.custom_avatar)
            val title = createdView.findViewById<TextView>(R.id.tvName)
            title.text = callLog.initiator?.name
            avatar.setAvatar(callLog.initiator?.name, callLog.initiator?.avatar)
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        itemView = { callLog ->
            Row(
                modifier = Modifier.fillMaxWidth().padding(12.dp),
                verticalAlignment = Alignment.CenterVertically
            ) {
                CometChatAvatar(imageUrl = callLog.initiator?.avatar, name = callLog.initiator?.name)
                Spacer(Modifier.width(12.dp))
                Column(modifier = Modifier.weight(1f)) {
                    Text(callLog.initiator?.name ?: "", style = CometChatTheme.typography.heading4Medium)
                    Text(callLog.status ?: "", style = CometChatTheme.typography.body3Regular)
                }
            }
        }
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setEmptyView(R.layout.custom_empty_view)
    callLogs.setErrorView(R.layout.custom_error_view)
    callLogs.setLoadingView(R.layout.custom_loading_view)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        emptyView = { Text("No call logs") },
        errorView = { onRetry -> Button(onClick = onRetry) { Text("Retry") } },
        loadingView = { CircularProgressIndicator() }
    )
    ```
  </Tab>
</Tabs>

### Overflow Menu

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setOverflowMenu(ImageButton(context).apply {
        setImageResource(R.drawable.ic_filter)
        setOnClickListener { /* show filter */ }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        overflowMenu = {
            IconButton(onClick = { /* show filter */ }) {
                Icon(painterResource(R.drawable.ic_filter), "Filter")
            }
        }
    )
    ```
  </Tab>
</Tabs>

***

## Menu Options

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Replace all options
    callLogs.setOptions { context, callLog ->
        listOf(
            CometChatPopupMenu.MenuItem(id = "delete", name = "Delete", onClick = { /* ... */ }),
            CometChatPopupMenu.MenuItem(id = "callback", name = "Call Back", onClick = { /* ... */ })
        )
    }

    // Append to defaults
    callLogs.setAddOptions { context, callLog ->
        listOf(
            CometChatPopupMenu.MenuItem(id = "info", name = "Info", onClick = { /* ... */ })
        )
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        options = { context, callLog ->
            listOf(
                MenuItem(id = "delete", name = "Delete", onClick = { /* ... */ }),
                MenuItem(id = "callback", name = "Call Back", onClick = { /* ... */ })
            )
        },
        addOptions = { context, callLog ->
            listOf(MenuItem(id = "info", name = "Info", onClick = { /* ... */ }))
        }
    )
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Minimal list — hide all chrome

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setToolbarVisibility(View.GONE)
    callLogs.setSeparatorVisibility(View.GONE)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        hideToolbar = true,
        hideSeparator = true
    )
    ```
  </Tab>
</Tabs>

### Audio calls only

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setCallLogRequestBuilder(
        CallLogRequest.CallLogRequestBuilder()
            .setCallType(CometChatConstants.CALL_TYPE_AUDIO)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        callLogRequestBuilder = CallLogRequest.CallLogRequestBuilder()
            .setCallType(CometChatConstants.CALL_TYPE_AUDIO)
    )
    ```
  </Tab>
</Tabs>

### Video calls only

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setCallLogRequestBuilder(
        CallLogRequest.CallLogRequestBuilder()
            .setCallType(CometChatConstants.CALL_TYPE_VIDEO)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        callLogRequestBuilder = CallLogRequest.CallLogRequestBuilder()
            .setCallType(CometChatConstants.CALL_TYPE_VIDEO)
    )
    ```
  </Tab>
</Tabs>

***

## Advanced Methods

### ViewModel Access

```kotlin lines theme={null}
val factory = CometChatCallLogsViewModelFactory()
val viewModel = ViewModelProvider(this, factory)
    .get(CometChatCallLogsViewModel::class.java)
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    callLogs.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        callLogsViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

See [ViewModel & Data](/docs/ui-kit/android/customization-viewmodel-data) for ListOperations, state observation, and custom repositories.

***

## Style

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Define a custom style in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="CustomCallLogsAvatarStyle" parent="CometChatAvatarStyle">
        <item name="cometchatAvatarStrokeRadius">8dp</item>
        <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
    </style>

    <style name="CustomCallLogsStyle" parent="CometChatCallLogsStyle">
        <item name="cometchatCallLogsAvatarStyle">@style/CustomCallLogsAvatarStyle</item>
        <item name="cometchatCallLogsSeparatorColor">#F76808</item>
        <item name="cometchatCallLogsTitleTextColor">#F76808</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatCallLogsStyle">@style/CustomCallLogsStyle</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        style = CometChatCallLogsStyle.default().copy(
            backgroundColor = Color(0xFFF5F5F5),
            titleTextColor = Color(0xFF141414),
            itemStyle = CometChatCallLogsItemStyle.default().copy(
                backgroundColor = Color.White,
                titleTextColor = Color(0xFF141414),
                subtitleTextColor = Color(0xFF727272),
                avatarStyle = CometChatAvatarStyle.default().copy(cornerRadius = 12.dp)
            )
        )
    )
    ```
  </Tab>
</Tabs>

### Style Properties

| Property                      | Description            |
| ----------------------------- | ---------------------- |
| `backgroundColor`             | List background color  |
| `titleTextColor`              | Toolbar title color    |
| `itemStyle.backgroundColor`   | Row background         |
| `itemStyle.titleTextColor`    | Caller name color      |
| `itemStyle.subtitleTextColor` | Call status text color |
| `itemStyle.separatorColor`    | Row separator color    |
| `itemStyle.avatarStyle`       | Avatar appearance      |

See [Component Styling](/docs/ui-kit/android/component-styling) for the full reference.

***

## Next Steps

<CardGroup>
  <Card title="Call Features" icon="phone" href="/ui-kit/android/call-features">
    Voice and video calling overview
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/android/conversations">
    Browse recent conversations
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/android/component-styling">
    Detailed styling reference with screenshots
  </Card>

  <Card title="ViewModel & Data" icon="database" href="/ui-kit/android/customization-viewmodel-data">
    Custom ViewModels, repositories, and ListOperations
  </Card>
</CardGroup>


# Calling Integration
Source: https://www.cometchat.com/docs/ui-kit/android/calling-integration

Add voice and video calling to your Android UI Kit application using chatuikit-kotlin or chatuikit-jetpack.

## Overview

This guide walks you through adding voice and video calling capabilities to your Android application using the CometChat UI Kit.

<Info>
  Make sure you've completed the [Getting Started](/docs/ui-kit/android/getting-started) guide before proceeding.
</Info>

## Add the Calls SDK

Add the CometChat Calls SDK dependency alongside your chosen UI Kit module:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin build.gradle.kts theme={null}
    dependencies {
        implementation("com.cometchat:chatuikit-kotlin-android:6.0.3")
        implementation("com.cometchat:calls-sdk-android:5.0.1")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin build.gradle.kts theme={null}
    dependencies {
        implementation("com.cometchat:chatuikit-compose-android:6.0.3")
        implementation("com.cometchat:calls-sdk-android:5.0.1")
    }
    ```
  </Tab>
</Tabs>

After adding this dependency, the Android UI Kit will automatically detect it and activate the calling features. You will see the `CometChatCallButtons` component rendered in the [MessageHeader](/docs/ui-kit/android/message-header) component.

<Frame>
  <img />
</Frame>

## Set Up Call Listener

To receive incoming calls globally in your app, add a `CallListener` before initializing the CometChat UI Kit. We recommend creating a custom Application class:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    class BaseApplication : Application() {
        companion object {
            private val LISTENER_ID = "${BaseApplication::class.java.simpleName}${System.currentTimeMillis()}"
        }

        override fun onCreate() {
            super.onCreate()
            CometChat.addCallListener(LISTENER_ID, object : CometChat.CallListener {
                override fun onIncomingCallReceived(call: Call) {
                    // Get the current activity context
                    val currentActivity = getCurrentActivity() // Implement this method

                    currentActivity?.let {
                        val incomingCallView = CometChatIncomingCall(it)
                        incomingCallView.call = call
                        incomingCallView.fitsSystemWindows = true
                        incomingCallView.onError = OnError { exception ->
                            // Handle errors
                        }

                        // Display the component (e.g., as dialog or full-screen overlay)
                    }
                }

                override fun onOutgoingCallAccepted(call: Call) {
                    // Handle accepted outgoing call
                }

                override fun onOutgoingCallRejected(call: Call) {
                    // Handle rejected outgoing call
                }

                override fun onIncomingCallCancelled(call: Call) {
                    // Handle cancelled incoming call
                }
            })
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    class BaseApplication : Application() {
        companion object {
            private val LISTENER_ID = "${BaseApplication::class.java.simpleName}${System.currentTimeMillis()}"
        }

        override fun onCreate() {
            super.onCreate()
            CometChat.addCallListener(LISTENER_ID, object : CometChat.CallListener {
                override fun onIncomingCallReceived(call: Call) {
                    CometChatCallActivity.launchIncomingCallScreen(this@BaseApplication, call, null)
                    // Pass null or IncomingCallConfiguration if need to configure CometChatIncomingCall component
                }

                override fun onOutgoingCallAccepted(call: Call) {
                    // Handle accepted outgoing call
                }

                override fun onOutgoingCallRejected(call: Call) {
                    // Handle rejected outgoing call
                }

                override fun onIncomingCallCancelled(call: Call) {
                    // Handle cancelled incoming call
                }
            })
        }
    }
    ```
  </Tab>
</Tabs>


# Campaigns
Source: https://www.cometchat.com/docs/ui-kit/android/campaigns

Deliver targeted, rich notifications to users via an in-app notification feed powered by the CometChat Cards renderer.

CometChat Campaigns enables you to send rich, interactive notifications to users through an in-app notification feed. Each notification is rendered as a native card using the **CometChat Cards** library — supporting images, text, buttons, layouts, and interactive actions.

<Note>
  Before proceeding, ensure you have completed the [UI Kit integration](/docs/ui-kit/android/getting-started) and the [Dashboard Setup](/docs/campaigns#setup-flow) for Campaigns.
</Note>

<Frame>
  <img />
</Frame>

***

## Overview

Campaigns delivers notifications as **Card Schema JSON** — a structured format that defines the visual layout of each notification card. The system consists of three layers:

1. **CometChat Chat SDK** — Fetches feed items, manages read/delivered state, provides real-time listeners, handles push notification tracking
2. **CometChat Cards Library** — Renders Card Schema JSON into native Android views (Jetpack Compose and XML Views)
3. **CometChat UI Kit** — Provides the ready-to-use `CometChatNotificationFeed` component that wires everything together

### Architecture Flow

```
Dashboard / API → Campaign Created → Push + WebSocket Delivery
                                            ↓
                                     SDK: NotificationFeedRequest.fetchNext()
                                            ↓
                                     NotificationFeedItem.getContent() → Card Schema JSON
                                            ↓
                                     Cards Library: CometChatCardView / CometChatCardComposable
                                            ↓
                                     Native Rendered Card (images, text, buttons, layouts)
                                            ↓
                                     User taps button → ActionCallback → Your code handles it
```

***

## How Cards Work

Each `NotificationFeedItem` from the SDK contains a `content` field — a `JSONObject` holding the Card Schema JSON. This JSON is passed directly to the CometChat Cards renderer which produces a native view.

The Cards library is a **pure renderer**:

* **Input**: Card Schema JSON string + theme mode + optional action callback
* **Output**: Native Android view hierarchy

It does not execute actions, manage message state, or call any SDK methods. When users tap interactive elements (buttons, links), the library emits the action to your callback. You decide what happens — open a URL, navigate to a chat, make an API call, etc.

### Card Schema JSON Example

```json theme={null}
{
  "version": "1.0",
  "body": [
    {
      "type": "column",
      "backgroundColor": {
        "light": "transparent",
        "dark": "transparent"
      },
      "gap": 5,
      "items": [
        {
          "type": "text",
          "content": "📢 Announcement",
          "variant": "heading2",
          "id": "txt_99323141-2459-4e33-88d3-ca39c5fd2f50"
        },
        {
          "type": "text",
          "content": "Your announcement message here.",
          "variant": "body",
          "id": "txt_61a417bc-5e4a-4ba2-bfe7-b7bc64dbaf35"
        },
        {
          "type": "divider",
          "id": "div_80f5c7fb-fd10-41d1-8c2f-51498f0f62d0"
        },
        {
          "type": "button",
          "label": "Learn More",
          "backgroundColor": {
            "light": "transparent",
            "dark": "transparent"
          },
          "textColor": {
            "light": "#6C5CE7",
            "dark": "#6C5CE7"
          },
          "size": 40,
          "fontSize": 13,
          "borderRadius": 6,
          "padding": {
            "top": 0,
            "right": 16,
            "bottom": 0,
            "left": 16
          },
          "action": {
            "type": "openUrl",
            "url": ""
          },
          "id": "btn_9b87a3f1-b0c6-45b9-a4c2-e22ea590f17f"
        }
      ],
      "id": "col_98fed9bd-1a95-4cee-aa81-84a9016e41f2"
    }
  ],
  "fallbackText": "",
  "style": {
    "background": {
      "light": "#E8E8E8",
      "dark": "#E8E8E8"
    },
    "borderRadius": 16,
    "borderColor": {
      "light": "#DFE6E9",
      "dark": "#DFE6E9"
    },
    "padding": 12
  }
}
```

The schema supports **20 element types** (text, image, icon, avatar, badge, divider, spacer, chip, progressBar, codeBlock, markdown, row, column, grid, accordion, tabs, button, iconButton, link, table) and **9 action types** (openUrl, chatWithUser, chatWithGroup, sendMessage, copyToClipboard, downloadFile, initiateCall, apiCall, customCallback).

Here's how the above JSON renders as a native card:

<Frame>
  <img />
</Frame>

***

## How Cards Work in the UI Kit

The `CometChatNotificationFeed` component uses the **CometChat Cards** library internally to render each notification. Here's what happens under the hood:

1. The component fetches `NotificationFeedItem` objects from the SDK
2. For each item, it extracts the `content` field (Card Schema JSON)
3. It passes the JSON to `CometChatCardComposable` (Compose) or `CometChatCardView` (XML) from the Cards library
4. The Cards renderer produces native UI — text, images, buttons, layouts — directly from the JSON
5. When users tap buttons/links inside a card, the action is emitted back to the component which handles navigation (open URL, navigate to chat, etc.)

You don't need to interact with the Cards library directly when using `CometChatNotificationFeed` — it's all wired up. But if you want to render cards outside the feed (e.g., a standalone card in a dialog), you can use the Cards library directly. See the [SDK Campaigns documentation](/docs/sdk/android/v5/campaigns#rendering-cards) for standalone usage.

***

## Handling Push Notifications for Campaigns

When a campaign push notification arrives via FCM, you should:

1. **Report delivery** — Call `CometChat.markPushNotificationDelivered()` in your `FirebaseMessagingService`
2. **Report click** — Call `CometChat.markPushNotificationClicked()` when the user taps the notification
3. **Deep link** — Use the announcement ID from the push payload to fetch the full item via `CometChat.getNotificationFeedItem(id)` and display it

```kotlin theme={null}
// In FirebaseMessagingService.onMessageReceived()
val pushNotification = PushNotification.fromJson(data)
CometChat.markPushNotificationDelivered(pushNotification, ...)

// When user taps the notification
CometChat.markPushNotificationClicked(pushNotification, ...)

// Navigate to feed or show specific item
CometChat.getNotificationFeedItem(pushNotification.id, ...)
```

See the [SDK Campaigns documentation](/docs/sdk/android/v5/campaigns) for the complete push notification tracking API.

***

## Sending Campaigns

Before integrating the frontend, you need to set up channels, categories, templates, and campaigns in the CometChat Dashboard. Follow the [Dashboard Setup Guide](/docs/campaigns#setup-flow) for step-by-step instructions with screenshots.

***

## Using the UI Kit Component

The easiest way to add a notification feed to your app is the `CometChatNotificationFeed` component. It handles fetching, rendering, pagination, filtering, real-time updates, and engagement reporting out of the box.

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    @Composable
    fun NotificationsScreen() {
        CometChatNotificationFeed(
            modifier = Modifier.fillMaxSize(),
            onItemClick = { item ->
                // Handle item tap
            },
            onBackPress = { /* navigate back */ }
        )
    }
    ```
  </Tab>

  <Tab title="Kotlin (XML Views)">
    ```xml theme={null}
    <com.cometchat.uikit.kotlin.presentation.notificationfeed.ui.CometChatNotificationFeed
        android:id="@+id/notificationFeed"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    ```kotlin theme={null}
    val feed = findViewById<CometChatNotificationFeed>(R.id.notificationFeed)
    feed.init(this) // Pass ViewModelStoreOwner
    feed.onItemClick = { item -> /* handle tap */ }
    ```
  </Tab>
</Tabs>

See the full [CometChatNotificationFeed component documentation](/docs/ui-kit/android/notification-feed) for all configuration options, styling, and customization.

***

## Next Steps

<CardGroup>
  <Card title="SDK Campaigns API" icon="code" href="/sdk/android/v5/campaigns">
    Full API reference for feed items, categories, engagement, and push tracking
  </Card>

  <Card title="CometChatNotificationFeed" icon="bell" href="/ui-kit/android/notification-feed">
    Ready-to-use component with filtering, real-time updates, and styling
  </Card>
</CardGroup>


# Color Resources
Source: https://www.cometchat.com/docs/ui-kit/android/color-resources

Review and override the default UI Kit color palette for consistent light and dark mode styling.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                                                              |
  | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Kotlin XML Views | Colors defined in `res/values/color.xml` (light) and `res/values-night/color.xml` (dark), overridable via theme attributes or `CometChatTheme.set*()`              |
  | Jetpack Compose  | Colors provided via `lightColorScheme()` and `darkColorScheme()` factory functions, customizable via `.copy()`                                                     |
  | Key tokens       | `primary`, `backgroundColor1–4`, `textColorPrimary/Secondary/Tertiary`, `strokeColorDefault/Light/Dark`, `successColor`, `errorColor`, `warningColor`, `infoColor` |
  | Related          | [Theme Introduction](/docs/ui-kit/android/theme-introduction) · [Component Styling](/docs/ui-kit/android/component-styling)                                                  |
</Accordion>

The UI Kit ships with a complete color palette for light and dark modes. This page documents the default values and how to override them.

***

## Color Categories

The palette is organized into these groups:

| Category   | Tokens                                                                                                                     | Purpose                                                   |
| ---------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Primary    | `primary`                                                                                                                  | Brand color for buttons, highlights, interactive elements |
| Neutral    | `neutral50` – `neutral900`                                                                                                 | Grayscale ramp for backgrounds, text, borders             |
| Alert      | `success`, `error`, `warning`, `info`, `messageRead`                                                                       | Status indicators                                         |
| Background | `backgroundColor1` – `backgroundColor4`                                                                                    | Surface/panel backgrounds (derived from neutrals)         |
| Stroke     | `strokeColorDefault`, `strokeColorLight`, `strokeColorDark`, `strokeColorHighlight`                                        | Borders and dividers                                      |
| Text       | `textColorPrimary`, `textColorSecondary`, `textColorTertiary`, `textColorDisabled`, `textColorWhite`, `textColorHighlight` | Typography colors                                         |
| Icon       | `iconTintPrimary`, `iconTintSecondary`, `iconTintTertiary`, `iconTintWhite`, `iconTintHighlight`                           | Icon tints                                                |
| Button     | `primaryButtonBackground`, `primaryButtonText`, `secondaryButtonBackground`, `secondaryButtonText`                         | Button colors                                             |

***

## Default Light Mode Palette

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Defined in `chatuikit-kotlin/src/main/res/values/color.xml`:

    ```xml color.xml lines theme={null}
    <!-- Primary -->
    <color name="cometchat_color_primary">#6852D6</color>

    <!-- Neutral -->
    <color name="cometchat_color_neutral_50">#FFFFFF</color>
    <color name="cometchat_color_neutral_100">#FAFAFA</color>
    <color name="cometchat_color_neutral_200">#F5F5F5</color>
    <color name="cometchat_color_neutral_300">#E8E8E8</color>
    <color name="cometchat_color_neutral_400">#DCDCDC</color>
    <color name="cometchat_color_neutral_500">#A1A1A1</color>
    <color name="cometchat_color_neutral_600">#727272</color>
    <color name="cometchat_color_neutral_700">#5B5B5B</color>
    <color name="cometchat_color_neutral_800">#434343</color>
    <color name="cometchat_color_neutral_900">#141414</color>

    <!-- Alert -->
    <color name="cometchat_color_info">#0B7BEA</color>
    <color name="cometchat_color_success">#09C26F</color>
    <color name="cometchat_color_warning">#FFAB00</color>
    <color name="cometchat_color_error">#F44649</color>
    <color name="cometchat_color_message_read">#56E8A7</color>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Provided by `lightColorScheme()` in `CometChatColorScheme.kt`:

    ```kotlin lines theme={null}
    import com.cometchat.uikit.compose.theme.lightColorScheme

    // Default light color scheme
    val colors = lightColorScheme()

    // Key defaults:
    // primary = Color(0xFF6852D6)
    // neutralColor50 = Color(0xFFFFFFFF)
    // neutralColor900 = Color(0xFF141414)
    // successColor = Color(0xFF09C26F)
    // errorColor = Color(0xFFF44649)
    // warningColor = Color(0xFFFFAB00)
    // infoColor = Color(0xFF0B7BEA)
    ```
  </Tab>
</Tabs>

***

## Default Dark Mode Palette

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Defined in `chatuikit-kotlin/src/main/res/values-night/color.xml`. Note how neutral values are inverted:

    ```xml values-night/color.xml lines theme={null}
    <!-- Primary -->
    <color name="cometchat_color_primary">#6852D6</color>

    <!-- Neutral (inverted for dark mode) -->
    <color name="cometchat_color_neutral_50">#141414</color>
    <color name="cometchat_color_neutral_100">#1A1A1A</color>
    <color name="cometchat_color_neutral_200">#272727</color>
    <color name="cometchat_color_neutral_300">#383838</color>
    <color name="cometchat_color_neutral_400">#4C4C4C</color>
    <color name="cometchat_color_neutral_500">#858585</color>
    <color name="cometchat_color_neutral_600">#989898</color>
    <color name="cometchat_color_neutral_700">#A8A8A8</color>
    <color name="cometchat_color_neutral_800">#C8C8C8</color>
    <color name="cometchat_color_neutral_900">#FFFFFF</color>

    <!-- Alert -->
    <color name="cometchat_color_info">#0D66BF</color>
    <color name="cometchat_color_success">#0B9F5D</color>
    <color name="cometchat_color_warning">#D08D04</color>
    <color name="cometchat_color_error">#C73C3E</color>
    <color name="cometchat_color_message_read">#56E8A7</color>
    ```

    Android automatically uses `values-night` resources when the system is in dark mode.
  </Tab>

  <Tab title="Jetpack Compose">
    Provided by `darkColorScheme()`:

    ```kotlin lines theme={null}
    import com.cometchat.uikit.compose.theme.darkColorScheme

    // Default dark color scheme
    val colors = darkColorScheme()

    // Key defaults (neutrals inverted):
    // primary = Color(0xFF6852D6)
    // neutralColor50 = Color(0xFF141414)
    // neutralColor900 = Color(0xFFFFFFFF)
    // successColor = Color(0xFF0B9F5D)
    // errorColor = Color(0xFFC73C3E)
    ```
  </Tab>
</Tabs>

***

## Override Colors

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Override via XML theme attributes in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatPrimaryColor">#F76808</item>
        <item name="cometchatBackgroundColor1">#FFFFFF</item>
        <item name="cometchatTextColorPrimary">#000000</item>
        <item name="cometchatStrokeColorDefault">#E0E0E0</item>
    </style>
    ```

    Or programmatically via `CometChatTheme`:

    ```kotlin lines theme={null}
    CometChatTheme.setPrimaryColor(Color.parseColor("#F76808"))
    CometChatTheme.setBackgroundColor1(Color.parseColor("#FFFFFF"))
    CometChatTheme.setTextColorPrimary(Color.parseColor("#000000"))
    CometChatTheme.setStrokeColorDefault(Color.parseColor("#E0E0E0"))
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Customize via `.copy()` on the factory functions:

    ```kotlin lines theme={null}
    val customColors = lightColorScheme().copy(
        primary = Color(0xFFF76808),
        backgroundColor1 = Color(0xFFFFFFFF),
        textColorPrimary = Color(0xFF000000),
        strokeColorDefault = Color(0xFFE0E0E0)
    )

    CometChatTheme(colorScheme = customColors) {
        // Your content
    }
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

***

## Derived Colors

Background, stroke, text, and icon colors are derived from the neutral scale by default:

| Token                | Light Mode Default     | Dark Mode Default      |
| -------------------- | ---------------------- | ---------------------- |
| `backgroundColor1`   | `neutral50` (#FFFFFF)  | `neutral50` (#141414)  |
| `backgroundColor2`   | `neutral100` (#FAFAFA) | `neutral100` (#1A1A1A) |
| `textColorPrimary`   | `neutral900` (#141414) | `neutral900` (#FFFFFF) |
| `textColorSecondary` | `neutral600` (#727272) | `neutral600` (#989898) |
| `strokeColorDefault` | `neutral200` (#F5F5F5) | `neutral200` (#272727) |
| `strokeColorLight`   | `neutral300` (#E8E8E8) | `neutral300` (#383838) |
| `iconTintPrimary`    | `neutral900` (#141414) | `neutral900` (#FFFFFF) |
| `iconTintHighlight`  | `primary` (#6852D6)    | `primary` (#6852D6)    |

This means overriding a neutral color automatically updates all tokens that reference it.


# Component Styling
Source: https://www.cometchat.com/docs/ui-kit/android/component-styling

Style CometChat UI Kit components using XML theme attributes or Compose style data classes.

<Accordion title="AI Integration Quick Reference">
  | Field             | Value                                                                                                                                                                            |
  | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Kotlin XML Views  | Override XML styles in `themes.xml` extending component parent styles (e.g., `CometChatConversationsStyle`), assign via theme attributes                                         |
  | Jetpack Compose   | Pass style data classes as parameters (e.g., `CometChatConversationsStyle`, `CometChatMessageListStyle`) with `.default()` and `.copy()`                                         |
  | Pattern (XML)     | Create custom style → extend parent → assign to `AppTheme` via theme attribute                                                                                                   |
  | Pattern (Compose) | Call `ComponentStyle.default().copy(property = value)` → pass as `style` parameter                                                                                               |
  | Related           | [Theme Introduction](/docs/ui-kit/android/theme-introduction) · [Color Resources](/docs/ui-kit/android/color-resources) · [Message Bubble Styling](/docs/ui-kit/android/message-bubble-styling) |
</Accordion>

This page shows how to style CometChat UI Kit components in Android. It is written for Android developers customizing UI Kit v6.

## When to use this

* You want UI Kit screens (lists, headers, and message UI) to match your brand colors and typography.
* You need to customize calling and AI UI components without rebuilding UI from scratch.
* You prefer centralized styling through `res/values/themes.xml` (XML Views) or style data classes (Compose).
* You want consistent iconography by supplying your own vector drawables.
* You need a repeatable pattern that can be applied across components.

## Prerequisites

* CometChat Android UI Kit v6 installed in your app.
* Your app theme extends `CometChatTheme.DayNight` (for XML Views).
* You can edit `res/values/themes.xml` in your Android module.
* You can add drawable resources to `res/drawable/` when needed.
* You rebuild or sync Gradle after updating styles.

## Styling Pattern

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Components read styles from XML theme attributes. The pattern is:

    1. Open `res/values/themes.xml`.
    2. Create a custom style that extends the component's parent style (for example, `CometChatConversationsStyle`).
    3. Assign your custom style to `AppTheme` using the component's theme attribute (for example, `cometchatConversationsStyle`).
    4. Sync Gradle and rebuild the app.
    5. Navigate to the screen that uses the component and confirm the visual change.

    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomConversationsStyle" parent="CometChatConversationsStyle">
            <item name="cometchatConversationsAvatarStyle">@style/CustomAvatarStyle</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatConversationsStyle">@style/CustomConversationsStyle</item>
        </style>
    </resources>
    ```

    You can also set fonts globally:

    ```xml themes.xml lines theme={null}
    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatFontBold">@font/your_font_bold</item>
        <item name="cometchatFontMedium">@font/your_font_medium</item>
        <item name="cometchatFontRegular">@font/your_font_regular</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Components accept a `style` parameter — a data class with `.default()` factory and `.copy()` for overrides:

    ```kotlin lines theme={null}
    CometChatConversations(
        style = CometChatConversationsStyle.default().copy(
            backgroundColor = Color(0xFFFFF9F5),
            titleTextColor = Color(0xFFF76808)
        )
    )
    ```

    Nested styles (e.g., avatar inside conversations) are overridden the same way:

    ```kotlin lines theme={null}
    CometChatConversations(
        style = CometChatConversationsStyle.default().copy(
            avatarStyle = CometChatAvatarStyle.default().copy(
                backgroundColor = Color(0xFFFBAA75),
                cornerRadius = 8.dp
            )
        )
    )
    ```
  </Tab>
</Tabs>

## Core concepts

* `AppTheme` is the single place where UI Kit style hooks are wired (XML Views).
* Each UI Kit component has a parent style (for example, `CometChatMessageListStyle`) and a theme attribute (for example, `cometchatMessageListStyle`).
* Custom styles must extend the correct parent style to inherit default behavior.
* Drawable overrides (for example, custom icons) live in `res/drawable/` and are referenced from styles.
* Fonts can be set once at the theme level and reused across components.

***

## Implementation

Use the following sections to style each component. Each section lists what changes, where to change it, the exact code to paste, and how to verify the result.

### Chat Lists & Messaging

#### Conversations

The `CometChatConversations` component renders the recent chats list.

<Frame>
  <img />
</Frame>

What you're changing: avatar and badge styling in the conversation list.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatConversations`
* **Default behavior**: UI Kit default avatar and badge styles.
* **Override**: set `cometchatConversationsStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomAvatarStyle" parent="CometChatAvatarStyle">
            <item name="cometchatAvatarStrokeRadius">8dp</item>
            <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
        </style>

        <style name="CustomBadgeCountStyle" parent="CometChatBadgeStyle">
            <item name="cometchatBadgeBackgroundColor">#F76808</item>
            <item name="cometchatBadgeTextColor">#FFFFFF</item>
        </style>

        <style name="CustomConversationsStyle" parent="CometChatConversationsStyle">
            <item name="cometchatConversationsAvatarStyle">@style/CustomAvatarStyle</item>
            <item name="cometchatConversationsBadgeStyle">@style/CustomBadgeCountStyle</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatConversationsStyle">@style/CustomConversationsStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        style = CometChatConversationsStyle.default().copy(
            avatarStyle = CometChatAvatarStyle.default().copy(
                backgroundColor = Color(0xFFFBAA75),
                cornerRadius = 8.dp
            ),
            badgeStyle = CometChatBadgeStyle.default().copy(
                backgroundColor = Color(0xFFF76808),
                textColor = Color.White
            )
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: applies custom avatar and badge styles to conversation list items.
* **Verify**: the Conversations list shows updated avatar backgrounds and badge colors.

Attribute references:

* [Conversations attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_conversations.xml)
* [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml)
* [Badge attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_badge.xml)

#### Users

The `CometChatUsers` component renders a list of users for selection or navigation.

<Frame>
  <img />
</Frame>

What you're changing: user list avatar and separator styling.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatUsers`
* **Default behavior**: UI Kit default avatar and list styling.
* **Override**: set `cometchatUsersStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomAvatarStyle" parent="CometChatAvatarStyle">
            <item name="cometchatAvatarStrokeRadius">8dp</item>
            <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
        </style>

        <style name="CustomUsersStyle" parent="CometChatUsersStyle">
            <item name="cometchatUsersAvatarStyle">@style/CustomAvatarStyle</item>
            <item name="cometchatUsersSeparatorColor">#F76808</item>
            <item name="cometchatUsersTitleTextColor">#F76808</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatUsersStyle">@style/CustomUsersStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        style = CometChatUsersStyle.default().copy(
            separatorColor = Color(0xFFF76808),
            titleTextColor = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: applies avatar and separator color overrides to the user list.
* **Verify**: the Users list shows updated avatar backgrounds and separator color.

Attribute references:

* [Users attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_users.xml)
* [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml)

#### Groups

The `CometChatGroups` component renders group items and their summary data.

<Frame>
  <img />
</Frame>

What you're changing: group list avatar and typography colors.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatGroups`
* **Default behavior**: UI Kit default group item styling.
* **Override**: set `cometchatGroupsStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomAvatarStyle" parent="CometChatAvatarStyle">
            <item name="cometchatAvatarStrokeRadius">8dp</item>
            <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
        </style>

        <style name="CustomGroupsStyle" parent="CometChatGroupsStyle">
            <item name="cometchatGroupsAvatarStyle">@style/CustomAvatarStyle</item>
            <item name="cometchatGroupsSeparatorColor">#F76808</item>
            <item name="cometchatGroupsTitleTextColor">#F76808</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatGroupsStyle">@style/CustomGroupsStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        style = CometChatGroupsStyle.default().copy(
            separatorColor = Color(0xFFF76808),
            titleTextColor = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: styles group avatars and separators in the Groups list.
* **Verify**: the Groups list shows the updated avatar background and title color.

Attribute references:

* [Groups attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_groups.xml)
* [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml)

#### Message Header

The `CometChatMessageHeader` component renders the title, avatar, and action icons for a chat.

<Frame>
  <img />
</Frame>

What you're changing: title text color, avatar styling, and call button icons.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatMessageHeader`
* **Default behavior**: UI Kit default header typography and icons.
* **Override**: set `cometchatMessageHeaderStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomAvatarStyle" parent="CometChatAvatarStyle">
            <item name="cometchatAvatarStrokeRadius">8dp</item>
            <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
        </style>

        <style name="CustomCallButtonStyle" parent="CometChatCallButtonsStyle">
            <item name="cometchatCallButtonsVideoCallIconTint">#F76808</item>
            <item name="cometchatCallButtonsVoiceCallIconTint">#F76808</item>
        </style>

        <style name="CustomMessageHeaderStyle" parent="CometChatMessageHeaderStyle">
            <item name="cometchatMessageHeaderTitleTextColor">#F76808</item>
            <item name="cometchatMessageHeaderAvatarStyle">@style/CustomAvatarStyle</item>
            <item name="cometchatMessageHeaderCallButtonsStyle">@style/CustomCallButtonStyle</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatMessageHeaderStyle">@style/CustomMessageHeaderStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageHeader(
        style = CometChatMessageHeaderStyle.default().copy(
            titleTextColor = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: applies custom title color, avatar styling, and call button tints in the message header.
* **Verify**: open a conversation and check the header text and call button icons.

Attribute references:

* [Message Header attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_message_header.xml)
* [Call Buttons attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_call_buttons.xml)

#### Message List

The `CometChatMessageList` component renders conversation messages and their bubble styles.

<Frame>
  <img />
</Frame>

What you're changing: message list background and outgoing bubble styling.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatMessageList`
* **Default behavior**: UI Kit default message list background and bubble colors.
* **Override**: set `cometchatMessageListStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomOutgoingMessageBubbleStyle" parent="CometChatOutgoingMessageBubbleStyle">
            <item name="cometchatMessageBubbleBackgroundColor">#F76808</item>
        </style>

        <style name="CustomCometChatMessageListStyle" parent="CometChatMessageListStyle">
            <item name="cometchatMessageListBackgroundColor">#FEEDE1</item>
            <item name="cometchatMessageListOutgoingMessageBubbleStyle">@style/CustomOutgoingMessageBubbleStyle</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatMessageListStyle">@style/CustomCometChatMessageListStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        style = CometChatMessageListStyle.default().copy(
            backgroundColor = Color(0xFFFEEDE1),
            outgoingMessageBubbleStyle = CometChatOutgoingMessageBubbleStyle.default().copy(
                backgroundColor = Color(0xFFF76808)
            )
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: changes the message list background and outgoing bubble color.
* **Verify**: open a conversation and check outgoing message bubble colors.

Attribute references:

* [Message List attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_message_list.xml)
* [Message Bubble attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_message_bubble.xml)

#### Message Composer

The `CometChatMessageComposer` component renders the input box and action buttons.

<Frame>
  <img />
</Frame>

What you're changing: send button icon and composer icon tints.

* **Where to change it**: `res/drawable/active_send_button.xml` and `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatMessageComposer`
* **Default behavior**: UI Kit default composer icons and send button drawable.
* **Override**: set `cometchatMessageComposerStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml res/drawable/active_send_button.xml lines theme={null}
    <vector xmlns:android="http://schemas.android.com/apk/res/android"
        android:width="32dp"
        android:height="32dp"
        android:viewportWidth="32"
        android:viewportHeight="32">
        <path
            android:fillColor="#F76808"
            android:pathData="M16,0L16,0A16,16 0,0 1,32 16L32,16A16,16 0,0 1,16 32L16,32A16,16 0,0 1,0 16L0,16A16,16 0,0 1,16 0z" />
        <group>
            <clip-path android:pathData="M4,4h24v24h-24z" />
            <path
                android:fillColor="?attr/cometchatColorWhite"
                android:pathData="M10.767,22.723C10.465,22.843 10.178,22.818 9.907,22.646C9.636,22.474 9.5,22.223 9.5,21.894V17.673L16.423,16L9.5,14.327V10.106C9.5,9.777 9.636,9.526 9.907,9.354C10.178,9.182 10.465,9.157 10.767,9.277L24.723,15.161C25.095,15.328 25.281,15.608 25.281,16.002C25.281,16.395 25.095,16.674 24.723,16.838L10.767,22.723Z" />
        </group>
    </vector>
    ```

    ```xml res/values/themes.xml lines theme={null}
    <resources>
        <style name="CustomMessageComposerStyle" parent="CometChatMessageComposerStyle">
            <item name="cometchatMessageComposerAttachmentIconTint">#F76808</item>
            <item name="cometchatMessageComposerVoiceRecordingIconTint">#F76808</item>
            <item name="cometchatMessageComposerActiveStickerIconTint">#F76808</item>
            <item name="cometchatMessageComposerInactiveStickerIconTint">#F76808</item>
            <item name="cometchatMessageComposerAIIconTint">#F76808</item>
            <item name="cometchatMessageComposerActiveSendButtonDrawable">@drawable/active_send_button</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatMessageComposerStyle">@style/CustomMessageComposerStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageComposer(
        style = CometChatMessageComposerStyle.default().copy(
            attachmentIconTint = Color(0xFFF76808),
            voiceRecordingIconTint = Color(0xFFF76808),
            aiIconTint = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: applies custom icon tints and the active send button drawable to the composer.
* **Verify**: the composer shows the custom send button and tinted icons.

Attribute references:

* [Message Composer attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_message_composer.xml)

#### Group Members

The `CometChatGroupMembers` component lists users inside a group.

<Frame>
  <img />
</Frame>

What you're changing: group member list avatars, separators, and back icon tint.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatGroupMembers`
* **Default behavior**: UI Kit default list styling.
* **Override**: set `cometchatGroupMembersStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomAvatarStyle" parent="CometChatAvatarStyle">
            <item name="cometchatAvatarStrokeRadius">8dp</item>
            <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
        </style>

        <style name="CustomGroupMembersStyle" parent="CometChatGroupMembersStyle">
            <item name="cometchatGroupMembersAvatarStyle">@style/CustomAvatarStyle</item>
            <item name="cometchatGroupMembersSeparatorColor">#F76808</item>
            <item name="cometchatGroupMembersTitleTextColor">#F76808</item>
            <item name="cometchatGroupMembersBackIconTint">#F76808</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatGroupMembersStyle">@style/CustomGroupMembersStyle</item>
            <item name="cometchatPrimaryColor">#F76808</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        style = CometChatGroupMembersStyle.default().copy(
            separatorColor = Color(0xFFF76808),
            titleTextColor = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: applies custom avatar and separator styling to the group members list.
* **Verify**: the group members screen shows updated avatar and separator colors.

Attribute references:

* [Group Members attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_group_members.xml)
* [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml)

#### Thread Header

The `CometChatThreadHeader` component renders the parent message preview in threaded views.

<Frame>
  <img />
</Frame>

What you're changing: thread header bubble colors and reply count styling.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatThreadHeader`
* **Default behavior**: UI Kit default thread header styling.
* **Override**: set `cometchatThreadHeaderStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomOutgoingMessageBubbleStyle" parent="CometChatOutgoingMessageBubbleStyle">
            <item name="cometchatMessageBubbleBackgroundColor">#F76808</item>
        </style>

        <style name="CustomIncomingMessageBubbleStyle" parent="CometChatIncomingMessageBubbleStyle">
            <item name="cometchatMessageBubbleBackgroundColor">#F76808</item>
        </style>

        <style name="CustomThreadHeaderStyle" parent="CometChatThreadHeaderStyle">
            <item name="cometchatThreadHeaderOutgoingMessageBubbleStyle">@style/CustomOutgoingMessageBubbleStyle</item>
            <item name="cometchatThreadHeaderIncomingMessageBubbleStyle">@style/CustomIncomingMessageBubbleStyle</item>
            <item name="cometchatThreadHeaderBackgroundColor">#FEEDE1</item>
            <item name="cometchatThreadHeaderReplyCountTextColor">#F76808</item>
            <item name="cometchatThreadHeaderReplyCountBackgroundColor">#FEEDE1</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatThreadHeaderStyle">@style/CustomThreadHeaderStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatThreadHeader(
        style = CometChatThreadHeaderStyle.default().copy(
            backgroundColor = Color(0xFFFEEDE1),
            replyCountTextColor = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: customizes thread header bubble colors and reply count styling.
* **Verify**: open a thread and confirm the header background and reply count colors.

Attribute references:

* [Thread Header attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_thread_header.xml)
* [Message Bubble attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_message_bubble.xml)

#### Mentions

The `CometChatMentions` styling controls how user mentions appear inside messages.

<Frame>
  <img />
</Frame>

What you're changing: mention text and background styles for incoming and outgoing bubbles.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatMentions`
* **Default behavior**: UI Kit default mention styling.
* **Override**: set `cometchatMessageBubbleMentionsStyle` in both incoming and outgoing bubble styles.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomIncomingMessageBubbleMentionStyle" parent="CometChatIncomingBubbleMentionsStyle">
            <item name="cometchatMentionTextAppearance">?attr/cometchatTextAppearanceBodyRegular</item>
            <item name="cometchatMentionTextColor">#D6409F</item>
            <item name="cometchatMentionBackgroundColor">#D6409F</item>
            <item name="cometchatSelfMentionTextColor">#30A46C</item>
            <item name="cometchatSelfMentionTextAppearance">?attr/cometchatTextAppearanceBodyRegular</item>
            <item name="cometchatSelfMentionBackgroundColor">#30A46C</item>
        </style>

        <style name="CustomOutgoingMessageBubbleMentionStyle" parent="CometChatOutgoingBubbleMentionsStyle">
            <item name="cometchatMentionTextAppearance">?attr/cometchatTextAppearanceBodyRegular</item>
            <item name="cometchatMentionTextColor">#FFFFFF</item>
            <item name="cometchatMentionBackgroundColor">#F9F8FD</item>
            <item name="cometchatSelfMentionTextColor">#30A46C</item>
            <item name="cometchatSelfMentionTextAppearance">?attr/cometchatTextAppearanceBodyRegular</item>
            <item name="cometchatSelfMentionBackgroundColor">#30A46C</item>
        </style>

        <style name="CustomIncomingMessageBubbleStyle" parent="CometChatIncomingMessageBubbleStyle">
            <item name="cometchatMessageBubbleMentionsStyle">@style/CustomIncomingMessageBubbleMentionStyle</item>
        </style>

        <style name="CustomOutgoingMessageBubbleStyle" parent="CometChatOutgoingMessageBubbleStyle">
            <item name="cometchatMessageBubbleMentionsStyle">@style/CustomOutgoingMessageBubbleMentionStyle</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatIncomingMessageBubbleStyle">@style/CustomIncomingMessageBubbleStyle</item>
            <item name="cometchatOutgoingMessageBubbleStyle">@style/CustomOutgoingMessageBubbleStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        style = CometChatMessageListStyle.default().copy(
            incomingMessageBubbleStyle = CometChatIncomingMessageBubbleStyle.default().copy(
                mentionTextColor = Color(0xFFD6409F)
            ),
            outgoingMessageBubbleStyle = CometChatOutgoingMessageBubbleStyle.default().copy(
                mentionTextColor = Color.White
            )
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: customizes mention colors for incoming and outgoing message bubbles.
* **Verify**: send a mention in a chat and check the mention highlight colors.

Attribute references:

* [Mentions attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_mentions.xml)
* [Message Bubble attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_message_bubble.xml)

#### Search

The `CometChatSearch` component provides cross-conversation and message search UI.

<Frame>
  <img />
</Frame>

What you're changing: search background and typography styles.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatSearch`

* **Default behavior**: UI Kit default search colors and text appearance.

* **Override**: set `cometchatSearchStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="TextStyleTimesNewRoman">
        <item name="android:fontFamily">@font/times_new_roman_regular</item>
    </style>

    <style name="CustomSearchStyle" parent="CometChatSearchStyle">
        <item name="cometchatSearchBackgroundColor">#EDEAFA</item>
        <item name="cometchatSearchFilterChipTextAppearance">@style/TextStyleTimesNewRoman</item>
        <item name="cometchatSearchSectionHeaderTextAppearance">@style/TextStyleTimesNewRoman</item>
        <item name="cometchatSearchSectionHeaderBackgroundColor">#EDEAFA</item>
        <item name="cometchatSearchConversationItemBackgroundColor">#EDEAFA</item>
        <item name="cometchatSearchConversationSubtitleTextAppearance">@style/TextStyleTimesNewRoman</item>
        <item name="cometchatSearchConversationTitleTextAppearance">@style/TextStyleTimesNewRoman</item>
        <item name="cometchatSearchConversationTimestampTextAppearance">?attr/cometchatTextAppearanceCaption1Bold</item>
        <item name="cometchatSearchSeeMoreTextAppearance">@style/TextStyleTimesNewRoman</item>
        <item name="cometchatSearchMessageItemBackgroundColor">#EDEAFA</item>
        <item name="cometchatSearchMessageTitleTextAppearance">@style/TextStyleTimesNewRoman</item>
        <item name="cometchatSearchMessageSubtitleTextAppearance">@style/TextStyleTimesNewRoman</item>
        <item name="cometchatSearchMessageTimestampTextAppearance">@style/TextStyleTimesNewRoman</item>
        <item name="cometchatSearchBarTextAppearance">@style/TextStyleTimesNewRoman</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatSearchStyle">@style/CustomSearchStyle</item>
    </style>
</resources>
```

* **What this does**: applies custom search colors and text styles across search UI sections.

* **Verify**: open Search and check section headers, chips, and list items.

Attribute references:

* [Search attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_search.xml)

#### Message Information

The `CometChatMessageInformation` component displays message metadata such as delivery and read status.

<Frame>
  <img />
</Frame>

What you're changing: message information styling for metadata views.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatMessageInformation`

* **Default behavior**: UI Kit default metadata styling.

* **Override**: set `cometchatMessageInformationStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="CustomMessageInformationStyle" parent="CometChatMessageInformationStyle">
        <!-- Add overrides from attr_cometchat_message_information.xml -->
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatMessageInformationStyle">@style/CustomMessageInformationStyle</item>
    </style>
</resources>
```

* **What this does**: wires a custom Message Information style so you can override specific metadata attributes.

* **Verify**: open Message Information and confirm your overrides apply.

Attribute references:

* [Message Information attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_message_information.xml)

#### Message Option Sheet

The `CometChatMessageOptionSheet` component is the action menu for message-level actions.

<Frame>
  <img />
</Frame>

What you're changing: option sheet background and icon tint.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatMessageOptionSheet`

* **Default behavior**: UI Kit default option sheet styling.

* **Override**: set `cometchatPopupMenuStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="CustomMessageOptionSheetStyle" parent="CometChatMessageOptionSheetStyle">
        <item name="cometchatMessageOptionSheetIconTint">#F76808</item>
        <item name="cometchatMessageOptionSheetBackgroundColor">#FFF9F5</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatMessageListMessageOptionSheetStyle">@style/CustomMessageOptionSheetStyle</item>
    </style>
</resources>
```

* **What this does**: updates message option sheet icon tint and background color.

* **Verify**: long-press a message and confirm the option sheet styling.

Attribute references:

* [Message Option Sheet attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_message_option_sheet.xml)

#### Attachment Option Sheet

The `CometChatAttachmentOptionSheet` component renders the attachment picker.

<Frame>
  <img />
</Frame>

What you're changing: attachment option sheet background and icon tint.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatAttachmentOptionSheet`

* **Default behavior**: UI Kit default attachment sheet styling.

* **Override**: set `cometchatAttachmentOptionSheetStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="CustomAttachmentOptionSheetStyle" parent="CometChatAttachmentOptionSheetStyle">
        <item name="cometchatAttachmentOptionSheetBackgroundColor">#FFF9F5</item>
        <item name="cometchatAttachmentOptionSheetIconTint">#F76808</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatAttachmentOptionSheetStyle">@style/CustomAttachmentOptionSheetStyle</item>
    </style>
</resources>
```

* **What this does**: applies custom colors to the attachment picker sheet.

* **Verify**: open the attachment menu and confirm background and icons.

Attribute references:

* [Attachment Option Sheet attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_attachment_option_sheet.xml)

***

### Calling UI

#### Call Logs

The `CometChatCallLogs` component renders recent call history.

<Frame>
  <img />
</Frame>

What you're changing: call log list separators and title colors.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatCallLogs`
* **Default behavior**: UI Kit default call log styling.
* **Override**: set `cometchatCallLogsStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomAvatarStyle" parent="CometChatAvatarStyle">
            <item name="cometchatAvatarStrokeRadius">8dp</item>
            <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
        </style>

        <style name="CustomCallLogStyle" parent="CometChatCallLogsStyle">
            <item name="cometchatCallLogsSeparatorColor">#F76808</item>
            <item name="cometchatCallLogsTitleTextColor">#F76808</item>
            <item name="cometchatCallLogsAvatarStyle">@style/CustomAvatarStyle</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatCallLogsStyle">@style/CustomCallLogStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatCallLogs(
        style = CometChatCallLogsStyle.default().copy(
            separatorColor = Color(0xFFF76808),
            titleTextColor = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: applies custom avatar and text colors to the call logs list.
* **Verify**: open Call Logs and confirm the separator and title colors.

Attribute references:

* [Call Logs attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_call_logs.xml)

#### Incoming Call

The `CometChatIncomingCall` component renders the incoming call UI.

<Frame>
  <img />
</Frame>

What you're changing: incoming call background, buttons, and avatar styling.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatIncomingCall`
* **Default behavior**: UI Kit default incoming call layout and colors.
* **Override**: set `cometchatIncomingCallStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomIncomingCallStyle" parent="CometChatIncomingCallStyle">
            <item name="cometchatIncomingCallBackgroundColor">#AA9EE8</item>
            <item name="cometchatIncomingCallAcceptButtonBackgroundColor">?attr/cometchatPrimaryColor</item>
            <item name="cometchatIncomingCallRejectButtonTextColor">?attr/cometchatErrorColor</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatIncomingCallStyle">@style/CustomIncomingCallStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatIncomingCall(
        call = call,
        style = CometChatIncomingCallStyle.default().copy(
            backgroundColor = Color(0xFFAA9EE8)
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: customizes the incoming call screen background and action buttons.
* **Verify**: trigger an incoming call and confirm the background and button colors.

Attribute references:

* [Incoming Call attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_incoming_call.xml)
* [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml)

#### Outgoing Call

The `CometChatOutgoingCall` component renders the outgoing call UI.

<Frame>
  <img />
</Frame>

What you're changing: outgoing call avatar styling.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatOutgoingCall`
* **Default behavior**: UI Kit default outgoing call styling.
* **Override**: set `cometchatOutgoingCallStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomAvatarStyle" parent="CometChatAvatarStyle">
            <item name="cometchatAvatarStrokeRadius">8dp</item>
            <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
        </style>

        <style name="CustomOutgoingCall" parent="CometChatOutgoingCallStyle">
            <item name="cometchatOutgoingCallAvatarStyle">@style/CustomAvatarStyle</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatOutgoingCallStyle">@style/CustomOutgoingCall</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatOutgoingCall(
        call = call,
        style = CometChatOutgoingCallStyle.default().copy(
            avatarStyle = CometChatAvatarStyle.default().copy(
                backgroundColor = Color(0xFFFBAA75)
            )
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: applies a custom avatar style to the outgoing call screen.
* **Verify**: place a call and confirm the avatar styling.

Attribute references:

* [Outgoing Call attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_outgoing_call.xml)
* [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml)

#### Call Buttons

The `CometChatCallButton` component renders voice and video call buttons.

<Frame>
  <img />
</Frame>

What you're changing: button background, stroke, and icon tint.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatCallButtons`

* **Default behavior**: UI Kit default call button styling.

* **Override**: set `cometchatCallButtonsStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="CustomCallButtonStyle" parent="CometChatCallButtonsStyle">
        <item name="cometchatCallButtonsVideoCallIconTint">#6852D6</item>
        <item name="cometchatCallButtonsVoiceCallIconTint">#6852D6</item>
        <item name="cometchatCallButtonsMarginBetween">16dp</item>
        <item name="cometchatCallButtonsVideoCallButtonPadding">8dp</item>
        <item name="cometchatCallButtonsVoiceCallButtonPadding">8dp</item>
        <item name="cometchatCallButtonsVideoCallBackgroundColor">#EDEAFA</item>
        <item name="cometchatCallButtonsVoiceCallBackgroundColor">#EDEAFA</item>
        <item name="cometchatCallButtonsVideoCallStrokeWidth">1dp</item>
        <item name="cometchatCallButtonsVoiceCallStrokeWidth">1dp</item>
        <item name="cometchatCallButtonsVideoCallStrokeColor">#E8E8E8</item>
        <item name="cometchatCallButtonsVoiceCallStrokeColor">#E8E8E8</item>
        <item name="cometchatCallButtonsVideoCallCornerRadius">8dp</item>
        <item name="cometchatCallButtonsVoiceCallCornerRadius">8dp</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatCallButtonsStyle">@style/CustomCallButtonStyle</item>
    </style>
</resources>
```

* **What this does**: customizes call button padding, background, and icon colors.

* **Verify**: open a chat header and confirm button styling.

Attribute references:

* [Call Buttons attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_call_buttons.xml)

***

### AI UI

#### AI Assistant Chat History

The `CometChatAIAssistantChatHistory` component renders the AI conversation history view.

<Frame>
  <img />
</Frame>

What you're changing: background, header, and list typography.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatAIAssistantChatHistory`

* **Default behavior**: UI Kit default AI history styling.

* **Override**: set `cometChatAIAssistantChatHistoryStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="TextStyleTimesNewRoman">
        <item name="android:fontFamily">@font/times_new_roman_regular</item>
    </style>

    <style name="CustomAIAssistantChatHistoryStyle">
        <item name="cometChatAIAssistantChatHistoryBackgroundColor">#FFFAF6</item>
        <item name="cometChatAIAssistantChatHistoryHeaderBackgroundColor">#FFFAF6</item>
        <item name="cometChatAIAssistantChatHistoryHeaderTextColor">?attr/cometchatTextColorPrimary</item>
        <item name="cometChatAIAssistantChatHistoryHeaderTextAppearance">@style/TextStyleTimesNewRoman</item>
        <item name="cometChatAIAssistantChatHistoryNewChatBackgroundColor">#FFFAF6</item>
        <item name="cometChatAIAssistantChatHistoryNewChatTextColor">?attr/cometchatTextColorPrimary</item>
        <item name="cometChatAIAssistantChatHistoryNewChatTextAppearance">@style/TextStyleTimesNewRoman</item>
        <item name="cometChatAIAssistantChatHistoryDateSeparatorTextAppearance">@style/TextStyleTimesNewRoman</item>
        <item name="cometChatAIAssistantChatHistoryDateSeparatorTextColor">?attr/cometchatTextColorTertiary</item>
        <item name="cometChatAIAssistantChatHistoryDateSeparatorBackgroundColor">#FFFAF6</item>
        <item name="cometChatAIAssistantChatHistoryItemBackgroundColor">#FFFAF6</item>
        <item name="cometChatAIAssistantChatHistoryItemTextAppearance">@style/TextStyleTimesNewRoman</item>
        <item name="cometChatAIAssistantChatHistoryItemTextColor">?attr/cometchatTextColorPrimary</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometChatAIAssistantChatHistoryStyle">@style/CustomAIAssistantChatHistoryStyle</item>
    </style>
</resources>
```

* **What this does**: applies custom colors and font styling to the AI Assistant history screen.

* **Verify**: open AI Assistant history and confirm background and header styling.

Attribute references:

* [AI Assistant Chat History attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_ai_assistant_chat_history.xml)

#### AI Option Sheet

The `CometChatAIOptionSheet` component renders AI action options.

<Frame>
  <img />
</Frame>

What you're changing: AI option sheet background and icon tint.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatAIOptionSheet`

* **Default behavior**: UI Kit default AI option sheet styling.

* **Override**: set `cometchatAIOptionSheetStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="CustomAIOptionSheetStyle" parent="CometChatAIOptionSheetStyle">
        <item name="cometchatAIOptionSheetBackgroundColor">#FFF9F5</item>
        <item name="cometchatAIOptionSheetIconTint">#F76808</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatAIOptionSheetStyle">@style/CustomAIOptionSheetStyle</item>
    </style>
</resources>
```

* **What this does**: customizes AI option sheet colors.

* **Verify**: open AI actions and confirm the option sheet styling.

Attribute references:

* [AI Option Sheet attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_ai_option_sheet.xml)

#### Conversation Starter

The `CometChatConversationStarter` component renders AI-powered conversation starters.

<Frame>
  <img />
</Frame>

What you're changing: conversation starter item backgrounds.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatConversationStarter`

* **Default behavior**: UI Kit default conversation starter styling.

* **Override**: set `cometchatAIConversationStarterStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="CustomConversationStarterStyle" parent="CometChatAIConversationStarterStyle">
        <item name="cometchatAIConversationStarterItemBackgroundColor">#FBAA75</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatAIConversationStarterStyle">@style/CustomConversationStarterStyle</item>
    </style>
</resources>
```

* **What this does**: applies a custom background color to AI conversation starter items.

* **Verify**: open a new chat and confirm the conversation starter chip color.

Attribute references:

* [AI Conversation Starter attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_ai_conversation_starter.xml)

#### Conversation Summary

The `CometChatConversationSummary` component renders AI-generated summaries of chats.

<Frame>
  <img />
</Frame>

What you're changing: conversation summary background color.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatConversationSummary`

* **Default behavior**: UI Kit default conversation summary styling.

* **Override**: set `cometchatAIConversationSummaryStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="CustomConversationSummaryStyle" parent="CometChatAIConversationSummaryStyle">
        <item name="cometchatAIConversationSummaryBackgroundColor">#FBAA75</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatAIConversationSummaryStyle">@style/CustomConversationSummaryStyle</item>
    </style>
</resources>
```

* **What this does**: applies a custom background color to conversation summary cards.

* **Verify**: open a chat summary and confirm the background color.

Attribute references:

* [AI Conversation Summary attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_ai_conversation_summary.xml)

#### Smart Replies

The `CometChatSmartReplies` component renders AI-generated reply suggestions.

<Frame>
  <img />
</Frame>

What you're changing: smart reply background, item color, and stroke.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatSmartReplies`

* **Default behavior**: UI Kit default smart replies styling.

* **Override**: set `cometchatAISmartRepliesStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="CustomSmartRepliesStyle" parent="CometChatAISmartRepliesStyle">
        <item name="cometchatAISmartRepliesBackgroundColor">#FBBB90</item>
        <item name="cometchatAISmartRepliesTitleTextColor">#F76808</item>
        <item name="cometchatAISmartRepliesItemBackgroundColor">#FFF9F5</item>
        <item name="cometchatAISmartRepliesItemStrokeWidth">1dp</item>
        <item name="cometchatAISmartRepliesItemStrokeColor">#F76808</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatAISmartRepliesStyle">@style/CustomSmartRepliesStyle</item>
    </style>
</resources>
```

* **What this does**: customizes smart reply container and chip styling.

* **Verify**: open a conversation with smart replies enabled and confirm chip styling.

Attribute references:

* [AI Smart Replies attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_ai_smart_replies.xml)

***

### Base Components

#### Avatar

The `CometChatAvatar` component is used across lists and headers.

<Frame>
  <img />
</Frame>

What you're changing: avatar shape and background color.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatAvatar`
* **Default behavior**: UI Kit default avatar styling.
* **Override**: set `cometchatAvatarStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomAvatarStyle" parent="CometChatAvatarStyle">
            <item name="cometchatAvatarStrokeRadius">8dp</item>
            <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatAvatarStyle">@style/CustomAvatarStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // Globally via CometChatConversations, CometChatUsers, etc.
    style = ComponentStyle.default().copy(
        avatarStyle = CometChatAvatarStyle.default().copy(
            backgroundColor = Color(0xFFFBAA75),
            cornerRadius = 8.dp
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: applies a consistent avatar style across UI Kit components.
* **Verify**: open any list with avatars and confirm the style.

Attribute references:

* [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml)

#### Badge

The `CometChatBadge` component shows unread or notification counts.

<Frame>
  <img />
</Frame>

What you're changing: badge background, text color, and corner radius.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatBadge`
* **Default behavior**: UI Kit default badge styling.
* **Override**: set `cometchatBadgeStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomBadgeStyle" parent="CometChatBadgeStyle">
            <item name="cometchatBadgeBackgroundColor">#F44649</item>
            <item name="cometchatBadgeTextColor">#FFFFFF</item>
            <item name="cometchatBadgeCornerRadius">4dp</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatBadgeStyle">@style/CustomBadgeStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // Via parent component style
    style = CometChatConversationsStyle.default().copy(
        badgeStyle = CometChatBadgeStyle.default().copy(
            backgroundColor = Color(0xFFF44649),
            textColor = Color.White,
            cornerRadius = 4.dp
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: applies a custom badge appearance across UI Kit lists.
* **Verify**: check any unread badge to confirm colors and radius.

Attribute references:

* [Badge attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_badge.xml)

#### Status Indicator

The `CometChatStatusIndicator` component shows user presence status.

<Frame>
  <img />
</Frame>

What you're changing: status indicator icon shape and drawable.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatStatusIndicator`
* **Default behavior**: UI Kit default presence icon.
* **Override**: set `cometchatStatusIndicatorStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomStatusIndicatorStyle" parent="CometChatStatusIndicatorStyle">
            <item name="cometchatStatusIndicatorCornerRadius">8dp</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatStatusIndicatorStyle">@style/CustomStatusIndicatorStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // Via parent component style
    style = ComponentStyle.default().copy(
        statusIndicatorStyle = CometChatStatusIndicatorStyle.default().copy(
            cornerRadius = 8.dp
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: applies the custom status indicator in UI Kit components.
* **Verify**: check any user list to confirm the presence icon.

Attribute references:

* [Status Indicator attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_status_indicator.xml)

#### Reaction List

The `CometChatReactionList` component renders reactions on messages.

<Frame>
  <img />
</Frame>

What you're changing: active tab color in the reaction list.

* **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose)
* **Applies to**: `CometChatReactionList`
* **Default behavior**: UI Kit default reaction list styling.
* **Override**: set `cometchatReactionListStyle` in `AppTheme` or pass a style object.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <resources>
        <style name="CustomReactionListStyle" parent="CometChatReactionListStyle">
            <item name="cometchatReactionListTabTextActiveColor">#F76808</item>
        </style>

        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatReactionListStyle">@style/CustomReactionListStyle</item>
        </style>
    </resources>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatReactionList(
        style = CometChatReactionListStyle.default().copy(
            tabTextActiveColor = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

* **What this does**: applies a custom active tab color in the reaction list.
* **Verify**: open reactions and confirm the active tab color.

Attribute references:

* [Reaction List attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_reaction_list.xml)

#### Date

The `CometChatDate` component formats timestamps in lists and message threads.

<Frame>
  <img />
</Frame>

What you're changing: date text color.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatDate`

* **Default behavior**: UI Kit default date styling.

* **Override**: set `cometchatDateStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="CustomDateStyle" parent="CometChatDateStyle">
        <item name="cometchatDateTextColor">#000000</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatDateStyle">@style/CustomDateStyle</item>
    </style>
</resources>
```

* **What this does**: customizes date text color in UI Kit lists and headers.

* **Verify**: check any timestamp and confirm the color.

Attribute references:

* [Date attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_date.xml)

#### Receipts

The `CometChatReceipts` component renders read and delivered status icons.

<Frame>
  <img />
</Frame>

What you're changing: read receipt icon drawable.

* **Where to change it**: `res/drawable/read_receipts.xml` and `res/values/themes.xml`

* **Applies to**: `CometChatReceipts`

* **Default behavior**: UI Kit default receipt icons.

* **Override**: set `cometchatMessageReceiptStyle` in `AppTheme` and reference a custom drawable.

* **Code**:

```xml res/drawable/read_receipts.xml lines theme={null}
<vector xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:width="14dp"
    android:height="8dp"
    android:autoMirrored="true"
    android:viewportWidth="14"
    android:viewportHeight="8">

    <path
        android:fillColor="#ffab00"
        android:pathData="M0.4,4.622C0.289,4.511 0.236,4.38 0.242,4.228C0.247,4.076 0.305,3.944 0.417,3.833C0.528,3.726 0.659,3.671 0.811,3.669C0.963,3.668 1.094,3.722 1.205,3.833L3.761,6.4C3.824,6.463 3.891,6.53 3.961,6.6L4.161,6.8C4.272,6.911 4.327,7.041 4.325,7.189C4.323,7.337 4.267,7.467 4.155,7.578L4.144,7.589C4.033,7.696 3.904,7.751 3.755,7.753C3.607,7.755 3.478,7.7 3.367,7.589L0.4,4.622ZM6.9,6.394L12.822,0.472C12.933,0.361 13.065,0.306 13.217,0.308C13.368,0.31 13.5,0.367 13.611,0.478C13.718,0.589 13.773,0.72 13.775,0.872C13.777,1.024 13.722,1.155 13.611,1.267L7.289,7.589C7.178,7.7 7.048,7.755 6.9,7.755C6.752,7.755 6.622,7.7 6.511,7.589L3.544,4.622C3.437,4.515 3.385,4.384 3.389,4.23C3.393,4.077 3.448,3.944 3.555,3.833C3.667,3.722 3.799,3.667 3.953,3.667C4.106,3.667 4.239,3.722 4.35,3.833L6.9,6.394ZM10.461,1.272L7.289,4.444C7.181,4.552 7.053,4.604 6.903,4.6C6.753,4.596 6.622,4.541 6.511,4.433C6.4,4.322 6.344,4.19 6.344,4.036C6.344,3.882 6.4,3.75 6.511,3.639L9.672,0.478C9.78,0.37 9.91,0.317 10.064,0.317C10.218,0.317 10.35,0.37 10.461,0.478C10.572,0.589 10.628,0.721 10.628,0.875C10.628,1.029 10.572,1.161 10.461,1.272Z"
        tools:ignore="VectorPath" />
</vector>
```

* **What this does**: defines a custom read receipt icon.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="CustomMessageReceiptStyle" parent="CometChatMessageReceiptStyle">
        <item name="cometchatMessageReceiptReadIcon">@drawable/read_receipts</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatMessageReceiptStyle">@style/CustomMessageReceiptStyle</item>
    </style>
</resources>
```

* **What this does**: applies the custom receipt icon to message status indicators.

* **Verify**: send a message and check the receipt icon for read status.

Attribute references:

* [Message Receipt attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_message_receipt.xml)

#### Media Recorder

The `CometChatMediaRecorder` component controls audio and video message recording.

<Frame>
  <img />
</Frame>

What you're changing: recorder icon sizes and recording button background color.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatMediaRecorder`

* **Default behavior**: UI Kit default media recorder styling.

* **Override**: set `cometchatMediaRecorderStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="CustomMediaRecorderStyle" parent="CometChatMediaRecorderStyle">
        <item name="cometchatMediaRecorderDeleteIconRadius">@dimen/cometchat_12dp</item>
        <item name="cometchatMediaRecorderStartIconRadius">@dimen/cometchat_12dp</item>
        <item name="cometchatMediaRecorderPauseIconRadius">@dimen/cometchat_12dp</item>
        <item name="cometchatMediaRecorderRecordingIconBackgroundColor">#F44649</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatMediaRecorderStyle">@style/CustomMediaRecorderStyle</item>
    </style>
</resources>
```

* **What this does**: applies custom sizing and color to the media recorder UI.

* **Verify**: open the recorder and check icon sizes and record button color.

Attribute references:

* [Media Recorder attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_media_recorder.xml)

#### Sticker Keyboard

The `CometChatStickerKeyboard` component renders the sticker picker UI.

<Frame>
  <img />
</Frame>

What you're changing: sticker keyboard background color.

* **Where to change it**: `res/values/themes.xml`

* **Applies to**: `CometChatStickerKeyboard`

* **Default behavior**: UI Kit default sticker keyboard styling.

* **Override**: set `cometchatStickerKeyboardStyle` in `AppTheme`.

* **Code**:

```xml res/values/themes.xml lines theme={null}
<resources>
    <style name="CustomStickerKeyboardStyle" parent="CometChatStickerKeyboardStyle">
        <item name="cometchatStickerKeyboardBackgroundColor">#EDEAFA</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatStickerKeyboardStyle">@style/CustomStickerKeyboardStyle</item>
    </style>
</resources>
```

* **What this does**: applies a custom background color to the sticker keyboard.

* **Verify**: open the sticker keyboard and confirm the background color.

Attribute references:

* [Sticker Keyboard attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_sticker_keyboard.xml)

***

## Customization matrix

| What you want to change        | Where                          | Property or API                                    | Example                                          |
| ------------------------------ | ------------------------------ | -------------------------------------------------- | ------------------------------------------------ |
| Conversations avatar and badge | `themes.xml` / style param     | `cometchatConversationsStyle`                      | `cometchatConversationsBadgeStyle`               |
| Users list separators          | `themes.xml` / style param     | `cometchatUsersStyle`                              | `cometchatUsersSeparatorColor`                   |
| Group list titles              | `themes.xml` / style param     | `cometchatGroupsStyle`                             | `cometchatGroupsTitleTextColor`                  |
| Header call icons              | `themes.xml` / style param     | `cometchatMessageHeaderStyle`                      | `cometchatMessageHeaderCallButtonsStyle`         |
| Message list background        | `themes.xml` / style param     | `cometchatMessageListStyle`                        | `cometchatMessageListBackgroundColor`            |
| Search styling                 | `themes.xml` / style param     | `cometchatSearchStyle`                             | `cometchatSearchBackgroundColor`                 |
| Message Information            | `themes.xml` / style param     | `cometchatMessageInformationStyle`                 | `cometchatMessageInformationBackgroundColor`     |
| AI Chat History                | `themes.xml` / style param     | `cometchatAIAssistantChatHistoryStyle`             | `cometchatAIAssistantChatHistoryBackgroundColor` |
| Date formatting                | `themes.xml` / style param     | `cometchatDateStyle`                               | `cometchatDateTextColor`                         |
| Receipts icons                 | `themes.xml` / style param     | `cometchatReceiptsStyle`                           | `cometchatReceiptsReadColor`                     |
| Composer send button           | `res/drawable/` + `themes.xml` | `cometchatMessageComposerActiveSendButtonDrawable` | `@drawable/active_send_button`                   |
| Call buttons styling           | `themes.xml` / style param     | `cometchatCallButtonsStyle`                        | `cometchatCallButtonsVideoCallBackgroundColor`   |


# Overview
Source: https://www.cometchat.com/docs/ui-kit/android/components-overview

Browse all prebuilt UI components in the CometChat Android UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                    |
  | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
  | Packages       | `com.cometchat:chatuikit-kotlin-android` (Kotlin XML Views), `com.cometchat:chatuikit-compose-android` (Jetpack Compose) |
  | Required setup | `CometChatUIKit.init()` + `CometChatUIKit.login()` before rendering any component                                        |
  | Shared core    | `chatuikit-core` — ViewModels, repositories, use cases, events (shared by both modules)                                  |
  | Calling        | Requires separate `com.cometchat:calls-sdk-android` package                                                              |
</Accordion>

## Architecture

The UI Kit is a set of independent components that compose into chat layouts. A typical chat layout uses four core components:

* `CometChatConversations` — list of recent conversations
* `CometChatMessageHeader` — toolbar with avatar, name, status, typing indicator
* `CometChatMessageList` — scrollable message feed with reactions, receipts, threads
* `CometChatMessageComposer` — rich input with attachments, mentions, voice notes

Selecting a conversation yields a `User` or `Group` object. Pass it to the message components to load the chat.

Components communicate via `CometChatEvents` — a SharedFlow-based event bus. See [Events](/docs/ui-kit/android/events).

***

## Component Catalog

### Conversations and Lists

| Component                | Purpose                                 | Page                                           |
| ------------------------ | --------------------------------------- | ---------------------------------------------- |
| `CometChatConversations` | Scrollable list of recent conversations | [Conversations](/docs/ui-kit/android/conversations) |
| `CometChatUsers`         | Scrollable list of users                | [Users](/docs/ui-kit/android/users)                 |
| `CometChatGroups`        | Scrollable list of groups               | [Groups](/docs/ui-kit/android/groups)               |
| `CometChatGroupMembers`  | Scrollable list of group members        | [Group Members](/docs/ui-kit/android/group-members) |

### Messages

| Component                  | Purpose                                        | Page                                                      |
| -------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
| `CometChatMessageHeader`   | Toolbar with avatar, name, status, typing      | [Message Header](/docs/ui-kit/android/message-header)          |
| `CometChatMessageList`     | Message feed with reactions, receipts, threads | [Message List](/docs/ui-kit/android/message-list)              |
| `CometChatMessageComposer` | Rich input with attachments, mentions, voice   | [Message Composer](/docs/ui-kit/android/message-composer)      |
| `CometChatThreadHeader`    | Parent message bubble and reply count          | [Thread Header](/docs/ui-kit/android/threaded-messages-header) |

### Calling

| Component               | Purpose                      | Page                                           |
| ----------------------- | ---------------------------- | ---------------------------------------------- |
| `CometChatCallButtons`  | Voice and video call buttons | [Call Buttons](/docs/ui-kit/android/call-buttons)   |
| `CometChatIncomingCall` | Incoming call notification   | [Incoming Call](/docs/ui-kit/android/incoming-call) |
| `CometChatOutgoingCall` | Outgoing call screen         | [Outgoing Call](/docs/ui-kit/android/outgoing-call) |
| `CometChatCallLogs`     | Call history list            | [Call Logs](/docs/ui-kit/android/call-logs)         |

***

## Component API Pattern

All components share a consistent API surface across both modules.

### Setting User or Group

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageHeader.setUser(user)
    messageList.setUser(user)
    messageComposer.setUser(user)

    // Or for group chat
    messageHeader.setGroup(group)
    messageList.setGroup(group)
    messageComposer.setGroup(group)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageHeader(user = user)
    CometChatMessageList(user = user)
    CometChatMessageComposer(user = user)

    // Or for group chat
    CometChatMessageHeader(group = group)
    CometChatMessageList(group = group)
    CometChatMessageComposer(group = group)
    ```
  </Tab>
</Tabs>

### Callbacks

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setOnItemClick { conversation -> /* navigate */ }
    conversations.setOnError { exception -> /* handle error */ }
    conversations.setOnLoad { list -> /* data loaded */ }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        onItemClick = { conversation -> /* navigate */ },
        onError = { exception -> /* handle error */ },
        onLoad = { list -> /* data loaded */ }
    )
    ```
  </Tab>
</Tabs>

### Data Filtering

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setConversationsRequestBuilder(
        ConversationsRequest.ConversationsRequestBuilder().setLimit(20)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        conversationsRequestBuilder = ConversationsRequest.ConversationsRequestBuilder().setLimit(20)
    )
    ```
  </Tab>
</Tabs>

### View Slots

Replace specific regions of a component's UI. See [View Slots](/docs/ui-kit/android/customization-view-slots).

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setSubtitleView(object : ConversationsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View {
            return CustomSubtitleView(context)
        }
        override fun bindView(context: Context, createdView: View, conversation: Conversation, ...) {
            (createdView as CustomSubtitleView).bind(conversation)
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        subtitleView = { conversation, typingIndicator ->
            Text(conversation.lastMessage?.text ?: "")
        }
    )
    ```
  </Tab>
</Tabs>

### Styles

See [Component Styling](/docs/ui-kit/android/component-styling).

<Tabs>
  <Tab title="Kotlin (XML Views)">
    XML theme attributes in `themes.xml`:

    ```xml lines theme={null}
    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatConversationsStyle">@style/CustomConversationsStyle</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Style data classes via parameters:

    ```kotlin lines theme={null}
    CometChatConversations(
        style = CometChatConversationsStyle.default().copy(
            backgroundColor = Color(0xFFF5F5F5)
        )
    )
    ```
  </Tab>
</Tabs>

### Events

Global inter-component communication via `CometChatEvents`:

```kotlin lines theme={null}
// Subscribe to message events
viewModelScope.launch {
    CometChatEvents.messageEvents.collect { event ->
        when (event) {
            is CometChatMessageEvent.MessageSent -> { /* handle */ }
            is CometChatMessageEvent.MessageDeleted -> { /* handle */ }
            else -> {}
        }
    }
}
```

See [Events](/docs/ui-kit/android/events) for the full reference.

***

## Next Steps

<CardGroup>
  <Card title="Core Features" icon="comments" href="/ui-kit/android/core-features">
    Chat features included out of the box
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/android/theme-introduction">
    Customize colors, fonts, and styles
  </Card>

  <Card title="Customization" icon="sliders" href="/ui-kit/android/customization-overview">
    Deep customization via ViewModels, styles, and view slots
  </Card>

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


# Building A Conversation List + Message View
Source: https://www.cometchat.com/docs/ui-kit/android/conversation-message-view

Build a conversation list with a full-screen message view using the Kotlin XML Views or Jetpack Compose UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                                                                           |
  | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Components   | `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`                                                          |
  | Layout       | Sequential navigation — conversation list → full-screen message view                                                                                            |
  | Prerequisite | Complete [Kotlin Integration](/docs/ui-kit/android/getting-started-kotlin) or [Jetpack Compose Integration](/docs/ui-kit/android/getting-started-jetpack) Steps 1–3 first |
  | Pattern      | WhatsApp, Slack, Telegram                                                                                                                                       |
</Accordion>

This guide builds a sequential navigation chat layout — conversation list as the entry point, tap a conversation to open a full-screen message view.

This assumes you've already completed the integration guide for your chosen UI toolkit (project created, dependencies installed, init + login working).

***

## What You're Building

Three sections working together:

1. **Conversation list** — shows all active conversations (users and groups)
2. **Message header** — displays user/group name, avatar, and status
3. **Message list + composer** — chat history with real-time updates and text input

<Tabs>
  <Tab title="Kotlin (XML Views)">
    This implementation uses Android's standard Activity navigation: `ConversationActivity` displays the list, user taps a conversation, `MessageActivity` launches with the selected user/group data via Intent extras.
  </Tab>

  <Tab title="Jetpack Compose">
    This implementation uses Compose state to manage navigation between the conversation list and message screen — no Activities or Fragments needed beyond your `MainActivity`.
  </Tab>
</Tabs>

***

## Step 1: Set Up the Conversation List

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Create a new Activity called `ConversationActivity` to display the list of conversations.

    **Layout** — `activity_conversation.xml`:

    ```xml activity_conversation.xml lines theme={null}
    <androidx.constraintlayout.widget.ConstraintLayout
        xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:app="http://schemas.android.com/apk/res-auto"
        android:layout_width="match_parent"
        android:layout_height="match_parent">

        <com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations
            android:id="@+id/conversations"
            android:layout_width="0dp"
            android:layout_height="0dp"
            app:layout_constraintTop_toTopOf="parent"
            app:layout_constraintBottom_toBottomOf="parent"
            app:layout_constraintStart_toStartOf="parent"
            app:layout_constraintEnd_toEndOf="parent" />

    </androidx.constraintlayout.widget.ConstraintLayout>
    ```

    **Activity** — `ConversationActivity.kt`:

    ```kotlin ConversationActivity.kt lines theme={null}
    import android.content.Intent
    import android.os.Bundle
    import android.util.Log
    import androidx.activity.enableEdgeToEdge
    import androidx.appcompat.app.AppCompatActivity
    import com.cometchat.chat.models.Group
    import com.cometchat.chat.models.User
    import com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations

    class ConversationActivity : AppCompatActivity() {

        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            enableEdgeToEdge()
            setContentView(R.layout.activity_conversation)

            val conversations = findViewById<CometChatConversations>(R.id.conversations)

            conversations.setTitle("Chats")
            conversations.setOnItemClick { conversation ->
                val intent = Intent(this, MessageActivity::class.java)
                when (val entity = conversation.conversationWith) {
                    is User -> intent.putExtra("user", entity)
                    is Group -> intent.putExtra("group", entity)
                    else -> Log.e("ConversationActivity", "Unknown conversation type")
                }
                startActivity(intent)
            }
        }
    }
    ```

    <Warning>
      You must use an activity that supports the **lifecycle** API (`AppCompatActivity`, `ComponentActivity`, or `FragmentActivity`) to properly manage the UI Kit's lifecycle events.
    </Warning>
  </Tab>

  <Tab title="Jetpack Compose">
    Create a `ChatApp.kt` file with the root composable that manages navigation between the conversation list and message screen:

    ```kotlin ChatApp.kt lines theme={null}
    import androidx.compose.runtime.Composable
    import androidx.compose.runtime.getValue
    import androidx.compose.runtime.mutableStateOf
    import androidx.compose.runtime.remember
    import androidx.compose.runtime.setValue
    import com.cometchat.chat.models.Group
    import com.cometchat.chat.models.User

    @Composable
    fun ChatApp() {
        var selectedUser by remember { mutableStateOf<User?>(null) }
        var selectedGroup by remember { mutableStateOf<Group?>(null) }

        val inChat = selectedUser != null || selectedGroup != null

        if (!inChat) {
            ConversationsScreen(
                onConversationClick = { user, group ->
                    selectedUser = user
                    selectedGroup = group
                }
            )
        } else {
            MessageScreen(
                user = selectedUser,
                group = selectedGroup,
                onBack = {
                    selectedUser = null
                    selectedGroup = null
                }
            )
        }
    }
    ```

    Add the `ConversationsScreen` composable:

    ```kotlin ChatApp.kt lines theme={null}
    import androidx.compose.foundation.layout.fillMaxSize
    import androidx.compose.ui.Modifier
    import com.cometchat.uikit.compose.presentation.conversations.ui.CometChatConversations

    @Composable
    fun ConversationsScreen(
        onConversationClick: (User?, Group?) -> Unit
    ) {
        CometChatConversations(
            modifier = Modifier.fillMaxSize(),
            title = "Chats",
            onItemClick = { conversation ->
                when (val entity = conversation.conversationWith) {
                    is User -> onConversationClick(entity, null)
                    is Group -> onConversationClick(null, entity)
                }
            }
        )
    }
    ```
  </Tab>
</Tabs>

***

## Step 2: Set Up the Message Screen

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Create a new Activity — `MessageActivity` to display the chat interface.

    **Layout** — `activity_message.xml`:

    ```xml activity_message.xml lines theme={null}
    <LinearLayout
        xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:orientation="vertical">

        <com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader
            android:id="@+id/message_header"
            android:layout_width="match_parent"
            android:layout_height="wrap_content" />

        <com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
            android:id="@+id/message_list"
            android:layout_width="match_parent"
            android:layout_height="0dp"
            android:layout_weight="1" />

        <com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
            android:id="@+id/message_composer"
            android:layout_width="match_parent"
            android:layout_height="wrap_content" />

    </LinearLayout>
    ```

    **Activity** — `MessageActivity.kt`:

    ```kotlin MessageActivity.kt lines theme={null}
    import android.os.Bundle
    import android.widget.Toast
    import androidx.activity.enableEdgeToEdge
    import androidx.appcompat.app.AppCompatActivity
    import com.cometchat.chat.models.Group
    import com.cometchat.chat.models.User
    import com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
    import com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader
    import com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList

    class MessageActivity : AppCompatActivity() {

        private lateinit var messageHeader: CometChatMessageHeader
        private lateinit var messageList: CometChatMessageList
        private lateinit var messageComposer: CometChatMessageComposer

        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            enableEdgeToEdge()
            setContentView(R.layout.activity_message)

            messageHeader = findViewById(R.id.message_header)
            messageList = findViewById(R.id.message_list)
            messageComposer = findViewById(R.id.message_composer)

            val user = intent.getSerializableExtra("user") as? User
            val group = intent.getSerializableExtra("group") as? Group

            when {
                user != null -> {
                    messageHeader.setUser(user)
                    messageList.setUser(user)
                    messageComposer.setUser(user)
                }
                group != null -> {
                    messageHeader.setGroup(group)
                    messageList.setGroup(group)
                    messageComposer.setGroup(group)
                }
                else -> {
                    Toast.makeText(this, "Missing user or group data", Toast.LENGTH_SHORT).show()
                    finish()
                }
            }

            messageHeader.setOnBackPress { finish() }
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Add the `MessageScreen` composable with header, list, and composer stacked vertically:

    ```kotlin ChatApp.kt lines theme={null}
    import androidx.compose.foundation.layout.Column
    import androidx.compose.foundation.layout.WindowInsets
    import androidx.compose.foundation.layout.consumeWindowInsets
    import androidx.compose.foundation.layout.fillMaxSize
    import androidx.compose.foundation.layout.fillMaxWidth
    import androidx.compose.foundation.layout.imePadding
    import androidx.compose.foundation.layout.navigationBarsPadding
    import androidx.compose.foundation.layout.padding
    import androidx.compose.foundation.layout.statusBars
    import androidx.compose.material3.Scaffold
    import androidx.compose.runtime.Composable
    import androidx.compose.ui.Modifier
    import com.cometchat.chat.models.Group
    import com.cometchat.chat.models.User
    import com.cometchat.uikit.compose.presentation.messagecomposer.ui.CometChatMessageComposer
    import com.cometchat.uikit.compose.presentation.messageheader.ui.CometChatMessageHeader
    import com.cometchat.uikit.compose.presentation.messagelist.ui.CometChatMessageList

    @Composable
    fun MessageScreen(
        user: User? = null,
        group: Group? = null,
        onBack: () -> Unit
    ) {
        Scaffold(
            contentWindowInsets = WindowInsets.statusBars
        ) { paddingValues ->
            Column(
                modifier = Modifier
                    .fillMaxSize()
                    .padding(paddingValues)
                    .consumeWindowInsets(paddingValues)
                    .navigationBarsPadding()
                    .imePadding()
            ) {
                CometChatMessageHeader(
                    modifier = Modifier.fillMaxWidth(),
                    user = user,
                    group = group,
                    hideBackButton = false,
                    onBackPress = onBack
                )

                CometChatMessageList(
                    modifier = Modifier
                        .fillMaxWidth()
                        .weight(1f),
                    user = user,
                    group = group
                )

                CometChatMessageComposer(
                    modifier = Modifier.fillMaxWidth(),
                    user = user,
                    group = group
                )
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Step 3: Update MainActivity

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Update your `MainActivity` to launch `ConversationActivity` after successful login:

    ```kotlin MainActivity.kt lines theme={null}
    private fun loginUser() {
        CometChatUIKit.login("cometchat-uid-1", object : CometChat.CallbackListener<User>() {
            override fun onSuccess(user: User) {
                Log.d(TAG, "Login successful: ${user.uid}")

                // Launch Conversation List + Message View
                startActivity(Intent(this@MainActivity, ConversationActivity::class.java))
            }

            override fun onError(e: CometChatException) {
                Log.e(TAG, "Login failed: ${e.message}")
            }
        })
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Update your `MainActivity` to render `ChatApp()` after successful login:

    ```kotlin MainActivity.kt lines theme={null}
    setContent {
        when {
            error != null -> {
                Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                    Text(error ?: "Unknown error")
                }
            }
            !isReady -> {
                Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                    CircularProgressIndicator()
                }
            }
            else -> {
                ChatApp()
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Step 4: Register Activities & Permissions

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add the new activities to your `AndroidManifest.xml`:

    ```xml AndroidManifest.xml lines theme={null}
    <application ...>
        <activity android:name=".MainActivity" android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
        <activity android:name=".ConversationActivity" />
        <activity android:name=".MessageActivity" />
    </application>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    No additional activities needed — everything runs inside your existing `MainActivity`.
  </Tab>
</Tabs>

Ensure you've added the required permissions in your `AndroidManifest.xml`:

```xml AndroidManifest.xml lines theme={null}
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/android/components-overview">
    Explore all available UI Kit components and their customization options
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/android/theme-introduction">
    Customize colors, fonts, and styles to match your brand
  </Card>

  <Card title="Integration" icon="rocket" href="/ui-kit/android/getting-started">
    Back to the main integration guide
  </Card>

  <Card title="Feature Guides" icon="book" href="/ui-kit/android/guide-overview">
    Add capabilities like threaded messages, blocking, and group management
  </Card>
</CardGroup>


# Conversations
Source: https://www.cometchat.com/docs/ui-kit/android/conversations

Scrollable list of recent one-on-one and group conversations for the logged-in user.

`CometChatConversations` renders a scrollable list of recent conversations with real-time updates for new messages, typing indicators, read receipts, and user presence.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatConversations` is a list component. It renders recent conversations and emits the selected `Conversation` via `onItemClick`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a standard chat layout.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_chat.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations
        android:id="@+id/conversations"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    ```kotlin lines theme={null}
    val conversations = findViewById<CometChatConversations>(R.id.conversations)

    conversations.setOnItemClick { conversation ->
        when (val entity = conversation.conversationWith) {
            is User -> navigateToUserChat(entity)
            is Group -> navigateToGroupChat(entity)
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        modifier = Modifier.fillMaxSize(),
        onItemClick = { conversation ->
            when (val entity = conversation.conversationWith) {
                is User -> navigateToUserChat(entity)
                is Group -> navigateToGroupChat(entity)
            }
        }
    )
    ```
  </Tab>
</Tabs>

> See the [Conversation List + Message View](/docs/ui-kit/android/conversation-message-view) guide for a complete layout.

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add to your layout XML:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations
        android:id="@+id/conversations"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    Or programmatically:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(CometChatConversations(this))
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    @Composable
    fun ConversationsScreen() {
        CometChatConversations(
            modifier = Modifier.fillMaxSize()
        )
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

Or in a Fragment:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
        return CometChatConversations(requireContext())
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
        return ComposeView(requireContext()).apply {
            setContent { CometChatConversations() }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Filtering Conversations

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Pass a `ConversationsRequest.ConversationsRequestBuilder` to control what loads:

    ```kotlin lines theme={null}
    conversations.setConversationsRequestBuilder(
        ConversationsRequest.ConversationsRequestBuilder()
            .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
            .setLimit(20)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        conversationsRequestBuilder = ConversationsRequest.ConversationsRequestBuilder()
            .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
            .setLimit(20)
    )
    ```
  </Tab>
</Tabs>

### Filter Recipes

| Recipe                   | Builder method                                                |
| ------------------------ | ------------------------------------------------------------- |
| Only user conversations  | `.setConversationType(CONVERSATION_TYPE_USER)`                |
| Only group conversations | `.setConversationType(CONVERSATION_TYPE_GROUP)`               |
| Limit per page           | `.setLimit(10)`                                               |
| With tags                | `.setTags(listOf("vip")).withTags(true)`                      |
| Filter by user tags      | `.withUserAndGroupTags(true).setUserTags(listOf("premium"))`  |
| Filter by group tags     | `.withUserAndGroupTags(true).setGroupTags(listOf("support"))` |

<Warning>
  Pass the builder object, not the result of `.build()`. The component calls `.build()` internally. Default page size is 30 with infinite scroll.
</Warning>

***

## Actions and Events

### Callback Methods

#### `onItemClick`

Fires when a conversation row is tapped. Primary navigation hook.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setOnItemClick { conversation ->
        // Navigate to chat screen
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        onItemClick = { conversation ->
            // Navigate to chat screen
        }
    )
    ```
  </Tab>
</Tabs>

> Replaces the default item-click behavior. Your custom lambda executes instead of the built-in navigation.

#### `onItemLongClick`

Fires when a conversation row is long-pressed. Use for additional actions like delete or select.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setOnItemLongClick { conversation ->
        // Show context menu
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        onItemLongClick = { conversation ->
            // Show context menu
        }
    )
    ```
  </Tab>
</Tabs>

#### `onBackPress`

Fires when the user presses the back button in the toolbar.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setOnBackPress {
        finish()
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        onBackPress = { /* navigate back */ }
    )
    ```
  </Tab>
</Tabs>

#### `onSearchClick`

Fires when the user taps the search icon in the toolbar.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setOnSearchClick {
        // Open search screen
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        onSearchClick = { /* open search */ }
    )
    ```
  </Tab>
</Tabs>

#### `onSelection`

Fires when conversations are selected/deselected in multi-select mode.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE)
    conversations.setOnSelection { selectedConversations ->
        updateToolbar(selectedConversations.size)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        selectionMode = UIKitConstants.SelectionMode.MULTIPLE,
        onSelection = { selectedConversations ->
            updateToolbar(selectedConversations.size)
        }
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setOnError { exception ->
        Log.e("Conversations", "Error: ${exception.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        onError = { exception ->
            Log.e("Conversations", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched and loaded.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setOnLoad { conversations ->
        Log.d("Conversations", "Loaded ${conversations.size}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        onLoad = { conversations ->
            Log.d("Conversations", "Loaded ${conversations.size}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setOnEmpty {
        Log.d("Conversations", "No conversations")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        onEmpty = { /* no conversations */ }
    )
    ```
  </Tab>
</Tabs>

### Global Events

The component emits events via `CometChatEvents` that can be subscribed to from anywhere:

```kotlin lines theme={null}
viewModelScope.launch {
    CometChatEvents.conversationEvents.collect { event ->
        when (event) {
            is CometChatConversationEvent.ConversationDeleted -> { /* handle */ }
            is CometChatConversationEvent.ConversationUpdated -> { /* handle */ }
        }
    }
}
```

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

| SDK Listener                                                                                | Internal behavior                                                |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived`              | Moves conversation to top, updates last message and unread count |
| `onTypingStarted` / `onTypingEnded`                                                         | Shows/hides typing indicator in subtitle                         |
| `onMessagesDelivered` / `onMessagesRead`                                                    | Updates receipt indicators                                       |
| `onUserOnline` / `onUserOffline`                                                            | Updates presence status dot                                      |
| `onGroupMemberJoined` / `onGroupMemberLeft` / `onGroupMemberKicked` / `onGroupMemberBanned` | Updates group conversation metadata                              |

***

## Functionality

| Method (Kotlin XML)                      | Compose Parameter                      | Description            |
| ---------------------------------------- | -------------------------------------- | ---------------------- |
| `setBackIconVisibility(View.VISIBLE)`    | `hideBackIcon = false`                 | Toggle back button     |
| `setToolbarVisibility(View.GONE)`        | `hideToolbar = true`                   | Toggle toolbar         |
| `setSearchBoxVisibility(View.GONE)`      | `hideSearchBox = true`                 | Toggle search box      |
| `setDisableSoundForMessages(true)`       | `disableSoundForMessages = true`       | Disable message sounds |
| `setCustomSoundForMessages(R.raw.sound)` | `customSoundForMessages = R.raw.sound` | Custom message sound   |
| `setSelectionMode(MULTIPLE)`             | `selectionMode = MULTIPLE`             | Enable selection mode  |
| `setTitle("Chats")`                      | `title = "Chats"`                      | Custom toolbar title   |
| `setSearchPlaceholderText("Search...")`  | `searchPlaceholderText = "Search..."`  | Search placeholder     |

***

## Custom View Slots

### Leading View

Replace the avatar / left section.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setLeadingView(object : ConversationsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View {
            return ImageView(context).apply {
                layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp)
            }
        }

        override fun bindView(
            context: Context, createdView: View, conversation: Conversation,
            typingIndicator: TypingIndicator?, holder: RecyclerView.ViewHolder,
            conversations: List<Conversation>, position: Int
        ) {
            val imageView = createdView as ImageView
            // Load avatar image
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        leadingView = { conversation, typingIndicator ->
            CometChatAvatar(
                imageUrl = conversation.conversationWith?.avatar,
                name = conversation.conversationWith?.name
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Title View

Replace the name / title text.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setTitleView(object : ConversationsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View {
            return TextView(context)
        }

        override fun bindView(
            context: Context, createdView: View, conversation: Conversation,
            typingIndicator: TypingIndicator?, holder: RecyclerView.ViewHolder,
            conversations: List<Conversation>, position: Int
        ) {
            (createdView as TextView).text = conversation.conversationWith?.name ?: ""
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        titleView = { conversation, _ ->
            Text(
                text = conversation.conversationWith?.name ?: "",
                style = CometChatTheme.typography.heading4Medium
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

Replace the last message preview.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setSubtitleView(object : ConversationsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View {
            return TextView(context).apply { maxLines = 1; ellipsize = TextUtils.TruncateAt.END }
        }

        override fun bindView(
            context: Context, createdView: View, conversation: Conversation,
            typingIndicator: TypingIndicator?, holder: RecyclerView.ViewHolder,
            conversations: List<Conversation>, position: Int
        ) {
            val textView = createdView as TextView
            if (typingIndicator != null) {
                textView.text = "typing..."
            } else {
                textView.text = when (val msg = conversation.lastMessage) {
                    is TextMessage -> msg.text
                    is MediaMessage -> "📎 ${msg.attachment?.fileExtension ?: "Media"}"
                    else -> "New conversation"
                }
            }
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        subtitleView = { conversation, typingIndicator ->
            val text = if (typingIndicator != null) "typing..." else {
                when (val msg = conversation.lastMessage) {
                    is TextMessage -> msg.text ?: ""
                    is MediaMessage -> "📎 ${msg.attachment?.fileExtension ?: "Media"}"
                    else -> "New conversation"
                }
            }
            Text(text, maxLines = 1, overflow = TextOverflow.Ellipsis)
        }
    )
    ```
  </Tab>
</Tabs>

### Trailing View

Replace the timestamp / badge / right section.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setTrailingView(object : ConversationsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View {
            return TextView(context)
        }

        override fun bindView(
            context: Context, createdView: View, conversation: Conversation,
            typingIndicator: TypingIndicator?, holder: RecyclerView.ViewHolder,
            conversations: List<Conversation>, position: Int
        ) {
            (createdView as TextView).text = "${conversation.unreadMessageCount} unread"
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        trailingView = { conversation, _ ->
            if (conversation.unreadMessageCount > 0) {
                Badge { Text("${conversation.unreadMessageCount}") }
            }
        }
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setEmptyView(customEmptyView)
    conversations.setErrorView(customErrorView)
    conversations.setLoadingView(customLoadingView)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        emptyView = { Text("No conversations yet") },
        errorView = { onRetry -> Button(onClick = onRetry) { Text("Retry") } },
        loadingView = { CircularProgressIndicator() }
    )
    ```
  </Tab>
</Tabs>

### Overflow Menu

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setOverflowMenu(ImageButton(context).apply {
        setImageResource(R.drawable.ic_filter)
        setOnClickListener { /* show filter */ }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        overflowMenu = {
            IconButton(onClick = { /* show filter */ }) {
                Icon(painterResource(R.drawable.ic_filter), "Filter")
            }
        }
    )
    ```
  </Tab>
</Tabs>

***

## Menu Options

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Replace all options
    conversations.setOptions { context, conversation ->
        listOf(
            CometChatPopupMenu.MenuItem(id = "archive", name = "Archive", onClick = { /* ... */ }),
            CometChatPopupMenu.MenuItem(id = "mute", name = "Mute", onClick = { /* ... */ })
        )
    }

    // Append to defaults
    conversations.setAddOptions { context, conversation ->
        listOf(
            CometChatPopupMenu.MenuItem(id = "pin", name = "Pin", onClick = { /* ... */ })
        )
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        options = { context, conversation ->
            listOf(
                MenuItem(id = "archive", name = "Archive", onClick = { /* ... */ }),
                MenuItem(id = "mute", name = "Mute", onClick = { /* ... */ })
            )
        },
        addOptions = { context, conversation ->
            listOf(MenuItem(id = "pin", name = "Pin", onClick = { /* ... */ }))
        }
    )
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Minimal list — hide all chrome

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setToolbarVisibility(View.GONE)
    conversations.setSearchBoxVisibility(View.GONE)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        hideToolbar = true,
        hideSearchBox = true
    )
    ```
  </Tab>
</Tabs>

### Users-only conversations

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setConversationsRequestBuilder(
        ConversationsRequest.ConversationsRequestBuilder()
            .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        conversationsRequestBuilder = ConversationsRequest.ConversationsRequestBuilder()
            .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
    )
    ```
  </Tab>
</Tabs>

### Custom date formatting

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setDateTimeFormatter(object : DateTimeFormatterCallback {
        override fun today(timestamp: Long) = "Today"
        override fun yesterday(timestamp: Long) = "Yesterday"
        override fun otherDays(timestamp: Long) = SimpleDateFormat("MMM d", Locale.getDefault()).format(Date(timestamp))
        override fun time(timestamp: Long) = SimpleDateFormat("h:mm a", Locale.getDefault()).format(Date(timestamp))
        override fun minutes(diff: Long, timestamp: Long) = "${diff}m ago"
        override fun hours(diff: Long, timestamp: Long) = "${diff}h ago"
        override fun lastWeek(timestamp: Long) = "Last week"
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        dateTimeFormatter = object : DateTimeFormatterCallback {
            override fun today(timestamp: Long) = "Today"
            override fun yesterday(timestamp: Long) = "Yesterday"
            override fun otherDays(timestamp: Long) = SimpleDateFormat("MMM d", Locale.getDefault()).format(Date(timestamp))
            override fun time(timestamp: Long) = SimpleDateFormat("h:mm a", Locale.getDefault()).format(Date(timestamp))
            override fun minutes(diff: Long, timestamp: Long) = "${diff}m ago"
            override fun hours(diff: Long, timestamp: Long) = "${diff}h ago"
            override fun lastWeek(timestamp: Long) = "Last week"
        }
    )
    ```
  </Tab>
</Tabs>

***

## Advanced Methods

### Programmatic Selection

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Enable selection
    conversations.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE)

    // Select a conversation
    conversations.selectConversation(conversation, UIKitConstants.SelectionMode.MULTIPLE)

    // Get selected
    val selected = conversations.getSelectedConversations()

    // Clear
    conversations.clearSelection()
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Selection is managed via the `selectionMode` and `onSelection` parameters. The component handles selection state internally.
  </Tab>
</Tabs>

### ViewModel Access

```kotlin lines theme={null}
val factory = CometChatConversationsViewModelFactory(
    repository = MyCustomRepository() // optional
)
val viewModel = ViewModelProvider(this, factory)
    .get(CometChatConversationsViewModel::class.java)
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        conversationsViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

See [ViewModel & Data](/docs/ui-kit/android/customization-viewmodel-data) for ListOperations, state observation, and custom repositories.

***

## Style

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Define a custom style in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="CustomConversationsStyle" parent="CometChatConversationsStyle">
        <item name="cometchatConversationsAvatarStyle">@style/CustomAvatarStyle</item>
        <item name="cometchatConversationsBadgeStyle">@style/CustomBadgeStyle</item>
        <item name="cometchatConversationsReceiptStyle">@style/CustomReceiptStyle</item>
        <item name="cometchatConversationsDateStyle">@style/CustomDateStyle</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatConversationsStyle">@style/CustomConversationsStyle</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        style = CometChatConversationsStyle.default().copy(
            backgroundColor = Color(0xFFF5F5F5),
            titleTextColor = Color(0xFF141414),
            searchBoxStyle = CometChatSearchBoxStyle.default().copy(
                backgroundColor = Color(0xFFFFFFFF)
            ),
            itemStyle = CometChatConversationsItemStyle.default().copy(
                backgroundColor = Color.White,
                titleTextColor = Color(0xFF141414),
                subtitleTextColor = Color(0xFF727272),
                avatarStyle = CometChatAvatarStyle.default().copy(cornerRadius = 12.dp),
                badgeStyle = CometChatBadgeStyle.default().copy(backgroundColor = Color(0xFFF76808)),
                dateStyle = CometChatDateStyle.default().copy(textColor = Color(0xFFA1A1A1)),
                receiptStyle = CometChatReceiptStyle.default().copy(),
                statusIndicatorStyle = CometChatStatusIndicatorStyle.default().copy(),
                typingIndicatorStyle = CometChatTypingIndicatorStyle.default().copy()
            )
        )
    )
    ```
  </Tab>
</Tabs>

### Style Properties

| Property                            | Description                |
| ----------------------------------- | -------------------------- |
| `backgroundColor`                   | List background color      |
| `titleTextColor`                    | Toolbar title color        |
| `searchBoxStyle`                    | Search box appearance      |
| `itemStyle.backgroundColor`         | Row background             |
| `itemStyle.selectedBackgroundColor` | Selected row background    |
| `itemStyle.titleTextColor`          | Conversation name color    |
| `itemStyle.subtitleTextColor`       | Last message preview color |
| `itemStyle.separatorColor`          | Row separator color        |
| `itemStyle.avatarStyle`             | Avatar appearance          |
| `itemStyle.badgeStyle`              | Unread badge appearance    |
| `itemStyle.dateStyle`               | Timestamp appearance       |
| `itemStyle.receiptStyle`            | Read receipt icons         |
| `itemStyle.statusIndicatorStyle`    | Online/offline indicator   |
| `itemStyle.typingIndicatorStyle`    | Typing indicator text      |
| `itemStyle.mentionStyle`            | Mention highlight style    |

See [Component Styling](/docs/ui-kit/android/component-styling) for the full reference.

***

## Next Steps

<CardGroup>
  <Card title="Conversation List + Message View" icon="comments" href="/ui-kit/android/conversation-message-view">
    Build a full chat layout with this component
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/android/component-styling">
    Detailed styling reference with screenshots
  </Card>

  <Card title="ViewModel & Data" icon="database" href="/ui-kit/android/customization-viewmodel-data">
    Custom ViewModels, repositories, and ListOperations
  </Card>

  <Card title="View Slots" icon="puzzle-piece" href="/ui-kit/android/customization-view-slots">
    Replace specific UI regions across all components
  </Card>
</CardGroup>


# Core
Source: https://www.cometchat.com/docs/ui-kit/android/core-features

Overview of CometChat's core chat features including instant messaging, media sharing, read receipts, typing indicators, user presence, reactions, mentions, threaded conversations, and moderation.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                                                                                             |
  | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Packages       | `com.cometchat:chatuikit-kotlin-android` (Kotlin XML Views), `com.cometchat:chatuikit-compose-android` (Jetpack Compose)                                                                                                          |
  | Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login()` — must complete before rendering any component                                                                                                                              |
  | Core features  | Instant Messaging, Media Sharing, Read Receipts, Mark as Unread, Typing Indicator, User Presence, Reactions, Mentions, Rich Text Formatting, Quoted Reply, Search, Threaded Conversations, Moderation, Report Message, Group Chat |
  | Key components | `CometChatConversations`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageHeader`, `CometChatUsers`, `CometChatGroups`, `CometChatGroupMembers`, `CometChatMessageInformation`, `CometChatThreadHeader`      |
  | Theming        | See [Theming](/docs/ui-kit/android/theme-introduction)                                                                                                                                                                                 |
</Accordion>

The UI Kit components work together to deliver a complete chat experience. The sections below map each core feature to the components that power it.

## Instant Messaging

Real-time text messaging — users can send and receive instant messages.

<Frame>
  <img />
</Frame>

| Component                                                    | Role                                                   |
| ------------------------------------------------------------ | ------------------------------------------------------ |
| [CometChatMessageComposer](/docs/ui-kit/android/message-composer) | Enables users to write and send text messages.         |
| [CometChatMessageList](/docs/ui-kit/android/message-list)         | Renders sent and received messages using text bubbles. |

## Media Sharing

Share multiple images, videos, audio files, and documents in a single send. Tapping the attachment button opens a multi-select picker; the picks stage in a preview tray above the input box with per-file upload progress, and send together with an optional caption — all out of the box.

<Frame>
  <img alt="Multi-attachment message list showing an image grid, a file card, and an audio bubble with caption, plus the composer staging tray with mixed image, video, and file tiles" />
</Frame>

| Component                                                                         | Role                                                                                                          |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [CometChatMessageComposer](/docs/ui-kit/android/message-composer#multiple-attachments) | Multi-select picker, an attachment tray that uploads before send, and the composer text as the batch caption. |
| [CometChatMessageList](/docs/ui-kit/android/message-list#multiple-attachments)         | Renders received attachments with per-type bubbles and groups a multi-type send as one visual batch.          |

A mixed pick is split into one message per attachment type (images → videos → audios → files) that render as grouped bubbles: an image/video **grid**, a stacked **audio player** list, and a connected **file card** stack. Per-message file count and per-file size limits come from your app's dashboard settings.

**Supported media types:**

| Type   | Single                                                                            | Multiple                                                              |
| ------ | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Images | [Image Bubble](/docs/ui-kit/android/message-bubble-styling#image-bubble)               | [Images Bubble](/docs/ui-kit/android/message-bubble-styling#images-bubble) |
| Videos | [Video Bubble](/docs/ui-kit/android/message-bubble-styling#video-bubble)               | [Videos Bubble](/docs/ui-kit/android/message-bubble-styling#videos-bubble) |
| Audio  | [Audio Bubble](/docs/ui-kit/android/message-bubble-styling#audio-bubble) (voice notes) | [Audios Bubble](/docs/ui-kit/android/message-bubble-styling#audios-bubble) |
| Files  | [File Bubble](/docs/ui-kit/android/message-bubble-styling#file-bubble)                 | [Files Bubble](/docs/ui-kit/android/message-bubble-styling#files-bubble)   |

## Read Receipts

Visibility into message status — delivered and read indicators.

<Frame>
  <img />
</Frame>

| Component                                                                            | Role                                                                    |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| [CometChatConversations](/docs/ui-kit/android/conversations)                              | Displays delivery status of the last message in each conversation item. |
| [CometChatMessageList](/docs/ui-kit/android/message-list)                                 | Shows read receipt status on every message bubble.                      |
| [CometChatMessageInformation](/docs/ui-kit/android/component-styling#message-information) | Shows detailed delivery and read status for a specific sent message.    |

## Mark as Unread

Users can manually mark messages as unread to revisit important conversations later. The message list can start from the first unread message automatically.

<Frame>
  <img />
</Frame>

| Component                                               | Role                                                                                                         |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| [CometChatMessageList](/docs/ui-kit/android/message-list)    | Provides the "Mark as unread" option in message actions and supports starting from the first unread message. |
| [CometChatConversations](/docs/ui-kit/android/conversations) | Reflects updated unread count in real-time.                                                                  |

## Typing Indicators

Shows when a user is typing a response in real-time.

<Frame>
  <img />
</Frame>

| Component                                                | Role                                                                              |
| -------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [CometChatConversations](/docs/ui-kit/android/conversations)  | Shows real-time typing status in conversation items.                              |
| [CometChatMessageHeader](/docs/ui-kit/android/message-header) | Displays a "typing..." indicator when the other user or a group member is typing. |

## User Presence

See whether contacts are online or offline.

<Frame>
  <img />
</Frame>

| Component                                                | Role                                         |
| -------------------------------------------------------- | -------------------------------------------- |
| [CometChatConversations](/docs/ui-kit/android/conversations)  | Shows user presence in conversation items.   |
| [CometChatMessageHeader](/docs/ui-kit/android/message-header) | Displays user presence in the chat header.   |
| [CometChatUsers](/docs/ui-kit/android/users)                  | Shows presence indicators in the user list.  |
| [CometChatGroupMembers](/docs/ui-kit/android/group-members)   | Shows presence indicators for group members. |

## Reactions

React to messages with emojis without typing a full response.

<Frame>
  <img />
</Frame>

| Component                                            | Role                                                                    |
| ---------------------------------------------------- | ----------------------------------------------------------------------- |
| [CometChatMessageList](/docs/ui-kit/android/message-list) | Displays reactions on message bubbles and provides the reaction picker. |

## Mentions

Address specific users in a conversation by typing `@` to trigger mention suggestions.

<Frame>
  <img />
</Frame>

| Component                                                    | Role                                                                |
| ------------------------------------------------------------ | ------------------------------------------------------------------- |
| [CometChatConversations](/docs/ui-kit/android/conversations)      | Shows where users have been mentioned from the conversation list.   |
| [CometChatMessageComposer](/docs/ui-kit/android/message-composer) | Triggers mention suggestions on `@` and inserts formatted mentions. |
| [CometChatMessageList](/docs/ui-kit/android/message-list)         | Renders mentions with distinct styling in the message flow.         |

## Rich Text Formatting

Rich Text Formatting allows users to style their messages with bold, italic, strikethrough, code, code blocks, blockquotes, ordered/unordered lists, and links. This brings richer expression to conversations and helps users emphasize key points.

<Frame>
  <img />
</Frame>

| Component                                                    | Role                                                                                                                                                                          |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [CometChatMessageComposer](/docs/ui-kit/android/message-composer) | Provides a built-in rich text editor with formatting toolbar and text selection menu items for bold, italic, strikethrough, code, links, lists, blockquotes, and code blocks. |
| [CometChatMessageList](/docs/ui-kit/android/message-list)         | Renders formatted messages with the appropriate styling automatically applied, ensuring that rich text formatting is displayed exactly as intended by the sender.             |

## Threaded Conversations

Respond directly to a specific message, keeping conversations organized.

<Frame>
  <img />
</Frame>

| Component                                                         | Role                                               |
| ----------------------------------------------------------------- | -------------------------------------------------- |
| [CometChatThreadHeader](/docs/ui-kit/android/threaded-messages-header) | Displays all replies made to a particular message. |
| [CometChatMessageComposer](/docs/ui-kit/android/message-composer)      | Allows composing messages within a thread.         |
| [CometChatMessageList](/docs/ui-kit/android/message-list)              | Displays threaded messages in context.             |

## Quoted Replies

Reply to specific messages by selecting "Reply" from the message action menu, maintaining context in the conversation.

<Frame>
  <img />
</Frame>

| Component                                                    | Role                                                      |
| ------------------------------------------------------------ | --------------------------------------------------------- |
| [CometChatMessageList](/docs/ui-kit/android/message-list)         | Provides the "Reply" option in message actions.           |
| [CometChatMessageComposer](/docs/ui-kit/android/message-composer) | Shows the quoted reply above the input field for context. |

## Group Chats

Conversations with multiple participants — team collaborations, group discussions, and communities.

<Frame>
  <img />
</Frame>

| Component                                              | Role                                                       |
| ------------------------------------------------------ | ---------------------------------------------------------- |
| [CometChatGroups](/docs/ui-kit/android/groups)              | Lists and manages groups.                                  |
| [CometChatGroupMembers](/docs/ui-kit/android/group-members) | Displays and manages group members with roles and actions. |

## Moderation

Automatically filter and manage inappropriate content based on predefined rules.

<Frame>
  <img />
</Frame>

<Note>
  Learn more about setting up moderation rules in the [Moderation](/docs/moderation/overview) documentation.
</Note>

| Component                                            | Role                                                                                      |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [CometChatMessageList](/docs/ui-kit/android/message-list) | Handles moderated messages, displaying blocked content based on your moderation settings. |

## Report Message

Users can report inappropriate messages by choosing from predefined reasons with optional remarks.

<Note>
  Learn more about flagged messages in the [Flagged Messages](/docs/moderation/flagged-messages) documentation.
</Note>

<Frame>
  <img />
</Frame>

| Component                                            | Role                                                     |
| ---------------------------------------------------- | -------------------------------------------------------- |
| [CometChatMessageList](/docs/ui-kit/android/message-list) | Provides the "Report Message" option in message actions. |

## Conversation and Advanced Search

Conversation and Advanced Search enables users to quickly find conversations, messages, and media across chats in real time. It supports filters, scopes, and custom actions, allowing users to locate content efficiently while keeping the chat experience smooth and intuitive.

<Frame>
  <img />
</Frame>

| Component                                                | Role                                                                                                                                                                |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [CometChatSearch](/docs/ui-kit/android/search)                | Allows users to search across conversations and messages in real time. Users can click on a result to open the conversation or jump directly to a specific message. |
| [CometChatMessageHeader](/docs/ui-kit/android/message-header) | Shows the search button in the chat header, allowing users to search within a conversation.                                                                         |
| [CometChatMessageList](/docs/ui-kit/android/message-list)     | Shows the selected message when clicked from search results and highlights it in the message list.                                                                  |
| [CometChatConversations](/docs/ui-kit/android/conversations)  | Displays the search input.                                                                                                                                          |

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/android/components-overview">
    Browse all available UI Kit components
  </Card>

  <Card title="Theme" icon="palette" href="/ui-kit/android/theme-introduction">
    Customize the look and feel of your chat UI
  </Card>

  <Card title="Call Features" icon="phone" href="/ui-kit/android/call-features">
    Add audio and video calling
  </Card>

  <Card title="AI Features" icon="robot" href="/ui-kit/android/ai-features">
    Explore AI-powered chat capabilities
  </Card>
</CardGroup>


# Custom Text Formatter
Source: https://www.cometchat.com/docs/ui-kit/android/custom-text-formatter-guide

Extend CometChatTextFormatter to build custom inline text patterns with tracking characters and suggestion lists.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                                            |
  | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Packages       | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack`                                                                                                             |
  | Key class      | `CometChatTextFormatter` (abstract base class for custom formatters)                                                                                                             |
  | Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login("UID")`                                                                                                                       |
  | Purpose        | Extend to create custom inline text patterns with tracking characters, suggestion lists, and span formatting                                                                     |
  | Features       | Tracking character activation, suggestion list, span formatting per context (composer, bubbles, conversations), pre-send hooks                                                   |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin)                                                                                         |
  | Related        | [Mentions Formatter](/docs/ui-kit/android/mentions-formatter-guide) \| [ShortCut Formatter](/docs/ui-kit/android/shortcut-formatter-guide) \| [All Guides](/docs/ui-kit/android/guide-overview) |
</Accordion>

`CometChatTextFormatter` is an abstract class for formatting text in the message composer and message bubbles. Extend it to build custom formatters — hashtags, shortcuts, or any pattern triggered by a tracking character.

| Capability            | Description                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| Tracking character    | Activates the formatter when the user types a specific character (e.g., `#`, `!`)               |
| Suggestion list       | Populates a dropdown of `SuggestionItem` objects as the user types                              |
| Span formatting       | Applies `SpannableStringBuilder` spans per context: composer, left/right bubbles, conversations |
| Pre-send hook         | `handlePreMessageSend` lets you modify the message before it's sent                             |
| Component integration | Plugs into any component via `setTextFormatters()`                                              |

***

## Steps

### 1. Create a class extending CometChatTextFormatter

Pass your tracking character to the superclass constructor.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    class HashTagFormatter : CometChatTextFormatter('#') {
        private val suggestions: MutableList<SuggestionItem> = ArrayList()
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // Same class — formatters are shared between both modules
    class HashTagFormatter : CometChatTextFormatter('#') {
        private val suggestions: MutableList<SuggestionItem> = ArrayList()
    }
    ```
  </Tab>
</Tabs>

### 2. Override the search method

Called when the user types after the tracking character. Match input against your data and update the suggestion list.

```kotlin lines theme={null}
override fun search(context: Context, queryString: String?) {
    suggestions.clear()
    val query = "#${queryString ?: ""}"
    // Match against your hashtag data source
    val matchingTags = getMatchingTags(query)
    for (tag in matchingTags) {
        val item = SuggestionItem("", tag, null, null, tag, null, null)
        item.isHideLeadingIcon = true
        suggestions.add(item)
    }
    setSuggestionItemList(suggestions)
}
```

### 3. Override onScrollToBottom

Required by the base class. Implement pagination logic or leave empty.

```kotlin theme={null}
override fun onScrollToBottom() {
    // Load more suggestions if needed
}
```

### 4. Override span formatting methods (optional)

Customize how matched text renders in different contexts using `SpannableStringBuilder`.

```kotlin lines theme={null}
override fun prepareLeftMessageBubbleSpan(
    context: Context, baseMessage: BaseMessage, spannable: SpannableStringBuilder
): SpannableStringBuilder? {
    // Apply custom spans for incoming message bubbles
    return applyHashTagSpans(spannable, Color.parseColor("#5dff05"))
}

override fun prepareRightMessageBubbleSpan(
    context: Context, baseMessage: BaseMessage, spannable: SpannableStringBuilder
): SpannableStringBuilder? {
    // Apply custom spans for outgoing message bubbles
    return applyHashTagSpans(spannable, Color.parseColor("#30b3ff"))
}
```

### 5. Integrate with a component

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.core.CometChatUIKit

    val textFormatters = CometChatUIKit.getDataSource().getTextFormatters(this, messageComposer.additionParameter)
    textFormatters.add(HashTagFormatter())
    messageComposer.setTextFormatters(textFormatters)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.core.CometChatUIKit

    // In your composable or ViewModel setup
    val textFormatters = CometChatUIKit.getDataSource().getTextFormatters(context, additionParameter)
    textFormatters.add(HashTagFormatter())

    CometChatMessageComposer(
        user = user,
        textFormatters = textFormatters
    )
    ```
  </Tab>
</Tabs>

Pass the same list to `CometChatMessageList` and `CometChatConversations` via their `setTextFormatters()` methods to apply formatting across all contexts.

***

## Methods Reference

| Method                                                                        | Description                                                                                            |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `search(Context, String)`                                                     | Abstract — called when user types after the tracking character. Update the suggestion list here.       |
| `onScrollToBottom()`                                                          | Abstract — called when the suggestion list scrolls to the bottom. Implement pagination or leave empty. |
| `onItemClick(Context, SuggestionItem, User, Group)`                           | Called when a suggestion item is selected. Override to customize insertion behavior.                   |
| `handlePreMessageSend(Context, BaseMessage)`                                  | Called before a message is sent. Override to modify the message (e.g., add metadata).                  |
| `prepareLeftMessageBubbleSpan(Context, BaseMessage, SpannableStringBuilder)`  | Override to format text in incoming message bubbles.                                                   |
| `prepareRightMessageBubbleSpan(Context, BaseMessage, SpannableStringBuilder)` | Override to format text in outgoing message bubbles.                                                   |
| `prepareComposerSpan(Context, BaseMessage, SpannableStringBuilder)`           | Override to format text in the message composer.                                                       |
| `prepareConversationSpan(Context, BaseMessage, SpannableStringBuilder)`       | Override to format text in the conversations list preview.                                             |
| `setSuggestionItemList(List<SuggestionItem>)`                                 | Updates the suggestion dropdown with new items.                                                        |
| `setDisableSuggestions(boolean)`                                              | Disables the suggestion dropdown entirely. (`protected` — accessible from subclasses only.)            |
| `setInfoText(String)`                                                         | Sets informational text displayed above the suggestion list.                                           |
| `setInfoVisibility(boolean)`                                                  | Toggles visibility of the info text.                                                                   |
| `setShowLoadingIndicator(boolean)`                                            | Shows/hides a loading spinner in the suggestion dropdown.                                              |
| `getTrackingCharacter()`                                                      | Returns the tracking character passed to the constructor.                                              |

***

## Next Steps

<CardGroup>
  <Card title="Mentions Formatter" icon="at" href="/ui-kit/android/mentions-formatter-guide">
    Built-in @mention formatting with styled tokens
  </Card>

  <Card title="ShortCut Formatter" icon="bolt" href="/ui-kit/android/shortcut-formatter-guide">
    Shortcut text expansion via the message-shortcuts extension
  </Card>

  <Card title="All Guides" icon="book" href="/ui-kit/android/guide-overview">
    Browse all feature and formatter guides
  </Card>

  <Card title="Sample App" icon="github" href="https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin">
    Full working sample application on GitHub
  </Card>
</CardGroup>


# Events & Callbacks
Source: https://www.cometchat.com/docs/ui-kit/android/customization-events

Handle user interaction events, selection mode, and global UI Kit events.

The UI Kit provides two levels of event handling: component-level callbacks set directly on a component, and global events via the `CometChatEvents` singleton using Kotlin `SharedFlow`.

***

## Component-Level Callbacks

### Click Callbacks

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setOnItemClick { conversation ->
        // Navigate to chat screen
    }

    conversations.setOnItemLongClick { conversation ->
        // Show context menu
    }

    conversations.setOnBackPress {
        // Handle back navigation
    }

    conversations.setOnSearchClick {
        // Open search
    }

    conversations.setOnError { exception ->
        Log.e("Conversations", "Error: ${exception.message}")
    }

    conversations.setOnLoad { list ->
        Log.d("Conversations", "Loaded ${list.size} conversations")
    }

    conversations.setOnEmpty {
        Log.d("Conversations", "No conversations")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        onItemClick = { conversation ->
            // Navigate to chat screen
        },
        onItemLongClick = { conversation ->
            // Show context menu
        },
        onBackPress = {
            // Handle back navigation
        },
        onSearchClick = {
            // Open search
        },
        onError = { exception ->
            Log.e("Conversations", "Error: ${exception.message}")
        },
        onLoad = { list ->
            Log.d("Conversations", "Loaded ${list.size} conversations")
        },
        onEmpty = {
            Log.d("Conversations", "No conversations")
        }
    )
    ```
  </Tab>
</Tabs>

***

## Selection Mode

Enable single or multi-select on list components:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Enable multi-select mode
    conversations.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE)

    // Listen for selection changes
    conversations.setOnSelection { selectedList ->
        updateToolbar(selectedList.size)
    }

    // Get selected items
    val selected = conversations.getSelectedConversations()

    // Clear selection
    conversations.clearSelection()
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        selectionMode = UIKitConstants.SelectionMode.MULTIPLE,
        onSelection = { selectedList ->
            updateToolbar(selectedList.size)
        }
    )
    ```
  </Tab>
</Tabs>

***

## Global Events (CometChatEvents)

Global events are emitted by UI Kit components when actions happen anywhere in the app. They use Kotlin `SharedFlow` for reactive, type-safe event distribution. Subscribe from any coroutine scope.

### Event Flows

| Flow                                 | Sealed Class                 | Fires When                                        |
| ------------------------------------ | ---------------------------- | ------------------------------------------------- |
| `CometChatEvents.messageEvents`      | `CometChatMessageEvent`      | Messages sent, edited, deleted, reactions, typing |
| `CometChatEvents.callEvents`         | `CometChatCallEvent`         | Calls initiated, accepted, rejected, ended        |
| `CometChatEvents.conversationEvents` | `CometChatConversationEvent` | Conversations deleted or updated                  |
| `CometChatEvents.groupEvents`        | `CometChatGroupEvent`        | Groups created, updated, members changed          |
| `CometChatEvents.userEvents`         | `CometChatUserEvent`         | Users blocked/unblocked                           |
| `CometChatEvents.uiEvents`           | `CometChatUIEvent`           | UI-level events (panels, dialogs)                 |

### Subscribing to Events

```kotlin lines theme={null}
import com.cometchat.uikit.core.events.CometChatEvents
import com.cometchat.uikit.core.events.CometChatMessageEvent

// Subscribe in a ViewModel or lifecycle-aware scope
viewModelScope.launch {
    CometChatEvents.messageEvents.collect { event ->
        when (event) {
            is CometChatMessageEvent.MessageSent -> {
                // Handle sent message: event.message, event.status
            }
            is CometChatMessageEvent.MessageDeleted -> {
                // Handle deleted message: event.message
            }
            is CometChatMessageEvent.MessageEdited -> {
                // Handle edited message: event.message
            }
            is CometChatMessageEvent.ReactionAdded -> {
                // Handle reaction: event.event
            }
            else -> { /* other message events */ }
        }
    }
}
```

### Emitting Events

```kotlin lines theme={null}
// Emit from anywhere — thread-safe
CometChatEvents.emitMessageEvent(
    CometChatMessageEvent.MessageSent(message, MessageStatus.SUCCESS)
)

CometChatEvents.emitCallEvent(
    CometChatCallEvent.OutgoingCall(call)
)

CometChatEvents.emitConversationEvent(
    CometChatConversationEvent.ConversationDeleted(conversation)
)
```

### Key Event Types

**Message Events:**

| Event                                | Data                          |
| ------------------------------------ | ----------------------------- |
| `MessageSent`                        | `message`, `status`           |
| `MessageEdited`                      | `message`, `status`           |
| `MessageDeleted`                     | `message`                     |
| `MessageRead`                        | `message`                     |
| `ReactionAdded` / `ReactionRemoved`  | `event` (ReactionEvent)       |
| `TypingStarted` / `TypingEnded`      | `indicator` (TypingIndicator) |
| `MessagesDelivered` / `MessagesRead` | `receipt` (MessageReceipt)    |

**Call Events:**

| Event          | Data   |
| -------------- | ------ |
| `OutgoingCall` | `call` |
| `CallAccepted` | `call` |
| `CallRejected` | `call` |
| `CallEnded`    | `call` |

**Conversation Events:**

| Event                 | Data           |
| --------------------- | -------------- |
| `ConversationDeleted` | `conversation` |
| `ConversationUpdated` | `conversation` |

***

## Component vs Global Events

| Aspect       | Component Callbacks                          | Global Events                           |
| ------------ | -------------------------------------------- | --------------------------------------- |
| Scope        | Single component instance                    | App-wide                                |
| Registration | `setOnItemClick {}` or composable parameter  | `CometChatEvents.*.collect {}`          |
| Use case     | Handle user interaction on a specific screen | Cross-component coordination            |
| Example      | Tap a conversation → navigate                | Message sent → update conversation list |

***

## Related

* [Events Reference](/docs/ui-kit/android/events) — Full list of all event types.
* [Customization Overview](/docs/ui-kit/android/customization-overview) — SDK Listeners vs UIKit Events distinction.


# Menu & Options
Source: https://www.cometchat.com/docs/ui-kit/android/customization-menu-options

Add, replace, or extend context menu actions on components.

Components provide context menus (e.g., long-press on a conversation or message). You can replace all options or append custom ones.

***

## setOptions vs addOptions

| Method       | Behavior                                             |
| ------------ | ---------------------------------------------------- |
| `setOptions` | Replaces all default options with your custom list   |
| `addOptions` | Appends your custom options to the existing defaults |

Use `addOptions` to keep defaults (like "Delete") and add your own. Use `setOptions` for full control.

***

## Adding Custom Options

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.kotlin.presentation.shared.popupmenu.CometChatPopupMenu

    conversations.addOptions { context, conversation ->
        listOf(
            CometChatPopupMenu.MenuItem(
                id = "pin",
                name = "Pin Conversation",
                startIcon = ContextCompat.getDrawable(context, R.drawable.ic_pin),
                onClick = { pinConversation(conversation) }
            )
        )
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.compose.shared.views.popupmenu.MenuItem

    CometChatConversations(
        addOptions = { context, conversation ->
            listOf(
                MenuItem(
                    id = "pin",
                    name = "Pin Conversation",
                    startIcon = painterResource(R.drawable.ic_pin),
                    onClick = { pinConversation(conversation) }
                )
            )
        }
    )
    ```
  </Tab>
</Tabs>

***

## Replacing All Options

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setOptions { context, conversation ->
        listOf(
            CometChatPopupMenu.MenuItem(
                id = "archive",
                name = "Archive",
                startIcon = ContextCompat.getDrawable(context, R.drawable.ic_archive),
                onClick = { archiveConversation(conversation) }
            ),
            CometChatPopupMenu.MenuItem(
                id = "mute",
                name = "Mute",
                startIcon = ContextCompat.getDrawable(context, R.drawable.ic_mute),
                onClick = { muteConversation(conversation) }
            )
        )
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        options = { context, conversation ->
            listOf(
                MenuItem(
                    id = "archive",
                    name = "Archive",
                    startIcon = painterResource(R.drawable.ic_archive),
                    onClick = { archiveConversation(conversation) }
                ),
                MenuItem(
                    id = "mute",
                    name = "Mute",
                    startIcon = painterResource(R.drawable.ic_mute),
                    onClick = { muteConversation(conversation) }
                )
            )
        }
    )
    ```
  </Tab>
</Tabs>

***

## MenuItem Properties

<Tabs>
  <Tab title="Kotlin (XML Views)">
    `CometChatPopupMenu.MenuItem`:

    | Property         | Type            | Description       |
    | ---------------- | --------------- | ----------------- |
    | `id`             | `String`        | Unique identifier |
    | `name`           | `String`        | Display text      |
    | `startIcon`      | `Drawable?`     | Icon at the start |
    | `endIcon`        | `Drawable?`     | Icon at the end   |
    | `startIconTint`  | `@ColorInt Int` | Start icon tint   |
    | `textColor`      | `@ColorInt Int` | Text color        |
    | `textAppearance` | `@StyleRes Int` | Text appearance   |
    | `onClick`        | `(() -> Unit)?` | Click callback    |
  </Tab>

  <Tab title="Jetpack Compose">
    `MenuItem`:

    | Property        | Type            | Description       |
    | --------------- | --------------- | ----------------- |
    | `id`            | `String`        | Unique identifier |
    | `name`          | `String`        | Display text      |
    | `startIcon`     | `Painter?`      | Icon at the start |
    | `endIcon`       | `Painter?`      | Icon at the end   |
    | `startIconTint` | `Color?`        | Start icon tint   |
    | `textColor`     | `Color?`        | Text color        |
    | `textStyle`     | `TextStyle?`    | Text style        |
    | `onClick`       | `(() -> Unit)?` | Click callback    |
  </Tab>
</Tabs>

Both modules provide convenience factory methods:

```kotlin lines theme={null}
// Simple menu item (no icons)
MenuItem.simple(id = "pin", name = "Pin") { /* onClick */ }

// Menu item with icons (Compose)
MenuItem.withIcons(id = "pin", name = "Pin", startIcon = painterResource(R.drawable.ic_pin)) { /* onClick */ }
```

***

## Components with Menu Options

| Component                | Data passed to callback   |
| ------------------------ | ------------------------- |
| `CometChatConversations` | `(Context, Conversation)` |
| `CometChatUsers`         | `(Context, User)`         |
| `CometChatGroups`        | `(Context, Group)`        |
| `CometChatGroupMembers`  | `(Context, GroupMember)`  |
| `CometChatCallLogs`      | `(Context, CallLog)`      |

***

## Related

* [Customization Overview](/docs/ui-kit/android/customization-overview) — See all customization categories.


# Overview
Source: https://www.cometchat.com/docs/ui-kit/android/customization-overview

Understand the layered architecture and discover all customization entry points in the CometChat Android UI Kit.

Every component in the UI Kit follows a layered architecture. Understanding these layers is the key to deep customization without rebuilding components from scratch.

***

## Architecture Layers

Each component is built from four layers, from outermost (UI) to innermost (data):

| Layer      | Role                                                                | Example                                                            |
| ---------- | ------------------------------------------------------------------- | ------------------------------------------------------------------ |
| View       | Renders UI, handles user interaction, exposes setter methods        | `CometChatConversations`, `CometChatMessageList`                   |
| ViewModel  | Manages state, business logic, list operations, and SDK listeners   | `CometChatConversationsViewModel`, `CometChatMessageListViewModel` |
| Repository | Abstracts data fetching — can be swapped for custom implementations | `ConversationsRepository`, `MessageListRepository`                 |
| DataSource | Direct SDK calls — the lowest layer that talks to CometChat servers | `ConversationsDataSourceImpl`, `MessageListDataSourceImpl`         |

```mermaid theme={null}
block-beta
    columns 1
    A["View Layer\nCometChatConversations / Compose\nUI rendering, styles, callbacks"]
    B["ViewModel Layer\nCometChatConversationsViewModel\nState, ListOperations, SDK listeners"]
    C["Repository Layer\nConversationsRepository\nData abstraction — swappable"]
    D["DataSource Layer\nConversationsDataSourceImpl\nDirect CometChat SDK calls"]

    A --> B
    B --> C
    C --> D
```

The ViewModel lives in `chatuikit-core` and is shared by both Kotlin XML Views and Jetpack Compose. The View layer is module-specific.

***

## Overriding the ViewModel

Every component accepts an external ViewModel. This lets you subclass the default ViewModel to override behavior, or provide a completely custom one.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // 1. Subclass the ViewModel to override behavior
    class MyConversationsViewModel(
        getConversationsUseCase: GetConversationsUseCase,
        deleteConversationUseCase: DeleteConversationUseCase,
        refreshConversationsUseCase: RefreshConversationsUseCase
    ) : CometChatConversationsViewModel(
        getConversationsUseCase,
        deleteConversationUseCase,
        refreshConversationsUseCase
    ) {
        // Override any behavior here
    }

    // 2. Create a factory with optional custom repository
    val factory = CometChatConversationsViewModelFactory(
        repository = MyCustomRepository() // or use default
    )

    // 3. Create the ViewModel via ViewModelProvider
    val viewModel = ViewModelProvider(this, factory)
        .get(MyConversationsViewModel::class.java)

    // 4. Inject into the component
    val conversations = findViewById<CometChatConversations>(R.id.conversations)
    conversations.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // 1. Subclass the ViewModel to override behavior
    class MyConversationsViewModel(
        getConversationsUseCase: GetConversationsUseCase,
        deleteConversationUseCase: DeleteConversationUseCase,
        refreshConversationsUseCase: RefreshConversationsUseCase
    ) : CometChatConversationsViewModel(
        getConversationsUseCase,
        deleteConversationUseCase,
        refreshConversationsUseCase
    ) {
        // Override any behavior here
    }

    // 2. Create a factory with optional custom repository
    val factory = CometChatConversationsViewModelFactory(
        repository = MyCustomRepository() // or use default
    )

    // 3. Create and pass to the component
    val viewModel: MyConversationsViewModel = viewModel(factory = factory)

    CometChatConversations(
        conversationsViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

***

## Overriding the Repository

Each ViewModel is created via a Factory that accepts a custom Repository. Implement the repository interface to change how data is fetched.

```kotlin lines theme={null}
// 1. Implement the repository interface
class MyConversationsRepository : ConversationsRepository {
    override suspend fun fetchConversations(request: ConversationsRequest): List<Conversation> {
        // Custom data fetching logic — local DB, filtered API call, etc.
    }
    // ... implement other methods
}

// 2. Create a factory with your custom repository
val factory = CometChatConversationsViewModelFactory(
    repository = MyConversationsRepository()
)

// 3. Create the ViewModel using the factory
val viewModel = ViewModelProvider(this, factory)
    .get(CometChatConversationsViewModel::class.java)

// 4. Set it on the component
conversations.setViewModel(viewModel)
```

Available repository interfaces in `chatuikit-core`:

| Repository                     | Used by                                |
| ------------------------------ | -------------------------------------- |
| `ConversationsRepository`      | `CometChatConversationsViewModel`      |
| `MessageListRepository`        | `CometChatMessageListViewModel`        |
| `MessageComposerRepository`    | `CometChatMessageComposerViewModel`    |
| `MessageHeaderRepository`      | `CometChatMessageHeaderViewModel`      |
| `UsersRepository`              | `CometChatUsersViewModel`              |
| `GroupsRepository`             | `CometChatGroupsViewModel`             |
| `GroupMembersRepository`       | `CometChatGroupMembersViewModel`       |
| `CallLogsRepository`           | `CometChatCallLogsViewModel`           |
| `CallButtonsRepository`        | `CometChatCallButtonsViewModel`        |
| `ReactionListRepository`       | `CometChatReactionListViewModel`       |
| `MessageInformationRepository` | `CometChatMessageInformationViewModel` |
| `StickerRepository`            | `CometChatStickerKeyboardViewModel`    |
| `PollRepository`               | `CometChatCreatePollViewModel`         |

***

## ListOperations API

All list-based ViewModels implement the `ListOperations<T>` interface, giving you a consistent API to manipulate list data programmatically.

### Available Operations

| Method                        | Description                                       |
| ----------------------------- | ------------------------------------------------- |
| `addItem(item)`               | Appends an item to the list                       |
| `addItems(items)`             | Appends multiple items                            |
| `removeItem(item)`            | Removes the first matching item                   |
| `removeItemAt(index)`         | Removes item at index                             |
| `updateItem(item, predicate)` | Replaces the first item matching the predicate    |
| `clearItems()`                | Removes all items                                 |
| `getItems()`                  | Returns a copy of all items                       |
| `getItemAt(index)`            | Returns item at index (or null)                   |
| `getItemCount()`              | Returns the item count                            |
| `moveItemToTop(item)`         | Moves an item to index 0 (or adds it there)       |
| `batch { }`                   | Performs multiple operations in a single emission |

### Example

```kotlin lines theme={null}
// Batch operations — emits only once for all changes
viewModel.batch {
    add(newConversation1)
    add(newConversation2)
    remove(oldConversation)
    moveToTop(pinnedConversation)
}
```

Batch operations are critical for performance when handling rapid updates (e.g., multiple messages arriving simultaneously).

***

## SDK Listeners vs UIKit Events

ViewModels use two event systems for real-time updates:

| Aspect       | SDK Listeners                      | UIKit Events                                       |
| ------------ | ---------------------------------- | -------------------------------------------------- |
| Source       | CometChat server                   | UIKit components                                   |
| Direction    | Server → Client                    | Component → Component                              |
| Registration | `CometChat.add*Listener()`         | `CometChatEvents.*Events.collect {}`               |
| Purpose      | Incoming messages, calls, presence | UI-initiated actions (message sent, call accepted) |

Both are needed for full functionality. SDK listeners handle server-pushed events, UIKit events handle inter-component communication.

***

## Customization Categories

<CardGroup>
  <Card title="View Slots" href="/ui-kit/android/customization-view-slots">
    Replace specific regions of a component's UI (leading view, title, subtitle, trailing view).
  </Card>

  <Card title="Styles" href="/ui-kit/android/customization-styles">
    Customize visual appearance using XML theme attributes or Compose style data classes.
  </Card>

  <Card title="ViewModel & Data" href="/ui-kit/android/customization-viewmodel-data">
    Configure data fetching, observe state flows, and call mutation methods on the ViewModel.
  </Card>

  <Card title="Events & Callbacks" href="/ui-kit/android/customization-events">
    Handle click events, selection mode, and global UI Kit events.
  </Card>

  <Card title="State Views" href="/ui-kit/android/customization-state-views">
    Replace or restyle the default empty, error, and loading state views.
  </Card>

  <Card title="Text Formatters" href="/ui-kit/android/customization-text-formatters">
    Create custom text processors for hashtags, mentions, links, or any pattern.
  </Card>

  <Card title="Menu & Options" href="/ui-kit/android/customization-menu-options">
    Add, replace, or extend context menu actions and composer attachment options.
  </Card>
</CardGroup>

***

## What's Next

Start with [Styles](/docs/ui-kit/android/customization-styles) for quick visual changes, or [ViewModel & Data](/docs/ui-kit/android/customization-viewmodel-data) for behavior customization.


# State Views
Source: https://www.cometchat.com/docs/ui-kit/android/customization-state-views

Replace the default empty, error, and loading state views with custom layouts.

Components display state views when the list is empty, an error occurs, or data is loading. You can replace these with your own custom views.

***

## State Types

| State   | When it shows                          |
| ------- | -------------------------------------- |
| Loading | Data is being fetched                  |
| Empty   | No data to display                     |
| Error   | An error occurred during data fetching |

***

## Replacing State Views

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Each component accepts a `View?` for each state:

    ```kotlin lines theme={null}
    // Custom empty view
    val emptyView = LayoutInflater.from(context)
        .inflate(R.layout.custom_empty_state, null)
    conversations.setEmptyView(emptyView)

    // Custom error view
    val errorView = LayoutInflater.from(context)
        .inflate(R.layout.custom_error_state, null)
    conversations.setErrorView(errorView)

    // Custom loading view
    val loadingView = LayoutInflater.from(context)
        .inflate(R.layout.custom_loading_state, null)
    conversations.setLoadingView(loadingView)
    ```

    Example custom empty layout:

    ```xml res/layout/custom_empty_state.xml lines theme={null}
    <LinearLayout
        xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:gravity="center"
        android:orientation="vertical"
        android:padding="32dp">

        <ImageView
            android:layout_width="120dp"
            android:layout_height="120dp"
            android:src="@drawable/ic_empty_conversations"
            android:contentDescription="No conversations" />

        <TextView
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_marginTop="16dp"
            android:text="No conversations yet"
            android:textSize="18sp" />
    </LinearLayout>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Each component accepts `@Composable` lambdas for each state:

    ```kotlin lines theme={null}
    CometChatConversations(
        emptyView = {
            Column(
                modifier = Modifier.fillMaxSize(),
                horizontalAlignment = Alignment.CenterHorizontally,
                verticalArrangement = Arrangement.Center
            ) {
                Icon(
                    painter = painterResource(R.drawable.ic_empty_conversations),
                    contentDescription = "No conversations",
                    modifier = Modifier.size(120.dp),
                    tint = CometChatTheme.colorScheme.iconTintSecondary
                )
                Spacer(modifier = Modifier.height(16.dp))
                Text(
                    text = "No conversations yet",
                    style = CometChatTheme.typography.heading2Medium,
                    color = CometChatTheme.colorScheme.textColorPrimary
                )
            }
        },
        errorView = { onRetry ->
            Column(
                modifier = Modifier.fillMaxSize(),
                horizontalAlignment = Alignment.CenterHorizontally,
                verticalArrangement = Arrangement.Center
            ) {
                Text("Something went wrong")
                Spacer(modifier = Modifier.height(8.dp))
                Button(onClick = onRetry) {
                    Text("Retry")
                }
            }
        },
        loadingView = {
            Box(
                modifier = Modifier.fillMaxSize(),
                contentAlignment = Alignment.Center
            ) {
                CircularProgressIndicator()
            }
        }
    )
    ```

    Note: the `errorView` lambda receives an `onRetry` callback you can wire to a retry button.
  </Tab>
</Tabs>

***

## Hiding State Views

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Components like `CometChatMessageList` provide explicit hide methods:

    ```kotlin lines theme={null}
    messageList.setHideLoadingState(true)
    messageList.setHideEmptyState(true)
    messageList.setHideErrorState(true)
    ```

    For components that don't have dedicated hide methods (e.g., `CometChatConversations`), pass `null` to remove a custom state view:

    ```kotlin lines theme={null}
    conversations.setEmptyView(null)
    conversations.setErrorView(null)
    conversations.setLoadingView(null)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        hideEmptyState = true,
        hideErrorState = true,
        hideLoadingState = true
    )

    CometChatMessageList(
        hideEmptyState = true,
        hideErrorState = true,
        hideLoadingState = true
    )
    ```
  </Tab>
</Tabs>

***

## Components with State Views

State views are available on all list-based components:

| Component                | States supported      |
| ------------------------ | --------------------- |
| `CometChatConversations` | Loading, Empty, Error |
| `CometChatUsers`         | Loading, Empty, Error |
| `CometChatGroups`        | Loading, Empty, Error |
| `CometChatGroupMembers`  | Loading, Empty, Error |
| `CometChatCallLogs`      | Loading, Empty, Error |
| `CometChatMessageList`   | Loading, Empty, Error |

***

## Related

* [Customization Overview](/docs/ui-kit/android/customization-overview) — See all customization categories.
* [View Slots](/docs/ui-kit/android/customization-view-slots) — Replace specific regions of list items.


# Styles
Source: https://www.cometchat.com/docs/ui-kit/android/customization-styles

Customize component appearance using XML theme attributes, programmatic setters, or Compose style data classes.

The UI Kit supports multiple approaches to styling depending on your module.

***

## Styling Approaches

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Two ways to style components:

    1. **XML theme attributes** — declarative, app-wide theming via `themes.xml`
    2. **Programmatic `CometChatTheme` setters** — runtime color/font overrides

    Programmatic setters take precedence over XML theme attributes.

    ### XML Theme Hierarchy

    ```xml themes.xml lines theme={null}
    <!-- Level 1: Theme-level colors and fonts -->
    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatPrimaryColor">#6851D6</item>
        <item name="cometchatBackgroundColor1">#FFFFFF</item>
        <item name="cometchatFontRegular">@font/my_regular_font</item>
        <item name="cometchatFontMedium">@font/my_medium_font</item>
        <item name="cometchatFontBold">@font/my_bold_font</item>

        <!-- Level 2: Component-level style -->
        <item name="cometchatConversationsStyle">@style/CustomConversationsStyle</item>
    </style>

    <!-- Level 2: Component style with nested sub-component styles -->
    <style name="CustomConversationsStyle" parent="CometChatConversationsStyle">
        <item name="cometchatConversationsAvatarStyle">@style/CustomAvatarStyle</item>
        <item name="cometchatConversationsBadgeStyle">@style/CustomBadgeStyle</item>
    </style>

    <!-- Level 3: Sub-component style -->
    <style name="CustomAvatarStyle" parent="CometChatAvatarStyle">
        <item name="cometchatAvatarStrokeRadius">12dp</item>
        <item name="cometchatAvatarBackgroundColor">#E8E0FF</item>
    </style>
    ```

    ### Programmatic Overrides

    ```kotlin lines theme={null}
    // Override theme colors at runtime
    CometChatTheme.setPrimaryColor(Color.parseColor("#6851D6"))
    CometChatTheme.setBackgroundColor1(Color.parseColor("#FFFFFF"))
    CometChatTheme.setTextColorPrimary(Color.parseColor("#141414"))
    CometChatTheme.setTextColorSecondary(Color.parseColor("#727272"))
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Components accept a `style` parameter — a data class with `.default()` factory and `.copy()` for overrides:

    ```kotlin lines theme={null}
    CometChatConversations(
        style = CometChatConversationsStyle.default().copy(
            backgroundColor = Color(0xFFF5F5F5),
            titleTextColor = Color(0xFF6851D6),
            itemStyle = CometChatConversationsItemStyle.default().copy(
                avatarStyle = CometChatAvatarStyle.default().copy(
                    cornerRadius = 12.dp,
                    backgroundColor = Color(0xFFE8E0FF)
                ),
                badgeStyle = CometChatBadgeStyle.default().copy(
                    backgroundColor = Color(0xFFF76808)
                )
            )
        )
    )
    ```

    Global theme colors are provided via `CometChatTheme`:

    ```kotlin lines theme={null}
    CometChatTheme(
        colorScheme = lightColorScheme().copy(
            primary = Color(0xFF6851D6),
            backgroundColor1 = Color(0xFFFFFFFF),
            textColorPrimary = Color(0xFF141414)
        )
    ) {
        // All components inside use these colors as defaults
    }
    ```
  </Tab>
</Tabs>

***

## Font Customization

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Override fonts at the theme level:

    ```xml themes.xml lines theme={null}
    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatFontBold">@font/my_bold_font</item>
        <item name="cometchatFontMedium">@font/my_medium_font</item>
        <item name="cometchatFontRegular">@font/my_regular_font</item>
    </style>
    ```

    | Attribute              | Usage                                 |
    | ---------------------- | ------------------------------------- |
    | `cometchatFontBold`    | Headings, titles, emphasized text     |
    | `cometchatFontMedium`  | Subtitles, secondary headings         |
    | `cometchatFontRegular` | Body text, descriptions, input fields |
  </Tab>

  <Tab title="Jetpack Compose">
    Provide custom typography via `CometChatTheme`:

    ```kotlin lines theme={null}
    CometChatTheme(
        typography = CometChatTypography(
            titleBold = TextStyle(fontFamily = myFontFamily, fontWeight = FontWeight.Bold, fontSize = 20.sp),
            bodyRegular = TextStyle(fontFamily = myFontFamily, fontWeight = FontWeight.Normal, fontSize = 14.sp),
            caption1Regular = TextStyle(fontFamily = myFontFamily, fontWeight = FontWeight.Normal, fontSize = 12.sp)
        )
    ) {
        // All components use custom typography
    }
    ```
  </Tab>
</Tabs>

***

## CometChatTheme Color Tokens

These tokens are available for programmatic override (Kotlin XML) or via `CometChatColorScheme` (Compose):

### Colors

| Token                                                        | Description                                |
| ------------------------------------------------------------ | ------------------------------------------ |
| `primaryColor`                                               | Brand color for buttons, links, highlights |
| `backgroundColor1` – `backgroundColor4`                      | Background levels                          |
| `textColorPrimary` / `Secondary` / `Tertiary`                | Text colors                                |
| `textColorDisabled` / `White` / `Highlight`                  | Special text colors                        |
| `errorColor` / `successColor` / `warningColor` / `infoColor` | Alert colors                               |
| `strokeColorDefault` / `Light` / `Dark` / `Highlight`        | Border colors                              |

### Icon Tints

| Token                                        | Description        |
| -------------------------------------------- | ------------------ |
| `iconTintPrimary` / `Secondary` / `Tertiary` | Icon tints         |
| `iconTintWhite` / `Highlight`                | Special icon tints |

### Button Colors

| Token                                                       | Description      |
| ----------------------------------------------------------- | ---------------- |
| `primaryButtonBackgroundColor` / `TextColor` / `IconTint`   | Primary button   |
| `secondaryButtonBackgroundColor` / `TextColor` / `IconTint` | Secondary button |

***

## Per-Component Style Properties

Each component has its own style data class with nested sub-component styles. Here's the pattern for key components:

### CometChatConversations

| Property                         | Description              |
| -------------------------------- | ------------------------ |
| `backgroundColor`                | List background          |
| `titleTextColor`                 | Toolbar title color      |
| `searchBoxStyle`                 | Search box styling       |
| `itemStyle.avatarStyle`          | Avatar in each row       |
| `itemStyle.badgeStyle`           | Unread badge             |
| `itemStyle.dateStyle`            | Timestamp                |
| `itemStyle.receiptStyle`         | Read receipts            |
| `itemStyle.statusIndicatorStyle` | Online/offline indicator |
| `itemStyle.typingIndicatorStyle` | Typing indicator         |

### CometChatMessageList

| Property                     | Description                |
| ---------------------------- | -------------------------- |
| `backgroundColor`            | List background            |
| `incomingMessageBubbleStyle` | Incoming bubble appearance |
| `outgoingMessageBubbleStyle` | Outgoing bubble appearance |
| `actionBubbleStyle`          | Group action bubbles       |
| `callActionBubbleStyle`      | Call action bubbles        |

### CometChatMessageComposer

| Property                 | Description                 |
| ------------------------ | --------------------------- |
| `backgroundColor`        | Composer background         |
| `attachmentIconTint`     | Attachment button tint      |
| `voiceRecordingIconTint` | Voice recording button tint |
| `aiIconTint`             | AI button tint              |
| `sendButtonStyle`        | Send button appearance      |

### CometChatMessageHeader

| Property            | Description              |
| ------------------- | ------------------------ |
| `backgroundColor`   | Header background        |
| `titleTextColor`    | User/group name color    |
| `subtitleTextColor` | Status/typing text color |
| `avatarStyle`       | Avatar appearance        |
| `callButtonsStyle`  | Call button appearance   |

***

## Related

* [Theme Introduction](/docs/ui-kit/android/theme-introduction) — Global theming reference.
* [Component Styling](/docs/ui-kit/android/component-styling) — Detailed per-component style examples with screenshots.
* [Color Resources](/docs/ui-kit/android/color-resources) — Default color palette reference.
* [Customization Overview](/docs/ui-kit/android/customization-overview) — All customization categories.


# Text Formatters
Source: https://www.cometchat.com/docs/ui-kit/android/customization-text-formatters

Create custom text processors for hashtags, mentions, links, or any pattern using the CometChatTextFormatter API.

Text formatters let you process message text with tracking characters, suggestion lists, and spannable transformations. Use them to add hashtag detection, custom mentions, link previews, or any text pattern processing.

Both modules have their own `CometChatTextFormatter` class with the same API pattern:

* Kotlin XML: `com.cometchat.uikit.kotlin.shared.formatters.CometChatTextFormatter`
* Jetpack Compose: `com.cometchat.uikit.compose.presentation.shared.formatters.CometChatTextFormatter`

***

## CometChatTextFormatter API

The abstract class takes a `trackingCharacter` that triggers the formatter when typed in the composer (e.g., `@` for mentions, `#` for hashtags).

### Key Override Methods

| Method                                                       | Purpose                                                                                 |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `search(context, queryString)`                               | Called when the user types after the tracking character. Fetch and display suggestions. |
| `onScrollToBottom()`                                         | Called when the user scrolls to the bottom of the suggestion list. Use for pagination.  |
| `prepareLeftMessageBubbleSpan(context, message, spannable)`  | Apply spans to text in incoming message bubbles.                                        |
| `prepareRightMessageBubbleSpan(context, message, spannable)` | Apply spans to text in outgoing message bubbles.                                        |
| `prepareComposerSpan(context, message, spannable)`           | Apply spans to text in the message composer.                                            |
| `prepareConversationSpan(context, message, spannable)`       | Apply spans to the last message preview in the conversation list.                       |
| `handlePreMessageSend(context, message)`                     | Modify a message before it's sent (attach metadata, transform text).                    |
| `onItemClick(context, suggestionItem, user, group)`          | Called when the user selects a suggestion item.                                         |

### Suggestion System

| Method                           | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `setSuggestionItemList(items)`   | Set the list of suggestions to display                 |
| `setShowLoadingIndicator(show)`  | Show/hide a loading spinner in the suggestion dropdown |
| `setDisableSuggestions(disable)` | Disable the suggestion dropdown entirely               |

***

## Example: Custom Hashtag Formatter

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.kotlin.shared.formatters.CometChatTextFormatter
    import com.cometchat.uikit.kotlin.shared.formatters.SuggestionItem

    class HashtagFormatter : CometChatTextFormatter('#') {

        override fun search(context: Context, queryString: String?) {
            val suggestions = fetchHashtags(queryString)
            setSuggestionItemList(suggestions)
        }

        override fun onScrollToBottom() {
            // Load more suggestions
        }

        override fun prepareLeftMessageBubbleSpan(
            context: Context,
            baseMessage: BaseMessage,
            spannable: SpannableStringBuilder
        ): SpannableStringBuilder? {
            applyHashtagSpans(spannable, context)
            return spannable
        }

        override fun prepareRightMessageBubbleSpan(
            context: Context,
            baseMessage: BaseMessage,
            spannable: SpannableStringBuilder
        ): SpannableStringBuilder? {
            applyHashtagSpans(spannable, context)
            return spannable
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.compose.presentation.shared.formatters.CometChatTextFormatter
    import com.cometchat.uikit.compose.presentation.shared.formatters.SuggestionItem

    class HashtagFormatter : CometChatTextFormatter('#') {

        override fun search(context: Context, queryString: String?) {
            val suggestions = fetchHashtags(queryString)
            setSuggestionItemList(suggestions)
        }

        override fun onScrollToBottom() {
            // Load more suggestions
        }

        override fun prepareLeftMessageBubbleSpan(
            context: Context,
            baseMessage: BaseMessage,
            spannable: SpannableStringBuilder
        ): SpannableStringBuilder? {
            applyHashtagSpans(spannable, context)
            return spannable
        }

        override fun prepareRightMessageBubbleSpan(
            context: Context,
            baseMessage: BaseMessage,
            spannable: SpannableStringBuilder
        ): SpannableStringBuilder? {
            applyHashtagSpans(spannable, context)
            return spannable
        }
    }
    ```
  </Tab>
</Tabs>

***

## Registering Formatters

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val hashtagFormatter = HashtagFormatter()
    conversations.setTextFormatters(listOf(hashtagFormatter))

    // Or on message composer / message list
    messageComposer.setTextFormatters(listOf(hashtagFormatter))
    messageList.setTextFormatters(listOf(hashtagFormatter))
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        textFormatters = listOf(HashtagFormatter())
    )

    CometChatMessageComposer(
        textFormatters = listOf(HashtagFormatter())
    )

    CometChatMessageList(
        textFormatters = listOf(HashtagFormatter())
    )
    ```
  </Tab>
</Tabs>

***

## Built-in Formatter: CometChatMentionsFormatter

The UI Kit includes `CometChatMentionsFormatter` as a built-in formatter that handles `@mention` detection, user suggestion lists, and spannable highlighting. It's automatically added to components when mentions are enabled.

Each module has its own implementation:

* Kotlin XML: `com.cometchat.uikit.kotlin.shared.formatters.CometChatMentionsFormatter`
* Jetpack Compose: `com.cometchat.uikit.compose.presentation.shared.formatters.CometChatMentionsFormatter`

See the [Mentions Formatter Guide](/docs/ui-kit/android/mentions-formatter-guide) for details.

***

## Related

* [Mentions Formatter Guide](/docs/ui-kit/android/mentions-formatter-guide) — Built-in mentions formatter reference.
* [Customization Overview](/docs/ui-kit/android/customization-overview) — See all customization categories.


# View Slots
Source: https://www.cometchat.com/docs/ui-kit/android/customization-view-slots

Replace specific regions of a component's UI without rebuilding the entire component.

View Slots let you swap out specific parts of a component's list item — the avatar area, title, subtitle, trailing section, or the entire row — while keeping the rest of the component's behavior intact.

***

## Available View Slots

| Slot           | Region        | Description                          |
| -------------- | ------------- | ------------------------------------ |
| `leadingView`  | Left section  | Replaces the avatar / leading area   |
| `titleView`    | Title text    | Replaces the name / title text       |
| `subtitleView` | Subtitle text | Replaces the last message preview    |
| `trailingView` | Right section | Replaces the timestamp / badge area  |
| `itemView`     | Entire row    | Replaces the entire list item layout |

<Warning>
  When you use `itemView`, all other slot setters are ignored since the entire row is replaced.
</Warning>

***

## How It Works

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Each list-based component defines a `ViewHolderListener` abstract class with two callbacks:

    | Callback                                    | Purpose                                                                   |
    | ------------------------------------------- | ------------------------------------------------------------------------- |
    | `createView(context, binding)`              | Return a `View` for the slot. Called once when the ViewHolder is created. |
    | `bindView(context, createdView, data, ...)` | Bind data to your custom view. Called every time the item is bound.       |

    Pass the listener to the component via `setLeadingView()`, `setTitleView()`, `setSubtitleView()`, `setTrailingView()`, or `setItemView()`.
  </Tab>

  <Tab title="Jetpack Compose">
    Each component accepts `@Composable` lambda parameters for each slot:

    ```kotlin lines theme={null}
    CometChatConversations(
        leadingView = { conversation, typingIndicator -> /* your composable */ },
        titleView = { conversation, typingIndicator -> /* your composable */ },
        subtitleView = { conversation, typingIndicator -> /* your composable */ },
        trailingView = { conversation, typingIndicator -> /* your composable */ },
        itemView = { conversation, typingIndicator -> /* your composable */ }
    )
    ```

    The lambda receives the data model directly — no `createView`/`bindView` split needed.
  </Tab>
</Tabs>

***

## Example: Custom Leading View

Replace the default avatar with a custom view showing the first letter of the conversation name.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setLeadingView(object : ConversationsViewHolderListener() {
        override fun createView(
            context: Context,
            binding: CometchatConversationsListItemsBinding
        ): View {
            return TextView(context).apply {
                layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp)
                gravity = Gravity.CENTER
                textSize = 18f
                setTextColor(Color.WHITE)
            }
        }

        override fun bindView(
            context: Context,
            createdView: View,
            conversation: Conversation,
            typingIndicator: TypingIndicator?,
            holder: RecyclerView.ViewHolder,
            conversations: List<Conversation>,
            position: Int
        ) {
            val textView = createdView as TextView
            val name = conversation.conversationWith?.name ?: ""
            textView.text = name.firstOrNull()?.uppercase() ?: "?"
            textView.background = GradientDrawable().apply {
                shape = GradientDrawable.OVAL
                setColor(Color.parseColor("#6851D6"))
            }
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        leadingView = { conversation, _ ->
            val name = conversation.conversationWith?.name ?: ""
            val initial = name.firstOrNull()?.uppercase() ?: "?"

            Box(
                modifier = Modifier
                    .size(48.dp)
                    .background(Color(0xFF6851D6), CircleShape),
                contentAlignment = Alignment.Center
            ) {
                Text(
                    text = initial,
                    color = Color.White,
                    fontSize = 18.sp
                )
            }
        }
    )
    ```
  </Tab>
</Tabs>

***

## Example: Custom Subtitle View

Show a custom last message format in the subtitle area.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setSubtitleView(object : ConversationsViewHolderListener() {
        override fun createView(
            context: Context,
            binding: CometchatConversationsListItemsBinding
        ): View {
            return TextView(context).apply {
                maxLines = 1
                ellipsize = TextUtils.TruncateAt.END
            }
        }

        override fun bindView(
            context: Context,
            createdView: View,
            conversation: Conversation,
            typingIndicator: TypingIndicator?,
            holder: RecyclerView.ViewHolder,
            conversations: List<Conversation>,
            position: Int
        ) {
            val textView = createdView as TextView
            // Show typing indicator if available
            if (typingIndicator != null) {
                textView.text = "typing..."
                return
            }
            textView.text = when (val msg = conversation.lastMessage) {
                is TextMessage -> msg.text
                is MediaMessage -> "📎 ${msg.attachment?.fileExtension ?: "Media"}"
                else -> "New conversation"
            }
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        subtitleView = { conversation, typingIndicator ->
            val text = if (typingIndicator != null) {
                "typing..."
            } else {
                when (val msg = conversation.lastMessage) {
                    is TextMessage -> msg.text
                    is MediaMessage -> "📎 ${msg.attachment?.fileExtension ?: "Media"}"
                    else -> "New conversation"
                }
            }

            Text(
                text = text,
                maxLines = 1,
                overflow = TextOverflow.Ellipsis,
                style = CometChatTheme.typography.bodyRegular,
                color = CometChatTheme.colorScheme.textColorSecondary
            )
        }
    )
    ```
  </Tab>
</Tabs>

***

## Toolbar Overflow Menu

Inject a custom view into the component's toolbar area. This is separate from list item view slots.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val menuButton = ImageButton(context).apply {
        setImageResource(R.drawable.ic_filter)
        setOnClickListener { /* show filter dialog */ }
    }
    conversations.setOverflowMenu(menuButton)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        overflowMenu = {
            IconButton(onClick = { /* show filter dialog */ }) {
                Icon(
                    painter = painterResource(R.drawable.ic_filter),
                    contentDescription = "Filter"
                )
            }
        }
    )
    ```
  </Tab>
</Tabs>

***

## Components with View Slots

View slots are available on all list-based components:

| Component                | ViewHolderListener (Kotlin XML)   | Composable Lambdas (Compose)               |
| ------------------------ | --------------------------------- | ------------------------------------------ |
| `CometChatConversations` | `ConversationsViewHolderListener` | `(Conversation, TypingIndicator?) -> Unit` |
| `CometChatUsers`         | `UsersViewHolderListener`         | `(User) -> Unit`                           |
| `CometChatGroups`        | `GroupsViewHolderListener`        | `(Group) -> Unit`                          |
| `CometChatGroupMembers`  | `GroupMembersViewHolderListener`  | `(GroupMember) -> Unit`                    |
| `CometChatCallLogs`      | `CallLogsViewHolderListener`      | `(CallLog) -> Unit`                        |
| `CometChatReactionList`  | `ReactionListViewHolderListener`  | `(Reaction) -> Unit`                       |
| `CometChatMessageHeader` | `MessageHeaderViewHolderListener` | `(User?, Group?) -> Unit`                  |

***

## Related

* [Styles](/docs/ui-kit/android/customization-styles) — Customize visual appearance without replacing views.
* [Customization Overview](/docs/ui-kit/android/customization-overview) — See all customization categories.


# ViewModel & Data
Source: https://www.cometchat.com/docs/ui-kit/android/customization-viewmodel-data

Access and configure the ViewModel layer to customize data fetching, state management, and list operations.

Each component's ViewModel lives in `chatuikit-core` and manages data fetching, state transitions, real-time listeners, and list operations via `StateFlow`. The same ViewModel is shared by both Kotlin XML Views and Jetpack Compose modules.

***

## Creating and Providing a ViewModel

By default, each component creates its own ViewModel internally. To customize behavior, create the ViewModel externally using the factory and pass it to the component.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // 1. Create the factory (optionally with a custom repository)
    val factory = CometChatConversationsViewModelFactory()

    // 2. Create the ViewModel using ViewModelProvider
    val viewModel = ViewModelProvider(this, factory)
        .get(CometChatConversationsViewModel::class.java)

    // 3. Configure the ViewModel before passing it
    viewModel.setConversationsRequestBuilder(
        ConversationsRequest.ConversationsRequestBuilder()
            .setLimit(20)
            .withTags(true)
    )

    // 4. Pass it to the component
    val conversations = findViewById<CometChatConversations>(R.id.conversations)
    conversations.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // 1. Create the factory (optionally with a custom repository)
    val factory = CometChatConversationsViewModelFactory()

    // 2. Create the ViewModel using Compose's viewModel()
    val viewModel: CometChatConversationsViewModel = viewModel(factory = factory)

    // 3. Pass it to the component
    CometChatConversations(
        conversationsViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

This pattern applies to all components — `CometChatUsers`, `CometChatGroups`, `CometChatMessageList`, `CometChatCallLogs`, etc. Each has a corresponding factory class.

***

## State Observation

ViewModels expose state via Kotlin `StateFlow` (not LiveData). The key state flows are:

| StateFlow          | Type                                      | Description                                                                   |
| ------------------ | ----------------------------------------- | ----------------------------------------------------------------------------- |
| `uiState`          | `StateFlow<UIState>`                      | Current screen state: `Loading`, `Empty`, `Error(exception)`, `Content(list)` |
| `conversations`    | `StateFlow<List<Conversation>>`           | The current list of conversations                                             |
| `typingIndicators` | `StateFlow<Map<String, TypingIndicator>>` | Active typing indicators by conversation ID                                   |
| `deleteState`      | `StateFlow<DeleteState>`                  | Delete operation state: `Idle`, `InProgress`, `Success`, `Failure(exception)` |
| `playSoundEvent`   | `SharedFlow<Boolean>`                     | Emits when a message sound should play                                        |
| `scrollToTopEvent` | `SharedFlow<Unit>`                        | Emits when the list should scroll to top                                      |

### UIState

```kotlin lines theme={null}
sealed class UIState {
    object Loading : UIState()
    object Empty : UIState()
    data class Error(val exception: CometChatException) : UIState()
    data class Content(val conversations: List<Conversation>) : UIState()
}
```

### Observing State

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Collect in a lifecycle-aware scope
    lifecycleScope.launch {
        repeatOnLifecycle(Lifecycle.State.STARTED) {
            viewModel.uiState.collect { state ->
                when (state) {
                    is UIState.Loading -> { /* show loading */ }
                    is UIState.Empty -> { /* show empty */ }
                    is UIState.Error -> { /* show error: state.exception */ }
                    is UIState.Content -> { /* data ready: state.conversations */ }
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    val uiState by viewModel.uiState.collectAsState()

    when (uiState) {
        is UIState.Loading -> CircularProgressIndicator()
        is UIState.Empty -> Text("No conversations")
        is UIState.Error -> Text("Error: ${(uiState as UIState.Error).exception.message}")
        is UIState.Content -> { /* render list */ }
    }
    ```
  </Tab>
</Tabs>

***

## Configuring Data Fetching

Pass a custom `ConversationsRequestBuilder` to control what data the component fetches. You can set it during ViewModel creation or directly on the component:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Option 1: Set on the component directly
    conversations.setConversationsRequestBuilder(
        ConversationsRequest.ConversationsRequestBuilder()
            .setLimit(20)
            .setTags(listOf("important", "pinned"))
            .withTags(true)
    )

    // Option 2: Set on the ViewModel after creation
    viewModel.setConversationsRequestBuilder(
        ConversationsRequest.ConversationsRequestBuilder()
            .setLimit(20)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        conversationsRequestBuilder = ConversationsRequest.ConversationsRequestBuilder()
            .setLimit(20)
            .setTags(listOf("important", "pinned"))
            .withTags(true)
    )
    ```
  </Tab>
</Tabs>

<Warning>
  Pass the builder object, not the result of `.build()`. The component calls `.build()` internally.
</Warning>

***

## ListOperations API

All list-based ViewModels implement `ListOperations<T>`, giving you a consistent API to manipulate list data:

```kotlin lines theme={null}
// Add items
viewModel.addItem(conversation)
viewModel.addItems(conversations)

// Remove items
viewModel.removeItem(conversation)
viewModel.removeItemAt(0)

// Update items
viewModel.updateItem(updatedConversation) { 
    it.conversationId == updatedConversation.conversationId 
}

// Move to top
viewModel.moveItemToTop(importantConversation)

// Query
val items = viewModel.getItems()
val count = viewModel.getItemCount()
val first = viewModel.getItemAt(0)

// Clear
viewModel.clearItems()
```

### Batch Operations

Perform multiple operations in a single emission — critical for performance with rapid updates:

```kotlin lines theme={null}
viewModel.batch {
    add(newConversation1)
    add(newConversation2)
    remove(oldConversation)
    moveToTop(pinnedConversation)
}
// Only one StateFlow emission for all four operations
```

***

## ViewModel Methods

| Method                                    | Description                                         |
| ----------------------------------------- | --------------------------------------------------- |
| `fetchConversations()`                    | Fetch the next page (pagination)                    |
| `refreshList()`                           | Clear and re-fetch from the server (silent refresh) |
| `deleteConversation(conversation)`        | Delete a conversation via the SDK                   |
| `resetDeleteState()`                      | Reset delete state to `Idle`                        |
| `setConversationsRequestBuilder(builder)` | Set a custom request builder for filtering          |
| `setDisableReceipt(disable)`              | Disable read receipts                               |
| `setDisableSoundForMessages(disable)`     | Disable message sounds                              |
| `setCustomSoundForMessage(rawRes)`        | Set a custom sound resource                         |

***

## Providing a Custom ViewModel

Subclass the ViewModel to override behavior, then inject it:

```kotlin lines theme={null}
class MyConversationsViewModel(
    getConversationsUseCase: GetConversationsUseCase,
    deleteConversationUseCase: DeleteConversationUseCase,
    refreshConversationsUseCase: RefreshConversationsUseCase
) : CometChatConversationsViewModel(
    getConversationsUseCase,
    deleteConversationUseCase,
    refreshConversationsUseCase
) {
    // Override list operations to add custom behavior
    override fun addItem(item: Conversation) {
        // Example: filter out blocked users before adding
        val blockedUser = item.conversationWith as? User
        if (blockedUser?.isBlockedByMe == true) return
        super.addItem(item)
    }

    override fun moveItemToTop(item: Conversation) {
        // Example: log when a conversation is moved to top
        Log.d("MyVM", "Moving ${item.conversationId} to top")
        super.moveItemToTop(item)
    }
}
```

Create it via the factory with a custom repository if needed:

```kotlin lines theme={null}
val factory = CometChatConversationsViewModelFactory(
    repository = MyCustomRepository()
)
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val viewModel = ViewModelProvider(this, factory)
        .get(CometChatConversationsViewModel::class.java)

    conversations.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    val viewModel = viewModel<CometChatConversationsViewModel>(factory = factory)

    CometChatConversations(
        conversationsViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

***

## Lifecycle Callbacks

Intercept data loading events on the View:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    conversations.setOnLoad { list ->
        Log.d("Conversations", "Loaded ${list.size} conversations")
    }

    conversations.setOnEmpty {
        Log.d("Conversations", "No conversations found")
    }

    conversations.setOnError { exception ->
        Log.e("Conversations", "Error: ${exception.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        onLoad = { list ->
            Log.d("Conversations", "Loaded ${list.size} conversations")
        },
        onEmpty = {
            Log.d("Conversations", "No conversations found")
        },
        onError = { exception ->
            Log.e("Conversations", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

***

## Related

* [Customization Overview](/docs/ui-kit/android/customization-overview) — Architecture overview with repository and ListOperations details.
* [Events & Callbacks](/docs/ui-kit/android/customization-events) — Handle click events and global UI Kit events.


# Events
Source: https://www.cometchat.com/docs/ui-kit/android/events

Listen to UI Kit events for user actions, group changes, messages, and call lifecycle updates using CometChatEvents SharedFlow.

<Accordion title="AI Integration Quick Reference">
  | Field              | Value                                                                                                                                                                                        |
  | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Kotlin (XML Views) | `com.cometchat:chatuikit-kotlin-android`                                                                                                                                                     |
  | Jetpack Compose    | `com.cometchat:chatuikit-compose-android`                                                                                                                                                    |
  | Import             | `com.cometchat.uikit.core.events.CometChatEvents`                                                                                                                                            |
  | Event flows        | `CometChatEvents.messageEvents`, `CometChatEvents.callEvents`, `CometChatEvents.conversationEvents`, `CometChatEvents.groupEvents`, `CometChatEvents.userEvents`, `CometChatEvents.uiEvents` |
  | Pattern            | Kotlin `SharedFlow` with sealed class event types — collect in `viewModelScope` or `lifecycleScope`                                                                                          |
  | Purpose            | Decoupled communication between UI Kit components — subscribe to event flows to react to changes without direct component references                                                         |
</Accordion>

Events enable a decoupled, flexible architecture in the CometChat UI Kit. Components emit events via the `CometChatEvents` singleton, and other parts of your application collect these `SharedFlow` streams to react without direct references between components.

## When to use this

* You need to update your UI when a user is blocked or unblocked.
* You need to respond to group actions such as member joins, kicks, bans, or ownership transfers.
* You need to track conversation deletions or updates in real time.
* You need to react to messages being sent, edited, deleted, or read.
* You need to handle call lifecycle events (outgoing, accepted, rejected, ended).
* You need to respond to UI-level events such as panel visibility changes or active chat changes.

## Prerequisites

* The `com.cometchat:chatuikit-kotlin-android` or `com.cometchat:chatuikit-compose-android` dependency added to your project.
* `CometChatUIKit.init()` called and completed successfully.
* A logged-in CometChat user (call `CometChatUIKit.login()` before collecting events).

## CometChatEvents Singleton

All events are accessed through the `CometChatEvents` singleton in `chatuikit-core`. Each domain has a dedicated `SharedFlow` that emits sealed class event types:

```kotlin theme={null}
import com.cometchat.uikit.core.events.CometChatEvents
```

| Flow                                 | Sealed Class        | Description                                    |
| ------------------------------------ | ------------------- | ---------------------------------------------- |
| `CometChatEvents.messageEvents`      | `MessageEvent`      | Message sent, edited, deleted, read, reactions |
| `CometChatEvents.callEvents`         | `CallEvent`         | Call initiated, accepted, rejected, ended      |
| `CometChatEvents.conversationEvents` | `ConversationEvent` | Conversation deleted, updated                  |
| `CometChatEvents.groupEvents`        | `GroupEvent`        | Group created, deleted, member changes         |
| `CometChatEvents.userEvents`         | `UserEvent`         | User blocked, unblocked                        |
| `CometChatEvents.uiEvents`           | `UIEvent`           | Panel visibility, active chat changes          |

## API reference

### Message Events

`CometChatEvents.messageEvents` emits `MessageEvent` sealed class instances when messages are sent, edited, deleted, or read.

**Event types:**

| Event                                             | Description                                                               |
| ------------------------------------------------- | ------------------------------------------------------------------------- |
| `MessageEvent.Sent(message, status)`              | Triggered when a message is sent. Status can be `inProgress` or `sent`.   |
| `MessageEvent.Edited(message, status)`            | Triggered when a message is edited. Status can be `inProgress` or `sent`. |
| `MessageEvent.Deleted(message)`                   | Triggered when a message is deleted.                                      |
| `MessageEvent.Read(message)`                      | Triggered when a message is read.                                         |
| `MessageEvent.LiveReaction(icon)`                 | Triggered when a live reaction is sent.                                   |
| `MessageEvent.FormReceived(message)`              | Triggered when a form message is received.                                |
| `MessageEvent.CardReceived(message)`              | Triggered when a card message is received.                                |
| `MessageEvent.CustomInteractiveReceived(message)` | Triggered when a custom interactive message is received.                  |
| `MessageEvent.InteractionGoalCompleted(message)`  | Triggered when an interaction goal is completed.                          |
| `MessageEvent.SchedulerReceived(message)`         | Triggered when a scheduler message is received.                           |

**Collecting events:**

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    // In an Activity or Fragment — use lifecycleScope
    lifecycleScope.launch {
        CometChatEvents.messageEvents.collect { event ->
            when (event) {
                is MessageEvent.Sent -> {
                    val message = event.message
                    val status = event.status
                    // Update UI when message is sent
                }
                is MessageEvent.Edited -> {
                    val message = event.message
                    // Update UI when message is edited
                }
                is MessageEvent.Deleted -> {
                    val message = event.message
                    // Remove message from UI
                }
                is MessageEvent.Read -> {
                    val message = event.message
                    // Update read receipts
                }
                is MessageEvent.LiveReaction -> {
                    val icon = event.icon
                    // Show live reaction animation
                }
                is MessageEvent.FormReceived -> { /* Handle form message */ }
                is MessageEvent.CardReceived -> { /* Handle card message */ }
                is MessageEvent.CustomInteractiveReceived -> { /* Handle custom interactive */ }
                is MessageEvent.InteractionGoalCompleted -> { /* Handle goal completion */ }
                is MessageEvent.SchedulerReceived -> { /* Handle scheduler message */ }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    @Composable
    fun MessageEventsHandler() {
        LaunchedEffect(Unit) {
            CometChatEvents.messageEvents.collect { event ->
                when (event) {
                    is MessageEvent.Sent -> {
                        val message = event.message
                        val status = event.status
                        // Update UI when message is sent
                    }
                    is MessageEvent.Edited -> {
                        val message = event.message
                        // Update UI when message is edited
                    }
                    is MessageEvent.Deleted -> {
                        val message = event.message
                        // Remove message from UI
                    }
                    is MessageEvent.Read -> {
                        val message = event.message
                        // Update read receipts
                    }
                    is MessageEvent.LiveReaction -> {
                        val icon = event.icon
                        // Show live reaction animation
                    }
                    is MessageEvent.FormReceived -> { /* Handle form message */ }
                    is MessageEvent.CardReceived -> { /* Handle card message */ }
                    is MessageEvent.CustomInteractiveReceived -> { /* Handle custom interactive */ }
                    is MessageEvent.InteractionGoalCompleted -> { /* Handle goal completion */ }
                    is MessageEvent.SchedulerReceived -> { /* Handle scheduler message */ }
                }
            }
        }
    }
    ```
  </Tab>
</Tabs>

> **What this does:** Collects the `messageEvents` SharedFlow and pattern-matches on the sealed class to handle each message lifecycle event.

***

### Call Events

`CometChatEvents.callEvents` emits `CallEvent` sealed class instances for call lifecycle changes.

**Event types:**

| Event                          | Description                                                   |
| ------------------------------ | ------------------------------------------------------------- |
| `CallEvent.OutgoingCall(call)` | Triggered when the logged-in user initiates an outgoing call. |
| `CallEvent.Accepted(call)`     | Triggered when a call is accepted.                            |
| `CallEvent.Rejected(call)`     | Triggered when a call is rejected.                            |
| `CallEvent.Ended(call)`        | Triggered when a call is ended.                               |

**Collecting events:**

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    lifecycleScope.launch {
        CometChatEvents.callEvents.collect { event ->
            when (event) {
                is CallEvent.OutgoingCall -> {
                    val call = event.call
                    // Handle outgoing call initiated
                }
                is CallEvent.Accepted -> {
                    val call = event.call
                    // Handle call accepted
                }
                is CallEvent.Rejected -> {
                    val call = event.call
                    // Handle call rejected
                }
                is CallEvent.Ended -> {
                    val call = event.call
                    // Handle call ended
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    @Composable
    fun CallEventsHandler() {
        LaunchedEffect(Unit) {
            CometChatEvents.callEvents.collect { event ->
                when (event) {
                    is CallEvent.OutgoingCall -> {
                        // Handle outgoing call initiated
                    }
                    is CallEvent.Accepted -> {
                        // Handle call accepted
                    }
                    is CallEvent.Rejected -> {
                        // Handle call rejected
                    }
                    is CallEvent.Ended -> {
                        // Handle call ended
                    }
                }
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

### Conversation Events

`CometChatEvents.conversationEvents` emits `ConversationEvent` sealed class instances when conversations are deleted or updated.

**Event types:**

| Event                                     | Description                                               |
| ----------------------------------------- | --------------------------------------------------------- |
| `ConversationEvent.Deleted(conversation)` | Triggered when the logged-in user deletes a conversation. |
| `ConversationEvent.Updated(conversation)` | Triggered when there is an update in the conversation.    |

**Collecting events:**

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    lifecycleScope.launch {
        CometChatEvents.conversationEvents.collect { event ->
            when (event) {
                is ConversationEvent.Deleted -> {
                    val conversation = event.conversation
                    // Remove conversation from UI
                }
                is ConversationEvent.Updated -> {
                    val conversation = event.conversation
                    // Update conversation in UI
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    @Composable
    fun ConversationEventsHandler() {
        LaunchedEffect(Unit) {
            CometChatEvents.conversationEvents.collect { event ->
                when (event) {
                    is ConversationEvent.Deleted -> {
                        // Remove conversation from UI
                    }
                    is ConversationEvent.Updated -> {
                        // Update conversation in UI
                    }
                }
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

### Group Events

`CometChatEvents.groupEvents` emits `GroupEvent` sealed class instances when the logged-in user performs group-related actions.

**Event types:**

| Event                                                                                                | Description                                        |
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `GroupEvent.Created(group)`                                                                          | Triggered when the logged-in user creates a group. |
| `GroupEvent.Deleted(group)`                                                                          | Triggered when the logged-in user deletes a group. |
| `GroupEvent.Left(actionMessage, leftUser, leftGroup)`                                                | Triggered when the logged-in user leaves a group.  |
| `GroupEvent.MemberScopeChanged(actionMessage, updatedUser, scopeChangedTo, scopeChangedFrom, group)` | Triggered when a member's scope is changed.        |
| `GroupEvent.MemberBanned(actionMessage, bannedUser, bannedBy, bannedFrom)`                           | Triggered when a member is banned from a group.    |
| `GroupEvent.MemberKicked(actionMessage, kickedUser, kickedBy, kickedFrom)`                           | Triggered when a member is kicked from a group.    |
| `GroupEvent.MemberUnBanned(actionMessage, unbannedUser, unBannedBy, unBannedFrom)`                   | Triggered when a member is unbanned from a group.  |
| `GroupEvent.MemberJoined(joinedUser, joinedGroup)`                                                   | Triggered when the logged-in user joins a group.   |
| `GroupEvent.MemberAdded(actionMessages, usersAdded, userAddedIn, addedBy)`                           | Triggered when members are added to a group.       |
| `GroupEvent.OwnershipChanged(group, newOwner)`                                                       | Triggered when group ownership is transferred.     |

**Collecting events:**

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    lifecycleScope.launch {
        CometChatEvents.groupEvents.collect { event ->
            when (event) {
                is GroupEvent.Created -> {
                    val group = event.group
                    // Add new group to UI
                }
                is GroupEvent.Deleted -> {
                    val group = event.group
                    // Remove group from UI
                }
                is GroupEvent.Left -> {
                    val leftUser = event.leftUser
                    val leftGroup = event.leftGroup
                    // Handle user leaving group
                }
                is GroupEvent.MemberScopeChanged -> {
                    val updatedUser = event.updatedUser
                    val newScope = event.scopeChangedTo
                    // Update member scope in UI
                }
                is GroupEvent.MemberBanned -> {
                    val bannedUser = event.bannedUser
                    // Remove banned user from member list
                }
                is GroupEvent.MemberKicked -> {
                    val kickedUser = event.kickedUser
                    // Remove kicked user from member list
                }
                is GroupEvent.MemberUnBanned -> {
                    val unbannedUser = event.unbannedUser
                    // Handle unbanned user
                }
                is GroupEvent.MemberJoined -> {
                    val joinedUser = event.joinedUser
                    // Add user to member list
                }
                is GroupEvent.MemberAdded -> {
                    val usersAdded = event.usersAdded
                    // Add users to member list
                }
                is GroupEvent.OwnershipChanged -> {
                    val newOwner = event.newOwner
                    // Update group owner in UI
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    @Composable
    fun GroupEventsHandler() {
        LaunchedEffect(Unit) {
            CometChatEvents.groupEvents.collect { event ->
                when (event) {
                    is GroupEvent.Created -> { /* Add new group to UI */ }
                    is GroupEvent.Deleted -> { /* Remove group from UI */ }
                    is GroupEvent.Left -> { /* Handle user leaving group */ }
                    is GroupEvent.MemberScopeChanged -> { /* Update member scope */ }
                    is GroupEvent.MemberBanned -> { /* Remove banned user */ }
                    is GroupEvent.MemberKicked -> { /* Remove kicked user */ }
                    is GroupEvent.MemberUnBanned -> { /* Handle unbanned user */ }
                    is GroupEvent.MemberJoined -> { /* Add user to member list */ }
                    is GroupEvent.MemberAdded -> { /* Add users to member list */ }
                    is GroupEvent.OwnershipChanged -> { /* Update group owner */ }
                }
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

### User Events

`CometChatEvents.userEvents` emits `UserEvent` sealed class instances when the logged-in user blocks or unblocks another user.

**Event types:**

| Event                       | Description                                              |
| --------------------------- | -------------------------------------------------------- |
| `UserEvent.Blocked(user)`   | Triggered when the logged-in user blocks another user.   |
| `UserEvent.Unblocked(user)` | Triggered when the logged-in user unblocks another user. |

**Collecting events:**

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    lifecycleScope.launch {
        CometChatEvents.userEvents.collect { event ->
            when (event) {
                is UserEvent.Blocked -> {
                    val user = event.user
                    // Update UI to reflect blocked user
                }
                is UserEvent.Unblocked -> {
                    val user = event.user
                    // Update UI to reflect unblocked user
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    @Composable
    fun UserEventsHandler() {
        LaunchedEffect(Unit) {
            CometChatEvents.userEvents.collect { event ->
                when (event) {
                    is UserEvent.Blocked -> {
                        // Update UI to reflect blocked user
                    }
                    is UserEvent.Unblocked -> {
                        // Update UI to reflect unblocked user
                    }
                }
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

### UI Events

`CometChatEvents.uiEvents` emits `CometChatUIEvent` sealed class instances for UI-level actions such as panel visibility and active chat changes.

**Event types:**

| Event                                                          | Description                                                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CometChatUIEvent.ShowPanel(id, alignment, view)`              | Triggered to show an additional UI panel with custom elements.                                                                                                                                                                                                                                  |
| `CometChatUIEvent.HidePanel(id, alignment)`                    | Triggered to hide a previously shown UI panel.                                                                                                                                                                                                                                                  |
| `CometChatUIEvent.ActiveChatChanged(id, message, user, group)` | Triggered when the active chat changes.                                                                                                                                                                                                                                                         |
| `CometChatUIEvent.OpenChat(user, group)`                       | Triggered to open a chat with a specific user or group.                                                                                                                                                                                                                                         |
| `CometChatUIEvent.CardActionClicked(message, actionEvent)`     | Triggered when a user taps an interactive element (button/link) inside a [card message](/docs/sdk/android/v5/send-message#card-message) (`CardMessage`) or an AI agent card (`AIAssistantMessage`). `actionEvent` is typed `Any`; cast it to `com.cometchat.cards.actions.CometChatCardActionEvent`. |

**Collecting events:**

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    lifecycleScope.launch {
        CometChatEvents.uiEvents.collect { event ->
            when (event) {
                is CometChatUIEvent.ShowPanel -> {
                    val alignment = event.alignment
                    // Show custom UI panel
                }
                is CometChatUIEvent.HidePanel -> {
                    val alignment = event.alignment
                    // Hide custom UI panel
                }
                is CometChatUIEvent.ActiveChatChanged -> {
                    val user = event.user
                    val group = event.group
                    // React to active chat change
                }
                is CometChatUIEvent.OpenChat -> {
                    val user = event.user
                    val group = event.group
                    // Navigate to chat with user or group
                }
                is CometChatUIEvent.CardActionClicked -> {
                    val message = event.message            // CardMessage or AIAssistantMessage
                    val action = event.actionEvent as CometChatCardActionEvent
                    // action.action, action.elementId, action.cardJson
                    // Handle the card / agent-card action tap
                }
                else -> { /* no-op */ }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    @Composable
    fun UIEventsHandler() {
        LaunchedEffect(Unit) {
            CometChatEvents.uiEvents.collect { event ->
                when (event) {
                    is CometChatUIEvent.ShowPanel -> { /* Show custom UI panel */ }
                    is CometChatUIEvent.HidePanel -> { /* Hide custom UI panel */ }
                    is CometChatUIEvent.ActiveChatChanged -> { /* React to active chat change */ }
                    is CometChatUIEvent.OpenChat -> { /* Navigate to chat */ }
                    is CometChatUIEvent.CardActionClicked -> { /* Handle the card agent-card action tap */ }
                    else -> { /* no-op */ }
                }
            }
        }
    }
    ```
  </Tab>
</Tabs>

> **About `CardActionClicked`:** The UI Kit renders card bubbles automatically (`CometChatCardBubble`) and emits this event when a user taps an action inside one — so a single subscriber handles every card action across your app. `event.message` is a `CardMessage` for standalone [card messages](/docs/sdk/android/v5/send-message#card-message) and an `AIAssistantMessage` for cards embedded in AI agent replies. `event.actionEvent` is typed `Any`; import and cast it to `com.cometchat.cards.actions.CometChatCardActionEvent` to read its `action`, `elementId`, and `cardJson`.

***

## Lifecycle Management

Since `SharedFlow` collection is coroutine-based, lifecycle management is handled automatically:

* In XML Views, use `lifecycleScope.launch` — the coroutine is cancelled when the lifecycle owner is destroyed.
* In Jetpack Compose, use `LaunchedEffect` — the coroutine is cancelled when the composable leaves the composition.

No manual `removeListener` calls are needed, unlike the old static listener pattern.

***

## Next steps

<CardGroup>
  <Card title="Methods Reference" icon="code" href="/ui-kit/android/methods">
    UI Kit wrapper methods for initialization, authentication, and sending messages
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/android/conversations">
    Display and manage the conversation list, which reacts to conversation events
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/android/message-list">
    Display messages in a chat, which reacts to message events
  </Card>
</CardGroup>


# Extensions
Source: https://www.cometchat.com/docs/ui-kit/android/extensions

Enable built-in CometChat extensions like reactions, stickers, polls, and link previews from the dashboard.

<Accordion title="AI Integration Quick Reference">
  | Field               | Value                                                                                                                                                                              |
  | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Packages            | `com.cometchat:chatuikit-kotlin-android` (Java), `com.cometchat:chatuikit-kotlin-android` (Kotlin XML), `com.cometchat:chatuikit-compose-android` (Jetpack Compose)                |
  | Required setup      | `CometChatUIKit.init()` then `CometChatUIKit.login()` + Extensions enabled in [CometChat Dashboard](/docs/fundamentals/extensions-overview)                                             |
  | Built-in extensions | Stickers, Polls, Collaborative Whiteboard, Collaborative Document, Message Translation, Link Preview, Thumbnail Generation, Profanity Filter                                       |
  | Key components      | [Message Composer](/docs/ui-kit/android/message-composer) (Stickers, Polls, Whiteboard, Document), [Message List](/docs/ui-kit/android/message-list) (Translation, Link Preview, Thumbnails) |
  | Activation          | Enable each extension from the CometChat Dashboard — UI Kit auto-integrates them, no additional code required                                                                      |
  | Related             | [Core Features](/docs/ui-kit/android/core-features), [AI Features](/docs/ui-kit/android/ai-features), [Extensions Overview](/docs/fundamentals/extensions-overview)                               |
</Accordion>

CometChat’s UI Kit comes with built-in support for a wide variety of extensions that provide additional functionality. These extensions enhance the chatting experience, making it more interactive, secure, and efficient.

Activating any of the extensions in CometChat is a simple process done through your application's dashboard. Refer to our guide for detailed information on [Extensions](/docs/fundamentals/extensions-overview).

Once you have successfully enabled the desired extension in your dashboard, it will be reflected in your CometChat application upon initialization and successful login. Please note that extension features will only be available if they are supported by the CometChat UI Kit.

CometChat’s UI Kit offers built-in support for 8 extensions. This seamless integration makes it easy for you to enhance your chat application with engaging features without any extra coding effort. Just enable the desired extensions from the CometChat Dashboard, and they will be automatically reflected in the relevant components of your application, providing a richer and more engaging experience for your users.

## Built-in Extensions

Here's a guide on how you can enable and integrate these extensions:

### Stickers

The Stickers extension allows users to express their emotions more creatively. It adds a much-needed fun element to the chat by allowing users to send various pre-designed stickers. For a comprehensive understanding and guide on implementing and using the Sticker Extension, refer to our specific guide on the [Sticker Extension](/docs/fundamentals/stickers).

Once you have successfully activated the [Sticker Extension](/docs/fundamentals/stickers) from your CometChat Dashboard, the feature will automatically be incorporated into the [Message Composer](/docs/ui-kit/android/message-composer) component of UI Kits.

<Frame>
  <img />
</Frame>

### Polls

The Polls extension enhances group discussions by allowing users to create polls. Users can ask questions with a predefined list of answers, enabling a quick, organized way to gather group opinions. For a comprehensive understanding and guide on implementing and using the Polls Extension, refer to our specific guide on the [Polls Extension](/docs/fundamentals/polls).

Once you have successfully activated the [Polls Extension](/docs/fundamentals/polls) from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/docs/ui-kit/android/message-composer) component of UI Kits.

<Frame>
  <img />
</Frame>

### Collaborative Whiteboard

The Collaborative Whiteboard extension facilitates real-time collaboration. Users can draw, brainstorm, and share ideas on a shared digital whiteboard. For a comprehensive understanding and guide on implementing and using the Collaborative Whiteboard Extension, refer to our specific guide on the [Collaborative Whiteboard Extension](/docs/ui-kit/android/message-bubble-styling#collaborative-bubble).

Once you have successfully activated the [Collaborative Whiteboard Extension](/docs/fundamentals/collaborative-whiteboard) from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/docs/ui-kit/android/message-composer) component of UI Kits.

<Frame>
  <img />
</Frame>

### Collaborative Document

With the Collaborative Document extension, users can work together on a shared document. This feature is essential for remote teams where document collaboration is a recurring requirement. For a comprehensive understanding and guide on implementing and using the Collaborative Document Extension, refer to our specific guide on the [Collaborative Document Extension](/docs/ui-kit/android/message-bubble-styling#collaborative-bubble).

Once you have successfully activated the [Collaborative Document Extension](/docs/fundamentals/collaborative-document) from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/docs/ui-kit/android/message-composer) component of UI Kits.

<Frame>
  <img />
</Frame>

### Message Translation

The Message Translation extension in CometChat is designed to translate any message into your local locale. It eliminates language barriers, making the chat more inclusive. For a comprehensive understanding and guide on implementing and using the Message Translation Extension, refer to our specific guide on the [Message Translation Extension](/docs/fundamentals/message-translation).

Once you have successfully activated the [Message Translation Extension](/docs/fundamentals/message-translation) from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of [MessageList Component](/docs/ui-kit/android/message-list) component of UI Kits.

<Frame>
  <img />
</Frame>

### Link Preview

The Link Preview extension provides a summary of the URL shared in the chat. It includes the title, a description, and a thumbnail image from the web page. For a comprehensive understanding and guide on implementing and using the Link Preview Extension, refer to our specific guide on the [Link Preview Extension](/docs/fundamentals/link-preview).

Once you have successfully activated the [Link Preview Extension](/docs/fundamentals/link-preview) from your CometChat Dashboard, the feature will automatically be incorporated into the Message Bubble of [MessageList Component](/docs/ui-kit/android/message-list) component of UI Kits.

<Frame>
  <img />
</Frame>

### Thumbnail Generation

The Thumbnail Generation extension automatically creates a smaller preview image whenever a larger image is shared, helping to reduce the upload/download time and bandwidth usage. For a comprehensive understanding and guide on implementing and using the Thumbnail Generation Extension, refer to our specific guide on the [Thumbnail Generation Extension](/docs/fundamentals/thumbnail-generation).

Once you have successfully activated the [Thumbnail Generation Extension](/docs/fundamentals/thumbnail-generation) from your CometChat Dashboard, the feature will automatically be incorporated into the Message Bubble of [MessageList Component](/docs/ui-kit/android/message-list) component of UI Kits.

<Frame>
  <img />
</Frame>

### Profanity Filter

The Profanity Filter extension helps in maintaining the chat decorum by censoring obscene and inappropriate words in the messages. For a comprehensive understanding and guide on implementing and using the Profanity Filter Extension, refer to our specific guide on the [Legacy Extensions](https://assets.cometchat.io/legacy-docs/moderation/legacy-extensions.html).

Once you have successfully activated the Profanity Filter Extension from your CometChat Dashboard, the feature will automatically be incorporated into the Message Bubble of [MessageList Component](/docs/ui-kit/android/message-list) component of UI Kits.


# Getting Started With CometChat Android UI Kit
Source: https://www.cometchat.com/docs/ui-kit/android/getting-started

Install, configure, and launch the CometChat Android UI Kit in your app — choose Kotlin (XML Views) or Jetpack Compose.

<Accordion title="AI Integration Quick Reference">
  | Field              | Value                                                                                   |
  | ------------------ | --------------------------------------------------------------------------------------- |
  | Kotlin (XML Views) | `com.cometchat:chatuikit-kotlin-android` v6.x                                           |
  | Jetpack Compose    | `com.cometchat:chatuikit-compose-android` v6.x                                          |
  | Init               | `CometChatUIKit.init(context, UIKitSettings, callback)` — must resolve before `login()` |
  | Login              | `CometChatUIKit.login("UID", callback)` — must resolve before rendering components      |
  | Order              | `init()` → `login()` → render. Breaking this order = blank screen                       |
  | Auth Key           | Dev/testing only. Use Auth Token in production                                          |
  | Theme              | Set `CometChatTheme.DayNight` as parent theme in `themes.xml`                           |
  | Calling            | Optional. Add `com.cometchat:calls-sdk-android` to enable voice/video                   |
  | Min SDK            | Android 9.0 (API 28)                                                                    |
</Accordion>

This guide walks you through adding CometChat to an Android app. By the end you'll have a working chat UI.

<Frame>
  <img />
</Frame>

***

## Prerequisites

You need three things from the [CometChat Dashboard](https://app.cometchat.com/):

| Credential | Where to find it                                           |
| ---------- | ---------------------------------------------------------- |
| App ID     | Dashboard → Your App → Credentials                         |
| Auth Key   | Dashboard → Your App → Credentials                         |
| Region     | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) |

You also need:

* Android Studio installed
* An Android emulator or physical device running Android 9.0 (API 28) or higher
* Java 8 or higher
* Gradle plugin 4.0.1 or later

<Warning>
  Auth Key is for development only. In production, generate Auth Tokens server-side via the [REST API](https://api-explorer.cometchat.com/) and use [`loginWithAuthToken()`](/docs/ui-kit/android/methods#login-using-auth-token). Never ship Auth Keys in client code.
</Warning>

***

## Step 1 — Create an Android Project

1. Open Android Studio and start a new project.
2. Choose Empty Activity as the project template.
3. Enter a project name and choose Kotlin as the language.
4. Set minimum API level to 24 or higher.

***

## Step 2 — Install Dependencies

Add the CometChat repository and dependencies to your Gradle configuration.

### Add the CometChat Repository

Add the CometChat Maven repository to your project-level `settings.gradle.kts` file:

```kotlin settings.gradle.kts theme={null}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
    }
}
```

### Add the CometChat Dependency

Choose the module that matches your UI toolkit:

<Tabs>
  <Tab title="Version Catalog (libs.versions.toml)">
    Inside `libs.versions.toml`, add the versions:

    ```toml libs.versions.toml theme={null}
    [versions]
    cometchat-ui-kit = "6.0.3"
    cometchat-calls-sdk = "5.0.1"
    ```

    Define the libraries — pick the module for your UI toolkit:

    <Tabs>
      <Tab title="Kotlin (XML Views)">
        ```toml libs.versions.toml theme={null}
        [libraries]
        cometchat-ui-kit = { module = "com.cometchat:chatuikit-kotlin-android", version.ref = "cometchat-ui-kit" }
        cometchat-calls-sdk = { module = "com.cometchat:calls-sdk-android", version.ref = "cometchat-calls-sdk" }
        ```
      </Tab>

      <Tab title="Jetpack Compose">
        ```toml libs.versions.toml theme={null}
        [libraries]
        cometchat-ui-kit = { module = "com.cometchat:chatuikit-compose-android", version.ref = "cometchat-ui-kit" }
        cometchat-calls-sdk = { module = "com.cometchat:calls-sdk-android", version.ref = "cometchat-calls-sdk" }
        ```
      </Tab>
    </Tabs>

    Now, in your app-level `build.gradle.kts` file:

    ```kotlin build.gradle.kts theme={null}
    dependencies {
        implementation(libs.cometchat.ui.kit)

        // (Optional) Include if using voice/video calling features
        implementation(libs.cometchat.calls.sdk)
    }
    ```
  </Tab>

  <Tab title="Gradle (build.gradle.kts)">
    Open the app-level `build.gradle.kts` file and add the dependency for your chosen UI toolkit:

    <Tabs>
      <Tab title="Kotlin (XML Views)">
        ```kotlin build.gradle.kts theme={null}
        dependencies {
            implementation("com.cometchat:chatuikit-kotlin-android:6.0.3")

            // (Optional) Include if using voice/video calling features
            implementation("com.cometchat:calls-sdk-android:5.0.1")
        }
        ```
      </Tab>

      <Tab title="Jetpack Compose">
        ```kotlin build.gradle.kts theme={null}
        dependencies {
            implementation("com.cometchat:chatuikit-compose-android:6.0.3")

            // (Optional) Include if using voice/video calling features
            implementation("com.cometchat:calls-sdk-android:5.0.1")
        }
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

### Add AndroidX Support

The Jetifier tool helps migrate legacy support libraries to AndroidX. Open `gradle.properties` and verify this line is present:

```properties gradle.properties theme={null}
android.enableJetifier=true
```

***

## Choose Your UI Toolkit

The remaining integration steps (initialization, login, theming, and rendering components) differ depending on your chosen UI toolkit. Follow the guide that matches your project:

<CardGroup>
  <Card title="Kotlin (XML Views)" icon="code" href="/ui-kit/android/getting-started-kotlin">
    Step-by-step integration using `chatuikit-kotlin` with XML layouts and ViewBinding
  </Card>

  <Card title="Jetpack Compose" icon="wand-magic-sparkles" href="/ui-kit/android/getting-started-jetpack">
    Step-by-step integration using `chatuikit-jetpack` with Composables
  </Card>
</CardGroup>

***

## Build Your Own Chat Experience

Need full control over the UI? Use individual components, customize themes, and wire up your own layouts.

<CardGroup>
  <Card title="Sample App" icon="code" href="https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin">
    Working reference app to compare against
  </Card>

  <Card title="Components" icon="grid-2" href="/ui-kit/android/components-overview">
    All prebuilt UI elements with customization options
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/android/core-features">
    Messaging, real-time updates, and other capabilities
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/android/theme-introduction">
    Colors, fonts, dark mode, and custom styling
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/android/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/android/theme-introduction">
    Customize colors, fonts, and styles
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/android/core-features">
    Chat features included out of the box
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/android/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Getting Started With Jetpack Compose UI Kit
Source: https://www.cometchat.com/docs/ui-kit/android/getting-started-jetpack

Step-by-step guide to integrate the CometChat Jetpack Compose UI Kit into your Android app.

<Accordion title="AI Integration Quick Reference">
  | Field    | Value                                                                                   |
  | -------- | --------------------------------------------------------------------------------------- |
  | Package  | `com.cometchat:chatuikit-compose-android`                                               |
  | UI Layer | Jetpack Compose (Material 3)                                                            |
  | Init     | `CometChatUIKit.init(context, UIKitSettings, callback)` — must resolve before `login()` |
  | Login    | `CometChatUIKit.login("UID", callback)` — must resolve before rendering components      |
  | Order    | `init()` → `login()` → render. Breaking this order = blank screen                       |
  | Auth Key | Dev/testing only. Use Auth Token in production                                          |
  | Calling  | Optional. Add `com.cometchat:calls-sdk-android` to enable voice/video                   |
  | Min SDK  | Android 9.0 (API 28)                                                                    |
</Accordion>

This guide walks you through integrating the CometChat Jetpack Compose UI Kit into an Android app. All UI components are native Compose composables built with Material 3. By the end you'll have a working chat UI.

***

## Prerequisites

You need three things from the [CometChat Dashboard](https://app.cometchat.com/):

| Credential | Where to find it                                           |
| ---------- | ---------------------------------------------------------- |
| App ID     | Dashboard → Your App → Credentials                         |
| Auth Key   | Dashboard → Your App → Credentials                         |
| Region     | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) |

You also need:

* Android Studio (Hedgehog or later recommended)
* An Android emulator or physical device running Android 9.0 (API 28) or higher
* Kotlin configured with Compose compiler plugin
* Gradle plugin 8.0+ with Kotlin DSL

<Warning>
  Auth Key is for development only. In production, generate Auth Tokens server-side via the [REST API](https://api-explorer.cometchat.com/) and use `loginWithAuthToken()`. Never ship Auth Keys in client code.
</Warning>

***

## Step 1 — Create an Android Project

1. Open Android Studio and start a new project.
2. Choose Empty Activity (Compose) as the project template.
3. Set minimum API level to 28 or higher.

***

## Step 2 — Install Dependencies

### Add the CometChat Repository

Add the CometChat Maven repository to your `settings.gradle.kts`:

```kotlin settings.gradle.kts lines theme={null}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
    }
}
```

### Add Dependencies

Open your app-level `build.gradle.kts` and enable Compose, then add the dependencies:

```kotlin build.gradle.kts lines theme={null}
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
}

android {
    // ...
    buildFeatures {
        compose = true
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
    kotlinOptions {
        jvmTarget = "11"
    }
}

dependencies {
    // CometChat Jetpack Compose UI Kit
    implementation("com.cometchat:chatuikit-compose-android:6.0.3")

    // (Optional) Voice/video calling
    implementation("com.cometchat:calls-sdk-android:5.0.1")
}
```

***

## Step 3 — Initialize and Login

Create your `MainActivity.kt` with the CometChat initialization and login flow. Since Compose uses a declarative approach, we track the auth state and render UI conditionally:

```kotlin MainActivity.kt lines theme={null}
import android.os.Bundle
import android.util.Log
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.Text
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import com.cometchat.chat.core.CometChat
import com.cometchat.chat.exceptions.CometChatException
import com.cometchat.chat.models.User
import com.cometchat.uikit.core.CometChatUIKit
import com.cometchat.uikit.core.UIKitSettings

class MainActivity : ComponentActivity() {

    private val TAG = "MainActivity"

    private val appID = "APP_ID"       // Replace with your App ID
    private val region = "REGION"      // Replace with your App Region
    private val authKey = "AUTH_KEY"   // Replace with your Auth Key

    private var isReady by mutableStateOf(false)
    private var error by mutableStateOf<String?>(null)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()

        val uiKitSettings = UIKitSettings.UIKitSettingsBuilder()
            .setRegion(region)
            .setAppId(appID)
            .setAuthKey(authKey)
            .subscribePresenceForAllUsers()
            .build()

        CometChatUIKit.init(this, uiKitSettings, object : CometChat.CallbackListener<String?>() {
            override fun onSuccess(s: String?) {
                Log.d(TAG, "Initialization completed successfully")
                loginUser()
            }

            override fun onError(e: CometChatException?) {
                error = "Init failed: ${e?.message}"
            }
        })

        setContent {
            when {
                error != null -> {
                    Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                        Text(error ?: "Unknown error")
                    }
                }
                !isReady -> {
                    Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                        CircularProgressIndicator()
                    }
                }
                else -> {
                    ChatApp()
                }
            }
        }
    }

    private fun loginUser() {
        CometChatUIKit.login("cometchat-uid-1", object : CometChat.CallbackListener<User>() {
            override fun onSuccess(user: User) {
                Log.d(TAG, "Login successful: ${user.uid}")
                isReady = true
            }

            override fun onError(e: CometChatException) {
                error = "Login failed: ${e.message}"
            }
        })
    }
}
```

<Warning>
  `init()` must resolve before you call `login()`. Calling `login()` before init completes will fail silently.
</Warning>

***

## Step 4 — Choose a Chat Experience

Integrate a conversation view that suits your app's UX. Each option below includes a step-by-step guide.

### Conversation List + Message View

Sequential navigation — conversation list as the entry point, tap a conversation to open a full-screen message view.

<Card title="Build Conversation List + Message View" href="/ui-kit/android/conversation-message-view" icon="comments">
  Step-by-step guide to build this layout with Jetpack Compose
</Card>

***

### One-to-One / Group Chat

Single chat window — no sidebar. Loads a specific user or group chat directly. Ideal for support chat, direct messages, or notification-driven flows.

<Card title="Build One-to-One / Group Chat" href="/ui-kit/android/one-to-one-chat" icon="message">
  Step-by-step guide to build this layout
</Card>

***

### Tab-Based Chat

Bottom navigation with tabs for Chats, Calls, Users, and Settings.

<Card title="Build Tab-Based Chat" href="/ui-kit/android/tab-based-chat" icon="table-columns">
  Step-by-step guide to build this layout
</Card>

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/android/components-overview">
    Browse all available UI Kit components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/android/theme-introduction">
    Customize colors, fonts, and styles
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/android/core-features">
    Chat features included out of the box
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/android/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Getting Started With Kotlin UI Kit
Source: https://www.cometchat.com/docs/ui-kit/android/getting-started-kotlin

Step-by-step guide to integrate the CometChat Kotlin UI Kit with XML Views into your Android app.

<Accordion title="AI Integration Quick Reference">
  | Field    | Value                                                                                   |
  | -------- | --------------------------------------------------------------------------------------- |
  | Package  | `com.cometchat:chatuikit-kotlin-android`                                                |
  | UI Layer | Kotlin + XML Views (View Binding)                                                       |
  | Init     | `CometChatUIKit.init(context, UIKitSettings, callback)` — must resolve before `login()` |
  | Login    | `CometChatUIKit.login("UID", callback)` — must resolve before rendering components      |
  | Order    | `init()` → `login()` → render. Breaking this order = blank screen                       |
  | Auth Key | Dev/testing only. Use Auth Token in production                                          |
  | Calling  | Optional. Add `com.cometchat:calls-sdk-android` to enable voice/video                   |
  | Min SDK  | Android 9.0 (API 28)                                                                    |
</Accordion>

This guide walks you through integrating the CometChat Kotlin UI Kit into an Android app using XML Views and View Binding. By the end you'll have a working chat UI.

***

## Prerequisites

You need three things from the [CometChat Dashboard](https://app.cometchat.com/):

| Credential | Where to find it                                           |
| ---------- | ---------------------------------------------------------- |
| App ID     | Dashboard → Your App → Credentials                         |
| Auth Key   | Dashboard → Your App → Credentials                         |
| Region     | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) |

You also need:

* Android Studio installed
* An Android emulator or physical device running Android 9.0 (API 28) or higher
* Kotlin configured in your project
* Gradle plugin 8.0+ with Kotlin DSL

<Warning>
  Auth Key is for development only. In production, generate Auth Tokens server-side via the [REST API](https://api-explorer.cometchat.com/) and use `loginWithAuthToken()`. Never ship Auth Keys in client code.
</Warning>

***

## Step 1 — Create an Android Project

1. Open Android Studio and start a new project.
2. Choose Empty Activity as the project template.
3. Select Kotlin as the language.
4. Set minimum API level to 28 or higher.

***

## Step 2 — Install Dependencies

### Add the CometChat Repository

Add the CometChat Maven repository to your `settings.gradle.kts`:

```kotlin settings.gradle.kts lines theme={null}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
    }
}
```

### Add Dependencies

Open your app-level `build.gradle.kts` and enable View Binding, then add the dependencies:

```kotlin build.gradle.kts lines theme={null}
android {
    // ...
    buildFeatures {
        viewBinding = true
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
    kotlinOptions {
        jvmTarget = "11"
    }
}

dependencies {
    // CometChat Kotlin UI Kit
    implementation("com.cometchat:chatuikit-kotlin-android:6.0.3")

    // (Optional) Voice/video calling
    implementation("com.cometchat:calls-sdk-android:5.0.1")
}
```

### Add AndroidX Support

Verify this line is present in `gradle.properties`:

```properties gradle.properties lines theme={null}
android.enableJetifier=true
```

***

## Step 3 — Initialize and Login

Create your `MainActivity.kt` with the CometChat initialization and login flow:

```kotlin MainActivity.kt lines theme={null}
import android.os.Bundle
import android.util.Log
import androidx.activity.enableEdgeToEdge
import androidx.appcompat.app.AppCompatActivity
import com.cometchat.chat.core.CometChat
import com.cometchat.chat.exceptions.CometChatException
import com.cometchat.chat.models.User
import com.cometchat.uikit.core.CometChatUIKit
import com.cometchat.uikit.core.UIKitSettings

class MainActivity : AppCompatActivity() {

    private val TAG = "MainActivity"

    private val appID = "APP_ID"       // Replace with your App ID
    private val region = "REGION"      // Replace with your App Region
    private val authKey = "AUTH_KEY"   // Replace with your Auth Key

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()

        val uiKitSettings = UIKitSettings.UIKitSettingsBuilder()
            .setRegion(region)
            .setAppId(appID)
            .setAuthKey(authKey)
            .subscribePresenceForAllUsers()
            .build()

        CometChatUIKit.init(this, uiKitSettings, object : CometChat.CallbackListener<String?>() {
            override fun onSuccess(s: String?) {
                Log.d(TAG, "Initialization completed successfully")
                loginUser()
            }

            override fun onError(e: CometChatException?) {
                Log.e(TAG, "Initialization failed: ${e?.message}")
            }
        })
    }

    private fun loginUser() {
        CometChatUIKit.login("cometchat-uid-1", object : CometChat.CallbackListener<User>() {
            override fun onSuccess(user: User) {
                Log.d(TAG, "Login successful: ${user.uid}")

                // Navigate to your chat screen after login
                // startActivity(Intent(this@MainActivity, ConversationActivity::class.java))
            }

            override fun onError(e: CometChatException) {
                Log.e(TAG, "Login failed: ${e.message}")
            }
        })
    }
}
```

<Warning>
  `init()` must resolve before you call `login()`. Calling `login()` before init completes will fail silently.
</Warning>

***

## Step 4 — Choose a Chat Experience

Integrate a conversation view that suits your app's UX. Each option below includes a step-by-step guide.

### Conversation List + Message View

Sequential navigation — conversation list as the entry point, tap a conversation to open a full-screen message view.

<Card title="Build Conversation List + Message View" href="/ui-kit/android/conversation-message-view" icon="comments">
  Step-by-step guide to build this layout with Kotlin XML Views
</Card>

***

### One-to-One / Group Chat

Single chat window — no sidebar. Loads a specific user or group chat directly. Ideal for support chat, direct messages, or notification-driven flows.

<Card title="Build One-to-One / Group Chat" href="/ui-kit/android/one-to-one-chat" icon="message">
  Step-by-step guide to build this layout
</Card>

***

### Tab-Based Chat

Bottom navigation with tabs for Chats, Calls, Users, and Settings.

<Card title="Build Tab-Based Chat" href="/ui-kit/android/tab-based-chat" icon="table-columns">
  Step-by-step guide to build this layout
</Card>

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/android/components-overview">
    Browse all available UI Kit components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/android/theme-introduction">
    Customize colors, fonts, and styles
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/android/core-features">
    Chat features included out of the box
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/android/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Group Members
Source: https://www.cometchat.com/docs/ui-kit/android/group-members

Scrollable list of all members in a group with search, avatars, names, scope badges, and online/offline status.

`CometChatGroupMembers` renders a scrollable list of all members in a specific group with real-time updates for membership changes, search, avatars, scope badges, and online/offline status indicators. Requires a `Group` object to load data.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatGroupMembers` is a list component. It renders all members of a given group and emits the selected `GroupMember` via `onItemClick`. Use it inside a group detail screen or as a standalone member browser.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_group_members.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.groupmembers.ui.CometChatGroupMembers
        android:id="@+id/group_members"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    ```kotlin lines theme={null}
    val groupMembers = findViewById<CometChatGroupMembers>(R.id.group_members)
    groupMembers.setGroup(group)

    groupMembers.setOnItemClick { groupMember ->
        // Navigate to member profile or start DM
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        modifier = Modifier.fillMaxSize(),
        onItemClick = { groupMember ->
            // Navigate to member profile or start DM
        }
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add to your layout XML:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.groupmembers.ui.CometChatGroupMembers
        android:id="@+id/group_members"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    Then set the group in your Activity:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_group_members)

        val groupMembers = findViewById<CometChatGroupMembers>(R.id.group_members)
        groupMembers.setGroup(group) // Required — must be called before data loads
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    @Composable
    fun GroupMembersScreen(group: Group) {
        CometChatGroupMembers(
            group = group,
            modifier = Modifier.fillMaxSize()
        )
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

Or in a Fragment:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
        val view = CometChatGroupMembers(requireContext())
        view.setGroup(group)
        return view
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
        return ComposeView(requireContext()).apply {
            setContent { CometChatGroupMembers(group = group) }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Filtering Group Members

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Pass a `GroupMembersRequest.GroupMembersRequestBuilder` to control what loads:

    ```kotlin lines theme={null}
    groupMembers.setGroupMembersRequestBuilder(
        GroupMembersRequest.GroupMembersRequestBuilder(group.guid)
            .setLimit(20)
            .setScopes(listOf("admin", "moderator"))
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        groupMembersRequestBuilder = GroupMembersRequest.GroupMembersRequestBuilder(group.guid)
            .setLimit(20)
            .setScopes(listOf("admin", "moderator"))
    )
    ```
  </Tab>
</Tabs>

### Filter Recipes

| Recipe            | Builder method                             |
| ----------------- | ------------------------------------------ |
| Limit per page    | `.setLimit(10)`                            |
| Search by keyword | `.setSearchKeyword("john")`                |
| Filter by scopes  | `.setScopes(listOf("admin", "moderator"))` |

<Warning>
  Pass the builder object, not the result of `.build()`. The component calls `.build()` internally. Default page size is 30 with infinite scroll.
</Warning>

***

## Actions and Events

### Callback Methods

#### `onItemClick`

Fires when a member row is tapped. Primary navigation hook.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setOnItemClick { groupMember ->
        // Navigate to member profile
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        onItemClick = { groupMember ->
            // Navigate to member profile
        }
    )
    ```
  </Tab>
</Tabs>

> Replaces the default item-click behavior. Your custom lambda executes instead of the built-in navigation.

#### `onItemLongClick`

Fires when a member row is long-pressed. Use for additional actions like kick or ban.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setOnItemLongClick { groupMember ->
        // Show context menu
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        onItemLongClick = { groupMember ->
            // Show context menu
        }
    )
    ```
  </Tab>
</Tabs>

#### `onBackPress`

Fires when the user presses the back button in the toolbar.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setOnBackPress {
        finish()
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        onBackPress = { /* navigate back */ }
    )
    ```
  </Tab>
</Tabs>

#### `onSearchClick`

Fires when the user taps the search icon in the toolbar.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setOnSearchClick {
        // Open search screen
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        onSearchClick = { /* open search */ }
    )
    ```
  </Tab>
</Tabs>

#### `onSelection`

Fires when members are selected/deselected in multi-select mode.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE)
    groupMembers.setOnSelection { selectedMembers ->
        updateToolbar(selectedMembers.size)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        selectionMode = UIKitConstants.SelectionMode.MULTIPLE,
        onSelection = { selectedMembers ->
            updateToolbar(selectedMembers.size)
        }
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setOnError { exception ->
        Log.e("GroupMembers", "Error: ${exception.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        onError = { exception ->
            Log.e("GroupMembers", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched and loaded.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setOnLoad { memberList ->
        Log.d("GroupMembers", "Loaded ${memberList.size}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        onLoad = { memberList ->
            Log.d("GroupMembers", "Loaded ${memberList.size}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setOnEmpty {
        Log.d("GroupMembers", "No members found")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        onEmpty = { /* no members */ }
    )
    ```
  </Tab>
</Tabs>

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

| SDK Listener                | Internal behavior                |
| --------------------------- | -------------------------------- |
| `onGroupMemberJoined`       | Adds the new member to the list  |
| `onGroupMemberLeft`         | Removes the member from the list |
| `onGroupMemberKicked`       | Removes the kicked member        |
| `onGroupMemberBanned`       | Removes the banned member        |
| `onGroupMemberUnbanned`     | Updates the member list          |
| `onGroupMemberScopeChanged` | Updates the member's scope badge |
| `onMemberAddedToGroup`      | Adds new members to the list     |

***

## Functionality

| Method (Kotlin XML)                   | Compose Parameter                   | Description                                  |
| ------------------------------------- | ----------------------------------- | -------------------------------------------- |
| `setGroup(group)`                     | `group = group`                     | Set the group to load members for (required) |
| `setBackIconVisibility(View.VISIBLE)` | `hideBackIcon = false`              | Toggle back button                           |
| `setToolbarVisibility(View.GONE)`     | `hideToolbar = true`                | Toggle toolbar                               |
| `setSearchBoxVisibility(View.GONE)`   | `hideSearchBox = true`              | Toggle search box                            |
| `setSeparatorVisibility(View.GONE)`   | `hideSeparator = true`              | Toggle list separators                       |
| `setSelectionMode(MULTIPLE)`          | `selectionMode = MULTIPLE`          | Enable selection mode                        |
| `setTitle("Members")`                 | `title = "Members"`                 | Custom toolbar title                         |
| `setSearchPlaceholderText("Find...")` | `searchPlaceholderText = "Find..."` | Search placeholder                           |

***

## Custom View Slots

### Leading View

Replace the avatar / left section.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setLeadingView(object : GroupMembersViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return ImageView(context).apply {
                layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp)
            }
        }

        override fun bindView(
            context: Context, createdView: View, groupMember: GroupMember,
            holder: RecyclerView.ViewHolder, memberList: List<GroupMember>, position: Int
        ) {
            val imageView = createdView as ImageView
            // Load member avatar
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        leadingView = { groupMember ->
            CometChatAvatar(
                imageUrl = groupMember.avatar,
                name = groupMember.name
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Title View

Replace the name / title text.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setTitleView(object : GroupMembersViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return TextView(context)
        }

        override fun bindView(
            context: Context, createdView: View, groupMember: GroupMember,
            holder: RecyclerView.ViewHolder, memberList: List<GroupMember>, position: Int
        ) {
            (createdView as TextView).text = groupMember.name ?: ""
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        titleView = { groupMember ->
            Text(
                text = groupMember.name ?: "",
                style = CometChatTheme.typography.heading4Medium
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

Replace the subtitle text below the member's name.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setSubtitleView(object : GroupMembersViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return TextView(context).apply { maxLines = 1; ellipsize = TextUtils.TruncateAt.END }
        }

        override fun bindView(
            context: Context, createdView: View, groupMember: GroupMember,
            holder: RecyclerView.ViewHolder, memberList: List<GroupMember>, position: Int
        ) {
            (createdView as TextView).text = "Scope: ${groupMember.scope}"
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        subtitleView = { groupMember ->
            Text(
                text = "Scope: ${groupMember.scope}",
                maxLines = 1,
                overflow = TextOverflow.Ellipsis
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Trailing View

Replace the right section of each member item.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setTrailingView(object : GroupMembersViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return TextView(context)
        }

        override fun bindView(
            context: Context, createdView: View, groupMember: GroupMember,
            holder: RecyclerView.ViewHolder, memberList: List<GroupMember>, position: Int
        ) {
            (createdView as TextView).text = groupMember.scope ?: ""
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        trailingView = { groupMember ->
            Text(text = groupMember.scope ?: "")
        }
    )
    ```
  </Tab>
</Tabs>

### Item View

Replace the entire list item row.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setItemView(object : GroupMembersViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return LayoutInflater.from(context).inflate(R.layout.custom_member_item, null)
        }

        override fun bindView(
            context: Context, createdView: View, groupMember: GroupMember,
            holder: RecyclerView.ViewHolder, memberList: List<GroupMember>, position: Int
        ) {
            val avatar = createdView.findViewById<CometChatAvatar>(R.id.custom_avatar)
            val title = createdView.findViewById<TextView>(R.id.tvName)
            title.text = groupMember.name
            avatar.setAvatar(groupMember.name, groupMember.avatar)
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        itemView = { groupMember ->
            Row(
                modifier = Modifier.fillMaxWidth().padding(12.dp),
                verticalAlignment = Alignment.CenterVertically
            ) {
                CometChatAvatar(imageUrl = groupMember.avatar, name = groupMember.name)
                Spacer(Modifier.width(12.dp))
                Column {
                    Text(groupMember.name ?: "", style = CometChatTheme.typography.heading4Medium)
                    Text(groupMember.scope ?: "", style = CometChatTheme.typography.body3Regular)
                }
            }
        }
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setEmptyView(R.layout.custom_empty_view)
    groupMembers.setErrorView(R.layout.custom_error_view)
    groupMembers.setLoadingView(R.layout.custom_loading_view)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        emptyView = { Text("No members found") },
        errorView = { onRetry -> Button(onClick = onRetry) { Text("Retry") } },
        loadingView = { CircularProgressIndicator() }
    )
    ```
  </Tab>
</Tabs>

### Overflow Menu

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setOverflowMenu(ImageButton(context).apply {
        setImageResource(R.drawable.ic_add_member)
        setOnClickListener { /* add member */ }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        overflowMenu = {
            IconButton(onClick = { /* add member */ }) {
                Icon(painterResource(R.drawable.ic_add_member), "Add Member")
            }
        }
    )
    ```
  </Tab>
</Tabs>

***

## Menu Options

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Replace all options
    groupMembers.setOptions { context, groupMember ->
        listOf(
            CometChatPopupMenu.MenuItem(id = "kick", name = "Kick", onClick = { /* ... */ }),
            CometChatPopupMenu.MenuItem(id = "ban", name = "Ban", onClick = { /* ... */ })
        )
    }

    // Append to defaults
    groupMembers.setAddOptions { context, groupMember ->
        listOf(
            CometChatPopupMenu.MenuItem(id = "promote", name = "Promote", onClick = { /* ... */ })
        )
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        options = { context, groupMember ->
            listOf(
                MenuItem(id = "kick", name = "Kick", onClick = { /* ... */ }),
                MenuItem(id = "ban", name = "Ban", onClick = { /* ... */ })
            )
        },
        addOptions = { context, groupMember ->
            listOf(MenuItem(id = "promote", name = "Promote", onClick = { /* ... */ }))
        }
    )
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Minimal list — hide all chrome

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setToolbarVisibility(View.GONE)
    groupMembers.setSearchBoxVisibility(View.GONE)
    groupMembers.setSeparatorVisibility(View.GONE)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        hideToolbar = true,
        hideSearchBox = true,
        hideSeparator = true
    )
    ```
  </Tab>
</Tabs>

### Admins and moderators only

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setGroupMembersRequestBuilder(
        GroupMembersRequest.GroupMembersRequestBuilder(group.guid)
            .setScopes(listOf("admin", "moderator"))
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        groupMembersRequestBuilder = GroupMembersRequest.GroupMembersRequestBuilder(group.guid)
            .setScopes(listOf("admin", "moderator"))
    )
    ```
  </Tab>
</Tabs>

***

## Advanced Methods

### Programmatic Selection

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Enable selection
    groupMembers.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE)

    // Select a member
    groupMembers.selectGroupMember(member, UIKitConstants.SelectionMode.MULTIPLE)

    // Get selected
    val selected = groupMembers.getSelectedGroupMembers()

    // Clear
    groupMembers.clearSelection()
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Selection is managed via the `selectionMode` and `onSelection` parameters. The component handles selection state internally.
  </Tab>
</Tabs>

### ViewModel Access

```kotlin lines theme={null}
val factory = CometChatGroupMembersViewModelFactory()
val viewModel = ViewModelProvider(this, factory)
    .get(CometChatGroupMembersViewModel::class.java)
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groupMembers.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        groupMembersViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

See [ViewModel & Data](/docs/ui-kit/android/customization-viewmodel-data) for ListOperations, state observation, and custom repositories.

***

## Style

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Define a custom style in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="CustomGroupMembersAvatarStyle" parent="CometChatAvatarStyle">
        <item name="cometchatAvatarStrokeRadius">8dp</item>
        <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
    </style>

    <style name="CustomGroupMembersStyle" parent="CometChatGroupMembersStyle">
        <item name="cometchatGroupMembersAvatarStyle">@style/CustomGroupMembersAvatarStyle</item>
        <item name="cometchatGroupMembersSeparatorColor">#F76808</item>
        <item name="cometchatGroupMembersTitleTextColor">#F76808</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatGroupMembersStyle">@style/CustomGroupMembersStyle</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroupMembers(
        group = group,
        style = CometChatGroupMembersStyle.default().copy(
            backgroundColor = Color(0xFFF5F5F5),
            titleTextColor = Color(0xFF141414),
            itemStyle = CometChatGroupMembersItemStyle.default().copy(
                backgroundColor = Color.White,
                titleTextColor = Color(0xFF141414),
                subtitleTextColor = Color(0xFF727272),
                avatarStyle = CometChatAvatarStyle.default().copy(cornerRadius = 12.dp),
                statusIndicatorStyle = CometChatStatusIndicatorStyle.default().copy()
            )
        )
    )
    ```
  </Tab>
</Tabs>

### Style Properties

| Property                            | Description              |
| ----------------------------------- | ------------------------ |
| `backgroundColor`                   | List background color    |
| `titleTextColor`                    | Toolbar title color      |
| `searchBoxStyle`                    | Search box appearance    |
| `itemStyle.backgroundColor`         | Row background           |
| `itemStyle.selectedBackgroundColor` | Selected row background  |
| `itemStyle.titleTextColor`          | Member name color        |
| `itemStyle.subtitleTextColor`       | Subtitle text color      |
| `itemStyle.separatorColor`          | Row separator color      |
| `itemStyle.avatarStyle`             | Avatar appearance        |
| `itemStyle.statusIndicatorStyle`    | Online/offline indicator |

See [Component Styling](/docs/ui-kit/android/component-styling) for the full reference.

***

## Next Steps

<CardGroup>
  <Card title="Groups" icon="users" href="/ui-kit/android/groups">
    Browse and search available groups
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/android/conversations">
    Browse recent conversations
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/android/component-styling">
    Detailed styling reference with screenshots
  </Card>

  <Card title="ViewModel & Data" icon="database" href="/ui-kit/android/customization-viewmodel-data">
    Custom ViewModels, repositories, and ListOperations
  </Card>
</CardGroup>


# Groups
Source: https://www.cometchat.com/docs/ui-kit/android/groups

Scrollable list of all available groups with search, avatars, names, and group type indicators.

`CometChatGroups` renders a scrollable list of all available groups with real-time updates for membership changes, search, avatars, and group type indicators (public, private, password-protected).

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatGroups` is a list component. It renders all available groups and emits the selected `Group` via `onItemClick`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a group messaging layout.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_chat.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.groups.ui.CometChatGroups
        android:id="@+id/groups"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    ```kotlin lines theme={null}
    val groups = findViewById<CometChatGroups>(R.id.groups)

    groups.setOnItemClick { group ->
        messageHeader.setGroup(group)
        messageList.setGroup(group)
        messageComposer.setGroup(group)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        modifier = Modifier.fillMaxSize(),
        onItemClick = { group ->
            messageHeader.setGroup(group)
            messageList.setGroup(group)
            messageComposer.setGroup(group)
        }
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add to your layout XML:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.groups.ui.CometChatGroups
        android:id="@+id/groups"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    Or programmatically:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(CometChatGroups(this))
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    @Composable
    fun GroupsScreen() {
        CometChatGroups(
            modifier = Modifier.fillMaxSize()
        )
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

Or in a Fragment:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
        return CometChatGroups(requireContext())
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
        return ComposeView(requireContext()).apply {
            setContent { CometChatGroups() }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Filtering Groups

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Pass a `GroupsRequest.GroupsRequestBuilder` to control what loads:

    ```kotlin lines theme={null}
    groups.setGroupsRequestBuilder(
        GroupsRequest.GroupsRequestBuilder()
            .joinedOnly(true)
            .setLimit(20)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        groupsRequestBuilder = GroupsRequest.GroupsRequestBuilder()
            .joinedOnly(true)
            .setLimit(20)
    )
    ```
  </Tab>
</Tabs>

### Filter Recipes

| Recipe            | Builder method                |
| ----------------- | ----------------------------- |
| Joined only       | `.joinedOnly(true)`           |
| Limit per page    | `.setLimit(10)`               |
| Search by keyword | `.setSearchKeyWord("design")` |
| Filter by tags    | `.setTags(listOf("vip"))`     |
| With tags         | `.withTags(true)`             |

<Warning>
  Pass the builder object, not the result of `.build()`. The component calls `.build()` internally. Default page size is 30 with infinite scroll.
</Warning>

***

## Actions and Events

### Callback Methods

#### `onItemClick`

Fires when a group row is tapped. Primary navigation hook.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setOnItemClick { group ->
        // Navigate to group chat screen
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        onItemClick = { group ->
            // Navigate to group chat screen
        }
    )
    ```
  </Tab>
</Tabs>

> Replaces the default item-click behavior. Your custom lambda executes instead of the built-in navigation.

#### `onItemLongClick`

Fires when a group row is long-pressed. Use for additional actions like delete or leave.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setOnItemLongClick { group ->
        // Show context menu
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        onItemLongClick = { group ->
            // Show context menu
        }
    )
    ```
  </Tab>
</Tabs>

#### `onBackPress`

Fires when the user presses the back button in the toolbar.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setOnBackPress {
        finish()
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        onBackPress = { /* navigate back */ }
    )
    ```
  </Tab>
</Tabs>

#### `onSearchClick`

Fires when the user taps the search icon in the toolbar.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setOnSearchClick {
        // Open search screen
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        onSearchClick = { /* open search */ }
    )
    ```
  </Tab>
</Tabs>

#### `onSelection`

Fires when groups are selected/deselected in multi-select mode.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE)
    groups.setOnSelection { selectedGroups ->
        updateToolbar(selectedGroups.size)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        selectionMode = UIKitConstants.SelectionMode.MULTIPLE,
        onSelection = { selectedGroups ->
            updateToolbar(selectedGroups.size)
        }
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setOnError { exception ->
        Log.e("Groups", "Error: ${exception.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        onError = { exception ->
            Log.e("Groups", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched and loaded.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setOnLoad { groupList ->
        Log.d("Groups", "Loaded ${groupList.size}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        onLoad = { groupList ->
            Log.d("Groups", "Loaded ${groupList.size}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setOnEmpty {
        Log.d("Groups", "No groups found")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        onEmpty = { /* no groups */ }
    )
    ```
  </Tab>
</Tabs>

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

| SDK Listener                | Internal behavior                                    |
| --------------------------- | ---------------------------------------------------- |
| `onGroupMemberJoined`       | Updates the group list when a member joins           |
| `onGroupMemberLeft`         | Updates the group list when a member leaves          |
| `onGroupMemberKicked`       | Updates the group list when a member is kicked       |
| `onGroupMemberBanned`       | Updates the group list when a member is banned       |
| `onGroupMemberUnbanned`     | Updates the group list when a member is unbanned     |
| `onGroupMemberScopeChanged` | Updates the group list when a member's scope changes |
| `onMemberAddedToGroup`      | Updates the group list when members are added        |

***

## Functionality

| Method (Kotlin XML)                   | Compose Parameter                   | Description                 |
| ------------------------------------- | ----------------------------------- | --------------------------- |
| `setBackIconVisibility(View.VISIBLE)` | `hideBackIcon = false`              | Toggle back button          |
| `setToolbarVisibility(View.GONE)`     | `hideToolbar = true`                | Toggle toolbar              |
| `setSearchBoxVisibility(View.GONE)`   | `hideSearchBox = true`              | Toggle search box           |
| `setGroupTypeVisibility(View.GONE)`   | `hideGroupType = true`              | Toggle group type indicator |
| `setSeparatorVisibility(View.GONE)`   | `hideSeparator = true`              | Toggle list separators      |
| `setSelectionMode(MULTIPLE)`          | `selectionMode = MULTIPLE`          | Enable selection mode       |
| `setTitle("My Groups")`               | `title = "My Groups"`               | Custom toolbar title        |
| `setSearchPlaceholderText("Find...")` | `searchPlaceholderText = "Find..."` | Search placeholder          |

***

## Custom View Slots

### Leading View

Replace the avatar / left section.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setLeadingView(object : GroupsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return ImageView(context).apply {
                layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp)
            }
        }

        override fun bindView(
            context: Context, createdView: View, group: Group,
            holder: RecyclerView.ViewHolder, groupList: List<Group>, position: Int
        ) {
            val imageView = createdView as ImageView
            // Load group avatar
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        leadingView = { group ->
            CometChatAvatar(
                imageUrl = group.icon,
                name = group.name
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Title View

Replace the name / title text.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setTitleView(object : GroupsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return TextView(context)
        }

        override fun bindView(
            context: Context, createdView: View, group: Group,
            holder: RecyclerView.ViewHolder, groupList: List<Group>, position: Int
        ) {
            (createdView as TextView).text = group.name ?: ""
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        titleView = { group ->
            Text(
                text = group.name ?: "",
                style = CometChatTheme.typography.heading4Medium
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

Replace the subtitle text below the group name.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setSubtitleView(object : GroupsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return TextView(context).apply { maxLines = 1; ellipsize = TextUtils.TruncateAt.END }
        }

        override fun bindView(
            context: Context, createdView: View, group: Group,
            holder: RecyclerView.ViewHolder, groupList: List<Group>, position: Int
        ) {
            (createdView as TextView).text = "${group.membersCount} members"
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        subtitleView = { group ->
            Text(
                text = "${group.membersCount} members",
                maxLines = 1,
                overflow = TextOverflow.Ellipsis
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Trailing View

Replace the right section of each group item.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setTrailingView(object : GroupsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return TextView(context)
        }

        override fun bindView(
            context: Context, createdView: View, group: Group,
            holder: RecyclerView.ViewHolder, groupList: List<Group>, position: Int
        ) {
            (createdView as TextView).text = if (group.isJoined) "Joined" else "Join"
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        trailingView = { group ->
            Text(text = if (group.isJoined) "Joined" else "Join")
        }
    )
    ```
  </Tab>
</Tabs>

### Item View

Replace the entire list item row.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setItemView(object : GroupsViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return LayoutInflater.from(context).inflate(R.layout.custom_group_item, null)
        }

        override fun bindView(
            context: Context, createdView: View, group: Group,
            holder: RecyclerView.ViewHolder, groupList: List<Group>, position: Int
        ) {
            val avatar = createdView.findViewById<CometChatAvatar>(R.id.custom_avatar)
            val title = createdView.findViewById<TextView>(R.id.tvName)
            title.text = group.name
            avatar.setAvatar(group.name, group.icon)
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        itemView = { group ->
            Row(
                modifier = Modifier.fillMaxWidth().padding(12.dp),
                verticalAlignment = Alignment.CenterVertically
            ) {
                CometChatAvatar(imageUrl = group.icon, name = group.name)
                Spacer(Modifier.width(12.dp))
                Column {
                    Text(group.name ?: "", style = CometChatTheme.typography.heading4Medium)
                    Text("${group.membersCount} members", style = CometChatTheme.typography.body3Regular)
                }
            }
        }
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setEmptyView(R.layout.custom_empty_view)
    groups.setErrorView(R.layout.custom_error_view)
    groups.setLoadingView(R.layout.custom_loading_view)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        emptyView = { Text("No groups found") },
        errorView = { onRetry -> Button(onClick = onRetry) { Text("Retry") } },
        loadingView = { CircularProgressIndicator() }
    )
    ```
  </Tab>
</Tabs>

### Overflow Menu

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setOverflowMenu(ImageButton(context).apply {
        setImageResource(R.drawable.ic_create_group)
        setOnClickListener { /* create group */ }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        overflowMenu = {
            IconButton(onClick = { /* create group */ }) {
                Icon(painterResource(R.drawable.ic_create_group), "Create Group")
            }
        }
    )
    ```
  </Tab>
</Tabs>

***

## Menu Options

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Replace all options
    groups.setOptions { context, group ->
        listOf(
            CometChatPopupMenu.MenuItem(id = "leave", name = "Leave", onClick = { /* ... */ }),
            CometChatPopupMenu.MenuItem(id = "delete", name = "Delete", onClick = { /* ... */ })
        )
    }

    // Append to defaults
    groups.setAddOptions { context, group ->
        listOf(
            CometChatPopupMenu.MenuItem(id = "pin", name = "Pin", onClick = { /* ... */ })
        )
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        options = { context, group ->
            listOf(
                MenuItem(id = "leave", name = "Leave", onClick = { /* ... */ }),
                MenuItem(id = "delete", name = "Delete", onClick = { /* ... */ })
            )
        },
        addOptions = { context, group ->
            listOf(MenuItem(id = "pin", name = "Pin", onClick = { /* ... */ }))
        }
    )
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Minimal list — hide all chrome

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setToolbarVisibility(View.GONE)
    groups.setSearchBoxVisibility(View.GONE)
    groups.setGroupTypeVisibility(View.GONE)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        hideToolbar = true,
        hideSearchBox = true,
        hideGroupType = true
    )
    ```
  </Tab>
</Tabs>

### Joined groups only

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setGroupsRequestBuilder(
        GroupsRequest.GroupsRequestBuilder()
            .joinedOnly(true)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        groupsRequestBuilder = GroupsRequest.GroupsRequestBuilder()
            .joinedOnly(true)
    )
    ```
  </Tab>
</Tabs>

### Tagged groups

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setGroupsRequestBuilder(
        GroupsRequest.GroupsRequestBuilder()
            .setTags(listOf("support"))
            .withTags(true)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        groupsRequestBuilder = GroupsRequest.GroupsRequestBuilder()
            .setTags(listOf("support"))
            .withTags(true)
    )
    ```
  </Tab>
</Tabs>

***

## Advanced Methods

### Programmatic Selection

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Enable selection
    groups.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE)

    // Select a group
    groups.selectGroup(group, UIKitConstants.SelectionMode.MULTIPLE)

    // Get selected
    val selected = groups.getSelectedGroups()

    // Clear
    groups.clearSelection()
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Selection is managed via the `selectionMode` and `onSelection` parameters. The component handles selection state internally.
  </Tab>
</Tabs>

### ViewModel Access

```kotlin lines theme={null}
val factory = CometChatGroupsViewModelFactory()
val viewModel = ViewModelProvider(this, factory)
    .get(CometChatGroupsViewModel::class.java)
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    groups.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        groupsViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

See [ViewModel & Data](/docs/ui-kit/android/customization-viewmodel-data) for ListOperations, state observation, and custom repositories.

***

## Style

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Define a custom style in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="CustomGroupsAvatarStyle" parent="CometChatAvatarStyle">
        <item name="cometchatAvatarStrokeRadius">8dp</item>
        <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
    </style>

    <style name="CustomGroupsStyle" parent="CometChatGroupsStyle">
        <item name="cometchatGroupsAvatarStyle">@style/CustomGroupsAvatarStyle</item>
        <item name="cometchatGroupsSeparatorColor">#F76808</item>
        <item name="cometchatGroupsTitleTextColor">#F76808</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatGroupsStyle">@style/CustomGroupsStyle</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatGroups(
        style = CometChatGroupsStyle.default().copy(
            backgroundColor = Color(0xFFF5F5F5),
            titleTextColor = Color(0xFF141414),
            itemStyle = CometChatGroupsItemStyle.default().copy(
                backgroundColor = Color.White,
                titleTextColor = Color(0xFF141414),
                subtitleTextColor = Color(0xFF727272),
                avatarStyle = CometChatAvatarStyle.default().copy(cornerRadius = 12.dp),
                statusIndicatorStyle = CometChatStatusIndicatorStyle.default().copy()
            )
        )
    )
    ```
  </Tab>
</Tabs>

### Style Properties

| Property                            | Description             |
| ----------------------------------- | ----------------------- |
| `backgroundColor`                   | List background color   |
| `titleTextColor`                    | Toolbar title color     |
| `searchBoxStyle`                    | Search box appearance   |
| `itemStyle.backgroundColor`         | Row background          |
| `itemStyle.selectedBackgroundColor` | Selected row background |
| `itemStyle.titleTextColor`          | Group name color        |
| `itemStyle.subtitleTextColor`       | Subtitle text color     |
| `itemStyle.separatorColor`          | Row separator color     |
| `itemStyle.avatarStyle`             | Avatar appearance       |
| `itemStyle.statusIndicatorStyle`    | Group type indicator    |

See [Component Styling](/docs/ui-kit/android/component-styling) for the full reference.

***

## Next Steps

<CardGroup>
  <Card title="Group Members" icon="user-group" href="/ui-kit/android/group-members">
    View and manage group members
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/android/conversations">
    Browse recent conversations
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/android/component-styling">
    Detailed styling reference with screenshots
  </Card>

  <Card title="ViewModel & Data" icon="database" href="/ui-kit/android/customization-viewmodel-data">
    Custom ViewModels, repositories, and ListOperations
  </Card>
</CardGroup>


# AI Agent Integration
Source: https://www.cometchat.com/docs/ui-kit/android/guide-ai-agent

Enable AI-powered conversational assistance with chat history, contextual responses, and seamless handoffs.

<Accordion title="Quick Reference">
  | Field          | Value                                                                                                                                                            |
  | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Packages       | `com.cometchat:chatuikit-kotlin-android` · `com.cometchat:chatuikit-compose-android`                                                                             |
  | Key components | `CometChatAIAssistantChatHistory`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageHeader`                                                  |
  | Purpose        | Enable AI-powered conversational assistance with chat history, contextual responses, and seamless handoffs.                                                      |
  | Related        | [AI Assistant Chat History](/docs/ui-kit/android/ai-assistant-chat-history), [AI Features](/docs/ui-kit/android/ai-features), [All Guides](/docs/ui-kit/android/guide-overview) |
</Accordion>

Enable intelligent conversational AI capabilities in your Android app using CometChat UIKit v6 with AI Agent integration:

* **AI Assistant Chat History**
* **Chat History Management**
* **Contextual Responses**
* **Agent Detection**
* **Seamless Handoffs**

Transform your chat experience with AI-powered assistance that provides intelligent responses and seamless integration with your existing chat infrastructure.

<Note>
  **1:1 and group conversations.** AI Agents work in both one-on-one and group conversations. In a 1:1 chat, the end user talks directly with the agent user. In a group, the agent participates as a member — its messages (including cards) are rendered and attributed like any other member's message.
</Note>

## Overview

Users can interact with AI agents through a dedicated chat interface that:

* Provides intelligent responses based on conversation context.
* Maintains chat history for continuity.
* Seamlessly integrates with your existing user chat system.

The AI Agent chat interface provides a familiar messaging experience enhanced with AI capabilities, accessible through your main chat flow or as a standalone feature.

<Frame>
  <img />
</Frame>

## Prerequisites

* Android Studio project with `com.cometchat:chatuikit-kotlin-android` or `com.cometchat:chatuikit-compose-android` in `build.gradle`.
* Internet permission in `AndroidManifest.xml`.
* Valid CometChat **App ID**, **Region**, and **Auth Key** configured via `UIKitSettings`.
* User logged in with `CometChatUIKit.login()`.
* AI Agent configured in your CometChat dashboard.

## Components

| Component / Class                 | Role                                       |
| :-------------------------------- | :----------------------------------------- |
| `AIAssistantChatActivity`         | Main activity for AI agent chat.           |
| `CometChatAIAssistantChatHistory` | Displays previous AI conversation history. |
| `CometChatMessageList`            | Shows AI messages with threading support.  |
| `CometChatMessageComposer`        | Input interface for AI conversations.      |
| `CometChatMessageHeader`          | Header with AI agent info and controls.    |

## Integration Steps

### Step 1 — Activity / Screen Setup

Create the AI Assistant chat screen with proper layout configuration.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin AIAssistantChatActivity.kt lines theme={null}
    class AIAssistantChatActivity : AppCompatActivity() {
        private lateinit var binding: ActivityAiAssistantChatBinding

        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            binding = ActivityAiAssistantChatBinding.inflate(layoutInflater)
            setContentView(binding.root)

            val messageJson = intent.getStringExtra(getString(R.string.app_base_message))
            val userJson = intent.getStringExtra(getString(R.string.app_user))

            var user: User? = null
            var parentMessage: BaseMessage? = null

            if (!userJson.isNullOrEmpty())
                user = User.fromJson(userJson)
            if (!messageJson.isNullOrEmpty())
                parentMessage = BaseMessage.processMessage(JSONObject(messageJson))

            initializeComponents(user, parentMessage)
            initClickListeners()
        }

        private fun initializeComponents(user: User?, parentMessage: BaseMessage?) {
            user?.let {
                binding.messageHeader.user = it
                binding.messageList.user = it
                binding.messageComposer.user = it
            }

            if (parentMessage != null) {
                binding.messageList.setParentMessage(parentMessage.getId())
                binding.messageComposer.setParentMessageId(parentMessage.getId())
            }

            binding.messageList.setStyle(R.style.CustomCometChatMessageListStyle)
            binding.messageComposer.style = R.style.CustomMessageComposerStyle
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin AIAssistantChatScreen.kt lines theme={null}
    import com.cometchat.uikit.compose.presentation.messageheader.ui.CometChatMessageHeader
    import com.cometchat.uikit.compose.presentation.messagelist.ui.CometChatMessageList
    import com.cometchat.uikit.compose.presentation.messagecomposer.ui.CometChatMessageComposer

    @Composable
    fun AIAssistantChatScreen(
        user: User,
        parentMessageId: Int? = null,
        onNewChatClick: () -> Unit = {},
        onChatHistoryClick: () -> Unit = {}
    ) {
        Column(modifier = Modifier.fillMaxSize()) {
            CometChatMessageHeader(
                user = user
            )

            CometChatMessageList(
                user = user,
                parentMessageId = parentMessageId ?: 0,
                modifier = Modifier.weight(1f)
            )

            CometChatMessageComposer(
                user = user,
                parentMessageId = parentMessageId ?: 0
            )
        }
    }
    ```
  </Tab>
</Tabs>

**File reference:**
[`AIAssistantChatActivity.kt`](https://github.com/cometchat/cometchat-uikit-android/blob/v6/ai-sample-app/src/main/java/com/cometchat/ai/sampleapp/ui/activity/AIAssistantChatActivity.kt)

### Step 2 — Layout (XML Views only)

Add `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to your layout.

```xml activity_ai_assistant_chat.xml lines theme={null}
<LinearLayout android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    xmlns:android="http://schemas.android.com/apk/res/android">

    <com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader
        android:id="@+id/messageHeader"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    <com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
        android:id="@+id/messageList"
        android:layout_width="match_parent"
        android:layout_height="0dp"
        android:layout_weight="1" />

    <com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
        android:id="@+id/messageComposer"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

</LinearLayout>
```

> **Note:** In Jetpack Compose, layout is handled declaratively in the composable function — no XML needed.

### Step 3 — Style of Message List & Composer (XML Views only)

Define custom styles for the message list and composer to differentiate AI agent chats.

```xml themes.xml lines theme={null}
<style name="CustomMessageComposerStyle">
    <item name="cometchatMessageComposerBackgroundColor">?attr/cometchatBackgroundColor2</item>
    <item name="cometchatMessageComposerComposeBoxStrokeWidth">@dimen/cometchat_1dp</item>
    <item name="cometchatMessageComposerComposeBoxCornerRadius">@dimen/cometchat_radius_2</item>
    <item name="cometchatMessageInputStyle">?attr/cometchatMessageInputStyle</item>
</style>

<style name="CustomCometChatMessageListStyle" parent="CometChatMessageListStyle">
    <item name="cometchatMessageListOutgoingMessageBubbleStyle">@style/CustomOutgoingMessageBubbleStyle</item>
</style>

<style name="CustomOutgoingMessageBubbleStyle">
    <item name="cometchatMessageBubbleBackgroundColor">?attr/cometchatBackgroundColor4</item>
    <item name="cometchatMessageBubbleCornerRadius">@dimen/cometchat_radius_3</item>
    <item name="cometchatTextBubbleStyle">@style/CustomTextBubbleStyle</item>
    <item name="cometchatMessageBubbleDateStyle">@style/CustomOutgoingMessageDateStyle</item>
</style>
```

> **Jetpack Compose:** Pass a custom style object via the `style` parameter on each composable instead of XML styles.

### Step 4 — Initialize click listeners

Initialize click listeners to handle new chat creation and chat history access.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin AIAssistantChatActivity.kt lines theme={null}
    private fun initClickListeners() {
        // New chat creation
        binding.messageHeader.setNewChatButtonClick {
            Utils.hideKeyBoard(this@AIAssistantChatActivity, binding.root)
            val intent = Intent(this@AIAssistantChatActivity, AIAssistantChatActivity::class.java)
            intent.putExtra(getString(R.string.app_user), user.toJson().toString())
            startActivity(intent)
            finish()
        }

        // Chat history access
        binding.messageHeader.setChatHistoryButtonClick {
            val intent = Intent(this@AIAssistantChatActivity, AIAssistantChatHistoryActivity::class.java)
            intent.putExtra(getString(R.string.app_user), user.toJson().toString())
            startActivity(intent)
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin AIAssistantChatScreen.kt lines theme={null}
    // In Jetpack Compose, pass callbacks as lambda parameters:
    AIAssistantChatScreen(
        user = aiUser,
        onNewChatClick = {
            // Navigate to a fresh AI chat screen
            navController.navigate("ai_chat/${Gson().toJson(aiUser)}")
        },
        onChatHistoryClick = {
            // Navigate to chat history screen
            navController.navigate("ai_chat_history/${Gson().toJson(aiUser)}")
        }
    )
    ```
  </Tab>
</Tabs>

### Step 5 — AI Assistant Chat History screen

Create a screen to host the `CometChatAIAssistantChatHistory` component.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin AIAssistantChatHistoryActivity.kt lines theme={null}
    class AIAssistantChatHistoryActivity : AppCompatActivity() {
        private lateinit var binding: ActivityAiAssistantChatHistoryBinding
        private var user: User? = null

        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            binding = ActivityAiAssistantChatHistoryBinding.inflate(layoutInflater)
            setContentView(binding.root)

            val userJson = intent.getStringExtra(getString(R.string.app_user))

            if (userJson != null && userJson.isNotEmpty()) {
                user = User.fromJson(userJson)
                binding.cometchatAiAssistantChatHistory.setUser(user)
            }

            initClickListeners()
        }

        private fun initClickListeners() {
            binding.cometchatAiAssistantChatHistory.setOnItemClickListener { view, position, message ->
                val appEntity = message.getReceiver()
                if (appEntity is User) {
                    user = appEntity
                    val intent = Intent(this, AIAssistantChatActivity::class.java)
                    intent.putExtra(getString(R.string.app_user), appEntity.toJson().toString())
                    intent.putExtra(getString(R.string.app_base_message), message.getRawMessage().toString())
                    startActivity(intent)
                    finish()
                }
            }

            binding.cometchatAiAssistantChatHistory.setOnNewChatClickListener {
                val intent = Intent(this, AIAssistantChatActivity::class.java)
                intent.putExtra(getString(R.string.app_user), user!!.toJson().toString())
                startActivity(intent)
                finish()
            }

            binding.cometchatAiAssistantChatHistory.setOnCloseClickListener {
                finish()
            }
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin AIAssistantChatHistoryScreen.kt lines theme={null}
    import com.cometchat.uikit.compose.presentation.aiassistantchathistory.ui.CometChatAIAssistantChatHistory

    @Composable
    fun AIAssistantChatHistoryScreen(
        user: User,
        navController: NavController
    ) {
        CometChatAIAssistantChatHistory(
            modifier = Modifier.fillMaxSize(),
            onCloseClick = {
                navController.popBackStack()
            },
            onNewChatClick = {
                navController.navigate("ai_chat/${Gson().toJson(user)}")
            },
            onItemClick = { message ->
                val receiver = message.receiver
                if (receiver is User) {
                    navController.navigate(
                        "ai_chat/${Gson().toJson(receiver)}/${message.rawMessage}"
                    )
                }
            }
        )
    }
    ```
  </Tab>
</Tabs>

### Step 6 — Chat History layout (XML Views only)

```xml activity_ai_assistant_chat_history.xml lines theme={null}
<LinearLayout android:layout_width="match_parent"
    android:layout_height="match_parent"
    xmlns:android="http://schemas.android.com/apk/res/android">

    <com.cometchat.uikit.kotlin.presentation.aiassistantchathistory.ui.CometChatAIAssistantChatHistory
        android:id="@+id/cometchat_ai_assistant_chat_history"
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>

</LinearLayout>
```

> **Note:** In Jetpack Compose, the `CometChatAIAssistantChatHistory` composable is used directly — no XML layout needed.

### Step 7 — Launching AI Chat

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    fun launchAIAssistantChat(aiUser: User) {
        val intent = Intent(this, AIAssistantChatActivity::class.java)
        intent.putExtra(getString(R.string.app_user), aiUser.toJson().toString())
        startActivity(intent)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // In your NavHost setup:
    composable("ai_chat/{userJson}") { backStackEntry ->
        val userJson = backStackEntry.arguments?.getString("userJson")
        val user = Gson().fromJson(userJson, User::class.java)
        AIAssistantChatScreen(user = user)
    }

    composable("ai_chat_history/{userJson}") { backStackEntry ->
        val userJson = backStackEntry.arguments?.getString("userJson")
        val user = Gson().fromJson(userJson, User::class.java)
        AIAssistantChatHistoryScreen(user = user, navController = navController)
    }
    ```
  </Tab>
</Tabs>

## Implementation Flow Summary

| Step | Action                                                                    |
| :--- | :------------------------------------------------------------------------ |
| 1    | User selects AI agent from chat list                                      |
| 2    | AI chat screen launches                                                   |
| 3    | Parse intent data and detect agent chat (Role of user must be "@agentic") |
| 4    | Initialize UI with AI-specific styling                                    |
| 5    | Configure chat history and navigation                                     |
| 6    | Launch chat with AI agent                                                 |

## Customization Options

* **Custom AI Assistant Empty Chat View:** Customize the empty state view using `setAIAssistantEmptyChatGreetingView()` (XML Views) or the `emptyView` composable slot (Compose).
* **Streaming Speed:** Adjust AI response streaming speed via `setStreamingSpeed()`.
* **AI Assistant Suggested Messages:** Create custom list of suggested messages using `setAIAssistantSuggestedMessages()`.
* **AI Assistant Tools:** Set tools for the AI agent using `setAIAssistantTools()`.

## Feature Matrix

| Feature           | Kotlin (XML Views)                    | Jetpack Compose                                |
| :---------------- | :------------------------------------ | :--------------------------------------------- |
| AI Chat Interface | `AIAssistantChatActivity`             | `AIAssistantChatScreen` composable             |
| Chat History      | `CometChatAIAssistantChatHistory` XML | `CometChatAIAssistantChatHistory()` composable |
| Message List      | `CometChatMessageList` XML            | `CometChatMessageList()` composable            |
| Message Composer  | `CometChatMessageComposer` XML        | `CometChatMessageComposer()` composable        |

<CardGroup>
  <Card title="Android AI Builder Sample">
    Explore this feature in the CometChat AI Builder:
    [GitHub → AI Builder](https://github.com/cometchat/cometchat-uikit-android/tree/v6/ai-sample-app)
  </Card>

  <Card title="Android Sample App (Kotlin)">
    Explore this feature in the CometChat SampleApp:
    [GitHub → SampleApp](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin)
  </Card>
</CardGroup>


# Block/Unblock User
Source: https://www.cometchat.com/docs/ui-kit/android/guide-block-unblock-user

Let users block and unblock others directly within chat to control unwanted communication.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                            |
  | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Packages       | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack`                                                                             |
  | Key components | `CometChatMessageComposer`, `CometChat.blockUsers()`, `CometChat.unblockUsers()`, `User.isBlockedByMe()`                                         |
  | Purpose        | Let users block and unblock others directly within chat to control unwanted communication.                                                       |
  | Related        | [Message Composer](/docs/ui-kit/android/message-composer), [Message List](/docs/ui-kit/android/message-list), [All Guides](/docs/ui-kit/android/guide-overview) |
</Accordion>

Enable users to block and unblock others directly within chat using CometChat's Android UI Kit v6+, preventing unwanted communication and giving users more control.

## Overview

Blocking a user stops them from sending messages to the blocker. The CometChat UIKit handles most behaviors internally:

* **Composer Hidden:** The message composer is hidden when chatting with a blocked user.
* **Unblock Prompt:** An "Unblock" button is displayed to reverse the block.
* **Message Restrictions:** Blocked users cannot send messages to the blocker.

## Prerequisites

* Android Studio project with CometChat Android UI Kit v6 added to `build.gradle`.
* CometChat **App ID**, **Auth Key**, and **Region** configured and initialized.
* `<uses-permission android:name="android.permission.INTERNET"/>` in `AndroidManifest.xml`.
* Logged-in user via `CometChatUIKit.login()`.
* Existing one-on-one chat screen using `CometChatMessageList` and `CometChatMessageComposer`.

## Components

| Component / Class          | Role                                                       |
| :------------------------- | :--------------------------------------------------------- |
| `UserDetailActivity`       | Displays user profile and provides block/unblock options.  |
| `MessagesActivity`         | Hosts the chat screen and toggles UI based on block state. |
| `CometChat.blockUsers()`   | SDK API to block one or more users by UID.                 |
| `CometChat.unblockUsers()` | SDK API to unblock one or more users by UID.               |
| `User.isBlockedByMe()`     | Checks if the current user has blocked this user.          |
| `unblockLayout` (View)     | Layout shown when a user is blocked, containing unblock.   |
| `CometChatMessageComposer` | Hidden when chatting with a blocked user.                  |

## Integration Steps

### 1. Detect Block Status

Update UI when block state changes.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // In MessagesActivity.kt
    import com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer

    private fun updateUserBlockStatus(user: User) {
        val blocked = user.isBlockedByMe
        binding.messageComposer.visibility = if (blocked) View.GONE else View.VISIBLE
        binding.unblockLayout.visibility = if (blocked) View.VISIBLE else View.GONE
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // In MessagesScreen.kt
    import com.cometchat.uikit.compose.presentation.messagecomposer.ui.CometChatMessageComposer

    @Composable
    fun MessagesScreen(user: User) {
        val blocked = user.isBlockedByMe

        Column(modifier = Modifier.fillMaxSize()) {
            // Message list...

            if (blocked) {
                UnblockPrompt(onUnblock = { /* unblock logic */ })
            } else {
                CometChatMessageComposer(user = user)
            }
        }
    }
    ```
  </Tab>
</Tabs>

**File reference:**\
[`MessagesActivity.kt`](https://github.com/cometchat/cometchat-uikit-android/blob/v6/sample-app-kotlin)

Ensures the composer and unblock UI reflect the current block state.

### 2. Hide Composer & Show Unblock UI

Define layout elements and their visibility toggles.

```xml activity_messages.xml lines theme={null}
<!-- In activity_messages.xml (chatuikit-kotlin) -->
<com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
    android:id="@+id/messageComposer"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

<LinearLayout
    android:id="@+id/unblockLayout"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:gravity="center"
    android:padding="12dp"
    android:visibility="gone">

    <Button
        android:id="@+id/unblockBtn"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Unblock" />
</LinearLayout>
```

Prepares the UI containers for dynamic show/hide operations.

### 3. Trigger Unblock Action

Call the unblock API and observe status updates.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // In MessagesActivity.kt
    binding.unblockBtn.setOnClickListener { viewModel.unblockUser() }

    // In MessagesViewModel.kt
    fun unblockUser() {
        CometChat.unblockUsers(listOf(currentUser.uid), object : CometChat.CallbackListener<HashMap<String, String>>() {
            override fun onSuccess(resultMap: HashMap<String, String>) {
                _unblockButtonState.value = false
            }
            override fun onError(e: CometChatException?) {
                // Handle error
            }
        })
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // In MessagesViewModel.kt
    private val _isBlocked = MutableStateFlow(false)
    val isBlocked: StateFlow<Boolean> = _isBlocked.asStateFlow()

    fun unblockUser() {
        CometChat.unblockUsers(listOf(currentUser.uid), object : CometChat.CallbackListener<HashMap<String, String>>() {
            override fun onSuccess(resultMap: HashMap<String, String>) {
                _isBlocked.value = false
            }
            override fun onError(e: CometChatException?) {
                // Handle error
            }
        })
    }

    // In MessagesScreen.kt
    @Composable
    fun MessagesScreen(viewModel: MessagesViewModel = viewModel()) {
        val isBlocked by viewModel.isBlocked.collectAsState()

        if (isBlocked) {
            Button(onClick = { viewModel.unblockUser() }) {
                Text("Unblock")
            }
        }
    }
    ```
  </Tab>
</Tabs>

Executes unblock logic and updates state to refresh UI.

### 4. Trigger Block from Detail Screen

Allow blocking directly from a user's profile.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // In UserDetailActivity.kt
    binding.blockMenuItem.setOnClickListener {
        CometChat.blockUsers(listOf(user.uid), object : CometChat.CallbackListener<HashMap<String, String>>() {
            override fun onSuccess(resultMap: HashMap<String, String>) {
                viewModel.refreshUser()
            }
            override fun onError(e: CometChatException?) {
                // Handle error
            }
        })
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // In UserDetailScreen.kt
    @Composable
    fun BlockButton(user: User, onBlocked: () -> Unit) {
        Button(onClick = {
            CometChat.blockUsers(listOf(user.uid), object : CometChat.CallbackListener<HashMap<String, String>>() {
                override fun onSuccess(resultMap: HashMap<String, String>) {
                    onBlocked()
                }
                override fun onError(e: CometChatException?) { /* Handle error */ }
            })
        }) {
            Text("Block User")
        }
    }
    ```
  </Tab>
</Tabs>

## Implementation Flow

| Step | Action                                | Location                                        |
| :--- | :------------------------------------ | :---------------------------------------------- |
| 1    | Check block status                    | `updateUserBlockStatus()` in `MessagesActivity` |
| 2    | Show/hide composer and unblock layout | `activity_messages.xml` or Compose conditional  |
| 3    | Unblock API call and state update     | `MessagesViewModel.unblockUser()`               |
| 4    | Block API call from profile           | `UserDetailActivity.blockMenuItem`              |

## Customization Options

* **Feedback UI:** Show a Toast or Snackbar upon success/failure.
* **Menu Icons/Text:** Toggle icon and text dynamically after block/unblock.
* **Disable History:** Optionally gray out or hide past messages when blocked.

## Filtering & Edge Cases

| Case            | Behavior                                      |
| :-------------- | :-------------------------------------------- |
| Blocked User    | Composer hidden; unblock layout shown.        |
| Block Self      | SDK ignores request; ensure menu is disabled. |
| Group Chat      | Blocking affects only 1:1 communication.      |
| Network Failure | Observe error callbacks and retry as needed.  |

## Error Handling

* Handle errors from `blockUsers` and `unblockUsers` callbacks by showing alerts or retry prompts.
* Ensure UI state reverts on failure.

## Group vs. User-Level Differences

| Scenario             | UI Behavior                           |
| :------------------- | :------------------------------------ |
| `ReceiverType.USER`  | Block/unblock enabled.                |
| `ReceiverType.GROUP` | Block option ignored; chat continues. |

## Summary / Feature Matrix

| Feature            | Component / Method                 |
| :----------------- | :--------------------------------- |
| Check block state  | `User.isBlockedByMe()`             |
| Block user         | `CometChat.blockUsers()`           |
| Unblock user       | `CometChat.unblockUsers()`         |
| Update UI          | `updateUserBlockStatus()`          |
| Profile block menu | `UserDetailActivity.blockMenuItem` |

## Next Steps & Further Reading

<CardGroup>
  <Card title="Android Sample App (Kotlin)">
    Explore this feature in the CometChat SampleApp:
    [GitHub → SampleApp](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin)
  </Card>
</CardGroup>


# Call Log Details
Source: https://www.cometchat.com/docs/ui-kit/android/guide-call-log-details

Build a call log details screen showing metadata, participants, join/leave history, and recordings.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                              |
  | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
  | Packages       | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack`                                                               |
  | Key components | `CometChatCallLogs`, `CometChatCallLogDetails`, `CallDetailsActivity`, `CallDetailsViewModel`                                      |
  | Purpose        | Build a call log details screen showing metadata, participants, join/leave history, and recordings.                                |
  | Related        | [Call Logs](/docs/ui-kit/android/call-logs), [Call Buttons](/docs/ui-kit/android/call-buttons), [All Guides](/docs/ui-kit/android/guide-overview) |
</Accordion>

Build a detailed Call Log Details screen in your Android app using CometChat's UI Kit and Calls SDK, displaying metadata, participants, join/leave history, and recordings for full transparency and auditing.

## Overview

When a user taps a call entry, the Call Details screen shows:

* **Metadata:** Call type, duration, timestamp, and status.
* **Participants:** List of users who joined the call.
* **History:** Chronological join/leave events.
* **Recordings:** Playback links for any recorded calls.

This feature is essential for support, moderation, and post-call reviews.

## Prerequisites

* Android Studio project targeting API 28+.
* **CometChat Android UI Kit v6** (`com.cometchat:chatuikit-kotlin` or `com.cometchat:chatuikit-jetpack`) and **CometChat Calls SDK** added in `build.gradle`.
* A logged-in CometChat user (`CometChat.getLoggedInUser()` non-null).
* Required permissions in `AndroidManifest.xml`: Internet, Camera, Microphone.
* ViewBinding enabled or equivalent view setup.

## Components

| Component / Class               | Role                                                                        |
| :------------------------------ | :-------------------------------------------------------------------------- |
| `CallsFragment`                 | Displays the list of recent calls using `CometChatCallLogs` component.      |
| `HomeActivity`                  | Hosts bottom navigation; loads `CallsFragment` for the Calls tab.           |
| `CallDetailsActivity`           | Container for the call details UI with tab navigation.                      |
| `CallDetailsTabFragmentAdapter` | Adapter for `ViewPager2` managing detail tabs.                              |
| `CometChatCallLogDetails`       | UI Kit widget that renders metadata, participants, history, and recordings. |
| `CallDetailsViewModel`          | ViewModel fetching call data and exposing it via StateFlow.                 |

## Integration Steps

### 1. Show Call Logs Using `CometChatCallLogs`

Use the UI Kit's `CometChatCallLogs` component to display recent calls.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml fragment_calls.xml lines theme={null}
    <?xml version="1.0" encoding="utf-8"?>
    <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:orientation="vertical">

        <com.cometchat.uikit.kotlin.presentation.calls.calllogs.CometChatCallLogs
            android:id="@+id/call_logs"
            android:layout_width="match_parent"
            android:layout_height="match_parent" />

    </LinearLayout>
    ```

    Handle call log item clicks to navigate to the details screen:

    ```kotlin CallsFragment.kt lines theme={null}
    // CallsFragment.kt
    val callLogs = view.findViewById<CometChatCallLogs>(R.id.call_logs)
    callLogs.setOnItemClick { _, _, callLog ->
        val intent = Intent(activity, CallDetailsActivity::class.java)
        intent.putExtra("callLog", Gson().toJson(callLog))
        intent.putExtra("initiator", Gson().toJson(callLog.initiator))
        intent.putExtra("receiver", Gson().toJson(callLog.receiver))
        startActivity(intent)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin CallsScreen.kt lines theme={null}
    // CallsScreen.kt
    import com.cometchat.uikit.compose.presentation.calls.calllogs.CometChatCallLogs

    @Composable
    fun CallsScreen(navController: NavController) {
        CometChatCallLogs(
            onItemClick = { callLog ->
                navController.navigate("call_details/${Gson().toJson(callLog)}")
            }
        )
    }
    ```
  </Tab>
</Tabs>

### 2. Load `CallsFragment` in `HomeActivity`

Display the Calls tab via bottom navigation.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin HomeActivity.kt lines theme={null}
    // HomeActivity.kt
    bottomNav.setOnItemSelectedListener { item ->
        val frag = if (item.itemId == R.id.nav_calls)
            CallsFragment()
        else
            MessagesFragment()
        supportFragmentManager
            .beginTransaction()
            .replace(R.id.container, frag)
            .commit()
        true
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin HomeScreen.kt lines theme={null}
    // HomeScreen.kt
    @Composable
    fun HomeScreen(navController: NavController) {
        var selectedTab by remember { mutableIntStateOf(0) }

        Scaffold(
            bottomBar = {
                NavigationBar {
                    NavigationBarItem(
                        selected = selectedTab == 0,
                        onClick = { selectedTab = 0 },
                        icon = { Icon(Icons.Default.Chat, "Chats") },
                        label = { Text("Chats") }
                    )
                    NavigationBarItem(
                        selected = selectedTab == 1,
                        onClick = { selectedTab = 1 },
                        icon = { Icon(Icons.Default.Call, "Calls") },
                        label = { Text("Calls") }
                    )
                }
            }
        ) { padding ->
            when (selectedTab) {
                0 -> ConversationScreen(navController, Modifier.padding(padding))
                1 -> CallsScreen(navController)
            }
        }
    }
    ```
  </Tab>
</Tabs>

### 3. Configure `CallDetailsActivity`

Initialize the detail screen with tabs for metadata, participants, history, and recordings.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin CallDetailsActivity.kt lines theme={null}
    // CallDetailsActivity.kt
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityCallDetailsBinding.inflate(layoutInflater)
        setContentView(binding.root)

        val callLog = Gson().fromJson(
            intent.getStringExtra("callLog"), CallLog::class.java
        )
        viewModel = ViewModelProvider(this)[CallDetailsViewModel::class.java]
        viewModel.setCallLog(callLog)

        // Setup ViewPager2 & TabLayout
        binding.viewPager.adapter = CallDetailsTabFragmentAdapter(this, callLog)
        TabLayoutMediator(binding.tabs, binding.viewPager) { tab, pos ->
            tab.text = when (pos) {
                0 -> "Participants"
                1 -> "History"
                else -> "Recordings"
            }
        }.attach()
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin CallDetailsScreen.kt lines theme={null}
    // CallDetailsScreen.kt
    @Composable
    fun CallDetailsScreen(callLogJson: String) {
        val callLog = remember { Gson().fromJson(callLogJson, CallLog::class.java) }
        var selectedTab by remember { mutableIntStateOf(0) }
        val tabs = listOf("Participants", "History", "Recordings")

        Column {
            TabRow(selectedTabIndex = selectedTab) {
                tabs.forEachIndexed { index, title ->
                    Tab(
                        selected = selectedTab == index,
                        onClick = { selectedTab = index },
                        text = { Text(title) }
                    )
                }
            }

            when (selectedTab) {
                0 -> ParticipantsTab(callLog)
                1 -> HistoryTab(callLog)
                2 -> RecordingsTab(callLog)
            }
        }
    }
    ```
  </Tab>
</Tabs>

### 4. Implement `CometChatCallLogDetails` Component

Use the UI Kit widget for an all-in-one detail view.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val detailsView = CometChatCallLogDetails(this)
    detailsView.setCall(callLog)
    setContentView(detailsView)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.compose.presentation.calls.calllogdetails.CometChatCallLogDetails

    @Composable
    fun CallLogDetailsScreen(callLog: CallLog) {
        CometChatCallLogDetails(callLog = callLog)
    }
    ```
  </Tab>
</Tabs>

## Implementation Flow

1. **CallsFragment** fetches and displays call logs list.
2. User taps a call → navigates to **CallDetailsActivity** / **CallDetailsScreen** with call data.
3. Detail screen initializes ViewModel, ViewPager2/TabRow, and TabLayout.
4. Tab fragments/composables render participants, join/leave history, and recordings.
5. **CometChatCallLogDetails** can be used as a single-widget alternative.

## Customization Options

* Style tabs and headers via `CometChatTheme` or custom attributes.
* Override individual fragments/composables for additional data (e.g., call notes).
* Control visibility of tabs based on call type or recording availability.

## Filtering & Edge Cases

* **Missed Calls:** Use `CallsRequestBuilder().setTypes(CallType.MISSED)` to filter.
* **No Recordings:** Hide or disable the Recordings tab.
* **Blocked Users:** Disable profile links in Participants tab.

## Error Handling

* Observe `StateFlow<Throwable>` in `CallDetailsViewModel` to show retry UIs.
* Use `detailsView.setOnError()` and `setOnEmpty()` for fallback views in UI Kit widget.

## Summary / Feature Matrix

| Feature                      | Component / Method                                    |
| :--------------------------- | :---------------------------------------------------- |
| Display call logs list       | `CometChatCallLogs` in **CallsFragment**              |
| Navigate to detail screen    | Intent / Compose navigation + **CallDetailsActivity** |
| Render detail tabs           | **CallDetailsTabFragmentAdapter** / Compose `TabRow`  |
| Single-widget detail view    | **CometChatCallLogDetails**                           |
| Theming & styling            | `CometChatTheme`, custom styles                       |
| Error & empty-state handling | `setOnError()`, `setOnEmpty()`                        |

<CardGroup>
  <Card title="Android Sample App (Kotlin)">
    Explore this feature in the CometChat SampleApp:
    [GitHub → SampleApp](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin)
  </Card>
</CardGroup>


# Group Management
Source: https://www.cometchat.com/docs/ui-kit/android/guide-group-chat

Implement group creation, joining, member management, banning, scope changes, and ownership transfer.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                                                         |
  | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Packages       | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack`                                                                                                                          |
  | Key components | `CometChat.createGroup()`, `CometChat.joinGroup()`, `CometChat.addMembersToGroup()`, `CometChat.banGroupMember()`, `CometChat.updateGroupMemberScope()`, `CometChat.transferGroupOwnership()` |
  | Purpose        | Implement group creation, joining, member management, banning, scope changes, and ownership transfer.                                                                                         |
  | Related        | [Groups](/docs/ui-kit/android/groups), [Group Members](/docs/ui-kit/android/group-members), [All Guides](/docs/ui-kit/android/guide-overview)                                                                |
</Accordion>

Enable seven core group-management features in your Android app using CometChat UIKit v6:

* **Create Group**
* **Join Group**
* **View Members**
* **Add Member**
* **Ban Member**
* **Change Member Scope**
* **Transfer Ownership**

These moderation tools transform a static chat into a dynamic, manageable experience, all accessible via a clean UI.

## Overview

A user can create or join a group, then open a dialog to:

* View current members.
* Add or ban participants.
* Change member roles (e.g., member, moderator).
* Delegate group ownership.

Typically, a FloatingActionButton (FAB) or menu item launches the group-management dialog, which uses CometChat Core SDK calls under the hood.

## Prerequisites

* Android Studio project with **CometChat Android UI Kit v6** (`com.cometchat:chatuikit-kotlin` or `com.cometchat:chatuikit-jetpack`) and **CometChat Chat SDK** in `build.gradle`.
* Internet permission in `AndroidManifest.xml`.
* Valid CometChat **App ID**, **Region**, and **Auth Key** configured via `UIKitSettings`.
* User logged in with `CometChatUIKit.login()`.
* A `MessagesActivity` (or `ConversationActivity`) and an optional `GroupDetailsActivity` in your flow.

## Components

| Component / Class                       | Role                                             |
| :-------------------------------------- | :----------------------------------------------- |
| `FloatingActionButton`                  | Triggers the group-management options dialog.    |
| `GroupMembersRequest`                   | Fetches current group members.                   |
| `UsersRequest`                          | Fetches all app users for the "Add Member" list. |
| `CometChat.createGroup(...)`            | Creates a new public or private group.           |
| `CometChat.joinGroup(...)`              | Joins an existing group by GUID.                 |
| `CometChat.addMembersToGroup(...)`      | Adds selected users to the group.                |
| `CometChat.banGroupMember(...)`         | Bans a member from the group.                    |
| `CometChat.updateGroupMemberScope(...)` | Changes a member's role (scope).                 |
| `CometChat.transferGroupOwnership(...)` | Delegates group ownership to another member.     |

## Integration Steps

### 1. Layout/UI Setup

Add a FAB to launch the group-management dialog.

```xml lines theme={null}
<!-- activity_message.xml -->
<com.google.android.material.floatingactionbutton.FloatingActionButton
  android:id="@+id/fab_group_actions"
  android:layout_width="wrap_content"
  android:layout_height="wrap_content"
  android:layout_gravity="end|bottom"
  android:src="@drawable/ic_group_actions" />
```

### 2. Wiring UI in Activity

Initialize UIKit views and respond to FAB clicks.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin MessagesActivity.kt lines theme={null}
    // In MessagesActivity.kt
    val fab = findViewById<FloatingActionButton>(R.id.fab_group_actions)
    fab.setOnClickListener { showGroupActionsDialog() }

    private fun showGroupActionsDialog() {
        // Present options: Create, Join, View Members, etc.
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin MessagesScreen.kt lines theme={null}
    // In MessagesScreen.kt
    @Composable
    fun GroupActionsButton(onAction: (String) -> Unit) {
        var showDialog by remember { mutableStateOf(false) }

        FloatingActionButton(onClick = { showDialog = true }) {
            Icon(Icons.Default.Group, contentDescription = "Group Actions")
        }

        if (showDialog) {
            GroupActionsDialog(
                onDismiss = { showDialog = false },
                onAction = onAction
            )
        }
    }
    ```
  </Tab>
</Tabs>

### 3. Create & Join Group

Allow users to create or join a group via Core SDK.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Create Group
    CometChat.createGroup(
        Group(groupGuid, groupName, CometChatConstants.GROUP_TYPE_PUBLIC, ""),
        object : CometChat.CallbackListener<Group>() {
            override fun onSuccess(group: Group) { /* handle success */ }
            override fun onError(e: CometChatException?) { /* handle error */ }
        }
    )

    // Join Group
    CometChat.joinGroup(
        groupGuid,
        CometChatConstants.GROUP_TYPE_PUBLIC,
        "",
        object : CometChat.CallbackListener<Group>() {
            override fun onSuccess(group: Group) { /* handle success */ }
            override fun onError(e: CometChatException?) { /* handle error */ }
        }
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // In GroupViewModel.kt
    fun createGroup(guid: String, name: String) {
        CometChat.createGroup(
            Group(guid, name, CometChatConstants.GROUP_TYPE_PUBLIC, ""),
            object : CometChat.CallbackListener<Group>() {
                override fun onSuccess(group: Group) { _createdGroup.value = group }
                override fun onError(e: CometChatException?) { _error.value = e }
            }
        )
    }

    fun joinGroup(guid: String) {
        CometChat.joinGroup(
            guid, CometChatConstants.GROUP_TYPE_PUBLIC, "",
            object : CometChat.CallbackListener<Group>() {
                override fun onSuccess(group: Group) { _joinedGroup.value = group }
                override fun onError(e: CometChatException?) { _error.value = e }
            }
        )
    }
    ```
  </Tab>
</Tabs>

### 4. View Group Members

Fetch and display the current member list.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val membersRequest = GroupMembersRequest.Builder(groupGuid).setLimit(50).build()
    membersRequest.fetchNext(object : CometChat.CallbackListener<List<GroupMember>>() {
        override fun onSuccess(members: List<GroupMember>) {
            showMembersDialog(members)
        }
        override fun onError(e: CometChatException?) {}
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // In GroupViewModel.kt
    private val _members = MutableStateFlow<List<GroupMember>>(emptyList())
    val members: StateFlow<List<GroupMember>> = _members.asStateFlow()

    fun fetchMembers(groupGuid: String) {
        val request = GroupMembersRequest.Builder(groupGuid).setLimit(50).build()
        request.fetchNext(object : CometChat.CallbackListener<List<GroupMember>>() {
            override fun onSuccess(members: List<GroupMember>) {
                _members.value = members
            }
            override fun onError(e: CometChatException?) {}
        })
    }
    ```
  </Tab>
</Tabs>

### 5. Add Member

Select users not in the group and add them.

```kotlin lines theme={null}
CometChat.addMembersToGroup(
    groupGuid,
    selectedUids,
    CometChatConstants.SCOPE_PARTICIPANT,
    object : CometChat.CallbackListener<HashMap<String, String>>() {
        override fun onSuccess(result: HashMap<String, String>) { /* handle result */ }
        override fun onError(e: CometChatException?) { /* handle error */ }
    }
)
```

### 6. Ban Member, Change Scope & Transfer Ownership

Perform moderation actions on selected members.

```kotlin lines theme={null}
// Ban Member
CometChat.banGroupMember(
    uid, groupGuid,
    object : CometChat.CallbackListener<String>() {
        override fun onSuccess(result: String) { /* handle success */ }
        override fun onError(e: CometChatException?) { /* handle error */ }
    }
)

// Change Scope
CometChat.updateGroupMemberScope(
    uid, groupGuid, CometChatConstants.SCOPE_MODERATOR,
    object : CometChat.CallbackListener<String>() {
        override fun onSuccess(result: String) { /* handle success */ }
        override fun onError(e: CometChatException?) { /* handle error */ }
    }
)

// Transfer Ownership
CometChat.transferGroupOwnership(
    uid, groupGuid,
    object : CometChat.CallbackListener<String>() {
        override fun onSuccess(result: String) { /* handle success */ }
        override fun onError(e: CometChatException?) { /* handle error */ }
    }
)
```

## Implementation Flow Summary

| Step | Action                                     |
| :--- | :----------------------------------------- |
| 1    | User taps FAB → `showGroupActionsDialog()` |
| 2    | Select operation (e.g., View Members)      |
| 3    | Fetch data via `GroupMembersRequest`       |
| 4    | Call Core SDK method for chosen operation  |
| 5    | Show success or error feedback             |

## Customization Options

* Use a **BottomSheetDialog** instead of a standard dialog.
* Implement **multi-select** for bulk actions (e.g., add multiple members).
* Replace default **dialogs** with custom **RecyclerView** lists or Compose `LazyColumn`.
* Control **permissions**: show options only to admins or owners.

## Error Handling & Edge Cases

* **Not in Group:** Disable join option if user is already member.
* **Permission Denied:** Only show ban/transfer options to group admins.
* **Empty Lists:** Display an empty-state view if no members or users.
* **Pagination:** Implement `fetchNext()` in scroll listeners for large groups.

## Feature Matrix

| Feature             | SDK Method                           | Selection Source   |
| :------------------ | :----------------------------------- | :----------------- |
| Create Group        | `CometChat.createGroup()`            | Dialog input       |
| Join Group          | `CometChat.joinGroup()`              | Dialog input       |
| View Members        | `GroupMembersRequest.fetchNext()`    | Group members list |
| Add Member          | `CometChat.addMembersToGroup()`      | App users list     |
| Ban Member          | `CometChat.banGroupMember()`         | Group members list |
| Change Member Scope | `CometChat.updateGroupMemberScope()` | Group members list |
| Transfer Ownership  | `CometChat.transferGroupOwnership()` | Group members list |

<CardGroup>
  <Card title="Android Sample App (Kotlin)">
    Explore this feature in the CometChat SampleApp:
    [GitHub → SampleApp](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin)
  </Card>
</CardGroup>


# Message Privately
Source: https://www.cometchat.com/docs/ui-kit/android/guide-message-privately

Allow users to start a private one-on-one chat from a user profile or list screen.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                                                              |
  | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Packages       | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack`                                                                                                                               |
  | Key components | `CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageHeader`, `CometChat.sendMessage()`                                                                                            |
  | Purpose        | Allow users to start a private one-on-one chat from a user profile or list screen.                                                                                                                 |
  | Related        | [Message List](/docs/ui-kit/android/message-list), [Message Composer](/docs/ui-kit/android/message-composer), [Message Header](/docs/ui-kit/android/message-header), [All Guides](/docs/ui-kit/android/guide-overview) |
</Accordion>

Allow users to initiate a private one-on-one chat from another user's profile or list screen using CometChat's Android UI Kit.

## Overview

The **Message Privately** feature streamlines direct messaging by enabling:

* Quick entry into a one-on-one conversation from a user context.
* Automatic conversation creation if none exists.
* Optional initial message send to surface the chat in lists.

Users tap **Message Privately** → launch `MessagesActivity` with the target user's UID → chat UI loads.

## Prerequisites

* Android Studio project with CometChat Android UI Kit v6 (`com.cometchat:chatuikit-kotlin` or `com.cometchat:chatuikit-jetpack`) added to `build.gradle`.
* Valid CometChat **App ID**, **Auth Key**, and **Region** initialized.
* `<uses-permission android:name="android.permission.INTERNET"/>` in `AndroidManifest.xml`.
* Users created in your CometChat app.
* User must be logged in via `CometChatUIKit.login()` before invoking this feature.
* Existing `MessagesActivity` capable of handling one-on-one chats.

## Components

| Component / Class         | Responsibility                                                       |
| :------------------------ | :------------------------------------------------------------------- |
| `UserDetailsActivity`     | Shows user profile UI and **Message Privately** button.              |
| `MessagesActivity`        | Chat screen for one-on-one conversation with a `User`.               |
| `MainActivity`            | (Optional) entry point for sending initial message programmatically. |
| `CometChatUIKit.login()`  | Authenticates the current user session.                              |
| `CometChat.sendMessage()` | Sends a dummy text message to initialize conversation.               |

## Integration Steps

### 1. Launch One-on-One Chat from Profile

Navigate from `UserDetailsActivity` to `MessagesActivity` with the selected user.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // In UserDetailsActivity.kt
    import com.cometchat.uikit.core.CometChatUIKit

    binding.messagePrivatelyBtn.setOnClickListener {
        val intent = Intent(this, MessagesActivity::class.java)
        intent.putExtra(getString(R.string.app_user), Gson().toJson(user))
        startActivity(intent)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // In UserDetailsScreen.kt
    @Composable
    fun MessagePrivatelyButton(user: User, navController: NavController) {
        Button(onClick = {
            navController.navigate("messages/${Gson().toJson(user)}")
        }) {
            Text("Message Privately")
        }
    }
    ```
  </Tab>
</Tabs>

### 2. Handle Incoming Intent in Chat Screen

Deserialize the `User` JSON extra and configure the chat UI.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // In MessagesActivity.kt
    import com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader
    import com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
    import com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_messages)

        val userJson = intent.getStringExtra(getString(R.string.app_user))
        if (userJson != null) {
            val user = Gson().fromJson(userJson, User::class.java)
            messageHeader.setUser(user)
            messageList.setUser(user)
            composer.setUser(user)
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // In MessagesScreen.kt
    import com.cometchat.uikit.compose.presentation.messageheader.ui.CometChatMessageHeader
    import com.cometchat.uikit.compose.presentation.messagelist.ui.CometChatMessageList
    import com.cometchat.uikit.compose.presentation.messagecomposer.ui.CometChatMessageComposer

    @Composable
    fun MessagesScreen(userJson: String) {
        val user = remember { Gson().fromJson(userJson, User::class.java) }

        Column(modifier = Modifier.fillMaxSize()) {
            CometChatMessageHeader(user = user)
            CometChatMessageList(
                user = user,
                modifier = Modifier.weight(1f)
            )
            CometChatMessageComposer(user = user)
        }
    }
    ```
  </Tab>
</Tabs>

### 3. (Optional) Programmatically Create Conversation

Send an initial greeting to ensure the chat appears in conversation lists.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // In MainActivity.kt
    val txtMessage = TextMessage(
        "cometchat-uid-2",
        "👋",
        CometChatConstants.RECEIVER_TYPE_USER
    )
    CometChat.sendMessage(txtMessage, object : CometChat.CallbackListener<BaseMessage>() {
        override fun onSuccess(msg: BaseMessage) {
            Log.d("SendMsg", "Initial message sent.")
        }
        override fun onError(e: CometChatException?) {
            Log.e("SendMsg", e?.message ?: "Error sending message")
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // In your ViewModel
    fun sendInitialMessage(receiverUid: String) {
        val txtMessage = TextMessage(
            receiverUid,
            "👋",
            CometChatConstants.RECEIVER_TYPE_USER
        )
        CometChat.sendMessage(txtMessage, object : CometChat.CallbackListener<BaseMessage>() {
            override fun onSuccess(msg: BaseMessage) {
                Log.d("SendMsg", "Initial message sent.")
            }
            override fun onError(e: CometChatException?) {
                Log.e("SendMsg", e?.message ?: "Error sending message")
            }
        })
    }
    ```
  </Tab>
</Tabs>

## Implementation Flow

| Step | Action                                               | Location                               |
| :--- | :--------------------------------------------------- | :------------------------------------- |
| 1    | Tap **Message Privately** button                     | `UserDetailsActivity`                  |
| 2    | Launch `MessagesActivity` with user JSON extra       | `UserDetailsActivity` onClick listener |
| 3    | Deserialize and bind `User` to UI Kit components     | `MessagesActivity.onCreate()`          |
| 4    | (Optional) Send initial message to surface chat list | `MainActivity.sendInitialMessage()`    |

## Customization Options

* **Button Text & Style:** Update `messagePrivatelyBtn` in `activity_user_details.xml`.
* **Intent Extras Key:** Use a custom key instead of `R.string.app_user`.
* **Dummy Message:** Customize initial message content or omit step if undesired.

## Edge Cases

| Condition                 | Behavior                                                      |
| :------------------------ | :------------------------------------------------------------ |
| User never chatted before | The conversation appears after the first message is sent.     |
| Target user blocked       | Composer hidden; consider showing unblock prompt.             |
| Invalid user data         | Guard against `null` JSON and show error UI or fallback.      |
| Missing JSON extra        | Do not initialize chat; optionally close screen with warning. |

## Summary / Feature Matrix

| Feature             | Component / Method                                 |
| :------------------ | :------------------------------------------------- |
| Launch private chat | Intent from `messagePrivatelyBtn`                  |
| Initialize chat UI  | `messageHeader.setUser()`, `messageList.setUser()` |
| Create conversation | `CometChat.sendMessage()` optional                 |

<CardGroup>
  <Card title="Android Sample App (Kotlin)">
    Explore this feature in the CometChat SampleApp:
    [GitHub → SampleApp](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin)
  </Card>
</CardGroup>


# New Chat
Source: https://www.cometchat.com/docs/ui-kit/android/guide-new-chat

Enable users to start one-on-one or group chats from a new chat screen with user and group browsing.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                          |
  | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Packages       | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack`                                                                                           |
  | Key components | `CometChatUsers`, `CometChatGroups`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageHeader`                                              |
  | Purpose        | Enable users to start one-on-one or group chats from a new chat screen with user and group browsing.                                                           |
  | Related        | [Users](/docs/ui-kit/android/users), [Groups](/docs/ui-kit/android/groups), [Conversations](/docs/ui-kit/android/conversations), [All Guides](/docs/ui-kit/android/guide-overview) |
</Accordion>

Enable users to start one-on-one or group chats by integrating CometChat's **New Chat** screen (`CometChatUsers` + `CometChatGroups`), providing a seamless flow from your conversation list to a specific chat.

## Overview

Users can tap the "+" icon in the conversation toolbar or bottom navigation to:

* Browse and search CometChat users.
* Browse and search CometChat groups.
* Select a user or group to launch a chat.

This streamlines contact/group discovery and boosts engagement by reducing friction in starting conversations.

## Prerequisites

* Android project with **CometChat UIKit Android v6** (`com.cometchat:chatuikit-kotlin` or `com.cometchat:chatuikit-jetpack`) added in `build.gradle`.
* CometChat credentials (**App ID**, **Auth Key**, **Region**) initialized.
* Navigation configured: `ConversationActivity` → `NewChatActivity` → `MessagesActivity`.
* Internet and network permissions granted in `AndroidManifest.xml`.

## Components

| Component / Class       | Role                                                              |
| :---------------------- | :---------------------------------------------------------------- |
| `ConversationActivity`  | Entry point; hosts "+" icon to launch New Chat screen.            |
| `NewChatActivity`       | Displays tabbed Users/Groups lists.                               |
| `activity_new_chat.xml` | Layout defining `TabLayout`, `CometChatUsers`, `CometChatGroups`. |
| `CometChatUsers`        | Lists and searches users; exposes `setOnItemClick()`.             |
| `CometChatGroups`       | Lists and searches groups; exposes `setOnItemClick()`.            |
| `UsersRequestBuilder`   | Configures user query filters (e.g. pagination).                  |
| `GroupsRequestBuilder`  | Configures group query filters (e.g. pagination).                 |
| `MessagesActivity`      | Chat UI for the selected user or group.                           |

## Integration Steps

### 1. Add Entry Point to New Chat

Show a "+" icon that launches `NewChatActivity`.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin ConversationActivity.kt lines theme={null}
    // In ConversationActivity.kt
    toolbar.inflateMenu(R.menu.conversation_menu)
    toolbar.setOnMenuItemClickListener { item ->
        if (item.itemId == R.id.action_new_chat) {
            startActivity(Intent(this, NewChatActivity::class.java))
            true
        } else false
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin ConversationScreen.kt lines theme={null}
    // In ConversationScreen.kt
    @Composable
    fun ConversationScreen(navController: NavController) {
        Scaffold(
            topBar = {
                TopAppBar(
                    title = { Text("Chats") },
                    actions = {
                        IconButton(onClick = { navController.navigate("new_chat") }) {
                            Icon(Icons.Default.Add, contentDescription = "New Chat")
                        }
                    }
                )
            }
        ) { padding ->
            CometChatConversations(
                modifier = Modifier.padding(padding),
                onItemClick = { conversation ->
                    navController.navigate("messages/${Gson().toJson(conversation)}")
                }
            )
        }
    }
    ```
  </Tab>
</Tabs>

### 2. Implement New Chat Screen

Build a tabbed interface with Users and Groups lists.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin NewChatActivity.kt lines theme={null}
    // In NewChatActivity.kt
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_new_chat)

        val tabs = findViewById<TabLayout>(R.id.tabLayout)
        val pager = findViewById<ViewPager2>(R.id.viewPager)
        val adapter = NewChatPagerAdapter(this)
        pager.adapter = adapter
        TabLayoutMediator(tabs, pager) { tab, pos ->
            tab.text = if (pos == 0) "Users" else "Groups"
        }.attach()
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin NewChatScreen.kt lines theme={null}
    // In NewChatScreen.kt
    @Composable
    fun NewChatScreen(navController: NavController) {
        var selectedTab by remember { mutableIntStateOf(0) }
        val tabs = listOf("Users", "Groups")

        Column {
            TabRow(selectedTabIndex = selectedTab) {
                tabs.forEachIndexed { index, title ->
                    Tab(
                        selected = selectedTab == index,
                        onClick = { selectedTab = index },
                        text = { Text(title) }
                    )
                }
            }

            when (selectedTab) {
                0 -> CometChatUsers(
                    onItemClick = { user ->
                        navController.navigate("messages/user/${Gson().toJson(user)}")
                    }
                )
                1 -> CometChatGroups(
                    onItemClick = { group ->
                        navController.navigate("messages/group/${Gson().toJson(group)}")
                    }
                )
            }
        }
    }
    ```
  </Tab>
</Tabs>

### 3. Handle User or Group Selection

Launch `MessagesActivity` when an item is tapped.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin NewChatActivity.kt lines theme={null}
    // In NewChatActivity.kt (Users fragment)
    cometChatUsers.setOnItemClick { view, position, user ->
        val intent = Intent(this, MessagesActivity::class.java)
        intent.putExtra("app_user", Gson().toJson(user))
        startActivity(intent)
    }

    // Similarly for CometChatGroups:
    cometChatGroups.setOnItemClick { view, position, group ->
        val intent = Intent(this, MessagesActivity::class.java)
        intent.putExtra("app_group", Gson().toJson(group))
        startActivity(intent)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // Handled inline via onItemClick lambdas in the NewChatScreen composable above
    ```
  </Tab>
</Tabs>

### 4. Open the Messages Screen

Read intent extras and configure chat UI.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin MessagesActivity.kt lines theme={null}
    // In MessagesActivity.kt
    import com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader
    import com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
    import com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_messages)

        val userJson = intent.getStringExtra("app_user")
        val groupJson = intent.getStringExtra("app_group")

        if (userJson != null) {
            val user = Gson().fromJson(userJson, User::class.java)
            messageHeader.setUser(user)
            messageList.setUser(user)
            composer.setUser(user)
        } else if (groupJson != null) {
            val group = Gson().fromJson(groupJson, Group::class.java)
            messageHeader.setGroup(group)
            messageList.setGroup(group)
            composer.setGroup(group)
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin MessagesScreen.kt lines theme={null}
    // In MessagesScreen.kt
    import com.cometchat.uikit.compose.presentation.messageheader.ui.CometChatMessageHeader
    import com.cometchat.uikit.compose.presentation.messagelist.ui.CometChatMessageList
    import com.cometchat.uikit.compose.presentation.messagecomposer.ui.CometChatMessageComposer

    @Composable
    fun MessagesScreen(userJson: String? = null, groupJson: String? = null) {
        val user = userJson?.let { Gson().fromJson(it, User::class.java) }
        val group = groupJson?.let { Gson().fromJson(it, Group::class.java) }

        Column(modifier = Modifier.fillMaxSize()) {
            if (user != null) {
                CometChatMessageHeader(user = user)
                CometChatMessageList(user = user, modifier = Modifier.weight(1f))
                CometChatMessageComposer(user = user)
            } else if (group != null) {
                CometChatMessageHeader(group = group)
                CometChatMessageList(group = group, modifier = Modifier.weight(1f))
                CometChatMessageComposer(group = group)
            }
        }
    }
    ```
  </Tab>
</Tabs>

## Implementation Flow

1. User taps the "+" icon → `NewChatActivity` launches (or Compose navigation).
2. Tabs switch between **Users** and **Groups**.
3. Selection triggers `MessagesActivity` with JSON payload.
4. Chat UI initializes with the passed user/group.
5. Real-time messaging begins via the UI Kit.

## Customization Options

* **Styling:** Apply `cometchatTheme` attributes to `TabLayout` and list items.
* **Filtering:** Customize `UsersRequestBuilder` / `GroupsRequestBuilder` (e.g., `hideBlockedUsers(true)`).
* **Navigation:** Replace default `MessagesActivity` with a custom screen.
* **Layout Tweaks:** Use `android:fitsSystemWindows="true"` to avoid overlap.

## Filtering & Edge Cases

* **Empty States:** Built-in empty views in `CometChatUsers` and `CometChatGroups`.
* **Protected Groups:** Prompt for password or disable selection.
* **Network Errors:** Observe error callbacks and show `Snackbar` messages.

## Error Handling

* Default loading and error states are handled by the UI Kit.
* Attach observers on `CometChatUsers` / `CometChatGroups` to handle failures.
* Use Toast or Snackbar for custom error feedback.

## Summary / Feature Matrix

| Feature                | Component / Method                             |
| :--------------------- | :--------------------------------------------- |
| Launch New Chat screen | Menu item click in `ConversationActivity`      |
| Tabbed lists           | `TabLayout` + `ViewPager2` or Compose `TabRow` |
| List/search users      | `CometChatUsers` + `UsersRequestBuilder`       |
| List/search groups     | `CometChatGroups` + `GroupsRequestBuilder`     |
| Selection handling     | `setOnItemClick()` / `onItemClick` lambda      |
| Initialize chat        | `messageHeader`, `messageList`, `composer`     |

## Next Steps & Further Reading

<CardGroup>
  <Card title="Android Sample App (Kotlin)">
    Explore this feature in the CometChat SampleApp:
    [GitHub → SampleApp](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin)
  </Card>
</CardGroup>


# Overview
Source: https://www.cometchat.com/docs/ui-kit/android/guide-overview

Index of task-oriented feature guides for the CometChat Android UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field      | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
  | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Packages   | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | Purpose    | Index of task-oriented feature guides for the Android UI Kit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
  | Sample app | [GitHub](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
  | Components | [Components Overview](/docs/ui-kit/android/components-overview)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
  | Guides     | [Block/Unblock](/docs/ui-kit/android/guide-block-unblock-user) · [Call Log Details](/docs/ui-kit/android/guide-call-log-details) · [Group Chat](/docs/ui-kit/android/guide-group-chat) · [Message Privately](/docs/ui-kit/android/guide-message-privately) · [New Chat](/docs/ui-kit/android/guide-new-chat) · [Search Messages](/docs/ui-kit/android/guide-search-messages) · [Threaded Messages](/docs/ui-kit/android/guide-threaded-messages) · [AI Agent](/docs/ui-kit/android/guide-ai-agent) · [Custom Text Formatter](/docs/ui-kit/android/custom-text-formatter-guide) · [Mentions Formatter](/docs/ui-kit/android/mentions-formatter-guide) · [ShortCut Formatter](/docs/ui-kit/android/shortcut-formatter-guide) |
</Accordion>

> This page indexes focused, task‑oriented feature guides for the Android UI Kit. Each guide shows how to implement a specific capability end‑to‑end using UIKit components. Guides include both **Kotlin (XML Views)** and **Jetpack Compose** examples where applicable.

## When to Use These Guides

Use these guides after completing the base [Getting Started](/docs/ui-kit/android/getting-started) setup. They help you layer additional UX without rewriting core chat flows.

The CometChat Android UI Kit is available in two modules:

| Module              | Description                                                        |
| :------------------ | :----------------------------------------------------------------- |
| `chatuikit-kotlin`  | Traditional XML-based Views for use with Activities and Fragments. |
| `chatuikit-jetpack` | Jetpack Compose components for declarative UI.                     |

## Guide Directory

| Guide                                                                | Description                                                                                                                          |
| :------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| [Block / Unblock User](/docs/ui-kit/android/guide-block-unblock-user)     | Let users block or unblock others in 1:1 chats; hides composer and shows unblock prompt while preventing outgoing/incoming messages. |
| [Call Log Details](/docs/ui-kit/android/guide-call-log-details)           | Detailed call insights screen: metadata, participants, join/leave history, and recordings.                                           |
| [Group Management](/docs/ui-kit/android/guide-group-chat)                 | Create/join groups, view members, add / ban users, change scopes, transfer ownership.                                                |
| [Message Privately](/docs/ui-kit/android/guide-message-privately)         | Launch a direct 1:1 chat from a profile/list; optionally send initial message to surface conversation.                               |
| [New Chat](/docs/ui-kit/android/guide-new-chat)                           | Unified entry for starting new 1:1 or group chats with tabbed Users / Groups search + navigation.                                    |
| [Threaded Messages](/docs/ui-kit/android/guide-threaded-messages)         | Threaded replies: open parent message context, list replies, compose with parent linkage.                                            |
| [Search Messages](/docs/ui-kit/android/guide-search-messages)             | Full-text message search across conversations with result routing and navigation.                                                    |
| [AI Agent](/docs/ui-kit/android/guide-ai-agent)                           | Build an AI-powered agent that responds to user messages using CometChat's AI features.                                              |
| [Custom Text Formatter](/docs/ui-kit/android/custom-text-formatter-guide) | Extend `CometChatTextFormatter` to build custom inline text patterns with tracking characters and suggestion lists.                  |
| [Mentions Formatter](/docs/ui-kit/android/mentions-formatter-guide)       | Format @mentions with styled tokens, suggestion lists, and click handling.                                                           |
| [ShortCut Formatter](/docs/ui-kit/android/shortcut-formatter-guide)       | Add shortcut text expansion to the message composer via the message-shortcuts extension.                                             |

Need another guide? Open a request via our [Support Portal](https://help.cometchat.com/hc/en-us/requests/new).

***

## Next Steps

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/ui-kit/android/getting-started">
    Set up the Android UI Kit
  </Card>

  <Card title="Components Overview" icon="puzzle-piece" href="/ui-kit/android/components-overview">
    Explore all UI components
  </Card>

  <Card title="Customization" icon="palette" href="/ui-kit/android/theme-introduction">
    Customize themes and styling
  </Card>

  <Card title="Events" icon="bolt" href="/ui-kit/android/events">
    Handle UI Kit events
  </Card>
</CardGroup>


# Search Messages
Source: https://www.cometchat.com/docs/ui-kit/android/guide-search-messages

Add full-text message search across conversations with result routing in CometChat Android UI Kit.

<Accordion title="Quick Reference">
  | Field          | Value                                                                                           |
  | -------------- | ----------------------------------------------------------------------------------------------- |
  | Packages       | `com.cometchat:chatuikit-kotlin-android` · `com.cometchat:chatuikit-compose-android`            |
  | Key components | `CometChatSearch`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageHeader` |
  | Purpose        | Full-text message search across conversations with result routing and navigation                |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin)        |
  | Related        | [Search Component](/docs/ui-kit/android/search), [All Guides](/docs/ui-kit/android/guide-overview)        |
</Accordion>

Search Messages lets users locate specific messages across conversations and groups using keyword search, then navigate directly to the result.

Before starting, complete the [Getting Started](/docs/ui-kit/android/getting-started) guide.

***

## Components

| Component / Class          | Role                                                     |
| :------------------------- | :------------------------------------------------------- |
| `CometChatSearch`          | Main search interface with filter chips and result lists |
| `CometChatMessageList`     | Displays messages in the selected conversation           |
| `CometChatMessageComposer` | Message input for the selected conversation              |
| `CometChatMessageHeader`   | Header bar showing conversation context                  |

***

## Integration Steps

### 1. Add CometChatSearch to your layout

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_search.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.search.ui.CometChatSearch
        android:id="@+id/cometchat_search"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin SearchScreen.kt lines theme={null}
    import com.cometchat.uikit.compose.presentation.search.ui.CometChatSearch

    @Composable
    fun SearchScreen(navController: NavController) {
        CometChatSearch(
            modifier = Modifier.fillMaxSize(),
            onConversationClick = { conversation ->
                navController.navigate("messages/${Gson().toJson(conversation)}")
            },
            onMessageClick = { message ->
                if (message.receiverType == CometChatConstants.RECEIVER_TYPE_USER) {
                    navController.navigate("messages/user/${(message.receiver as User).uid}/${message.id}")
                } else {
                    navController.navigate("messages/group/${(message.receiver as Group).guid}/${message.id}")
                }
            }
        )
    }
    ```
  </Tab>
</Tabs>

***

### 2. Handle conversation result clicks

When a user taps a conversation result, navigate to the message view for that conversation.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin SearchActivity.kt lines theme={null}
    val search: CometChatSearch = findViewById(R.id.cometchat_search)

    search.setOnConversationClicked { view, position, conversation ->
        val intent = Intent(this, ChatActivity::class.java)
        intent.putExtra("conversation", conversation)
        startActivity(intent)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin SearchScreen.kt lines theme={null}
    // Handled inline via onConversationClick lambda in the CometChatSearch composable above
    ```
  </Tab>
</Tabs>

***

### 3. Handle message result clicks

When a user taps a message result, navigate to the conversation and scroll to that message.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin SearchActivity.kt lines theme={null}
    search.setOnMessageClicked { view, position, message ->
        val intent = Intent(this, ChatActivity::class.java)
        if (message.receiverType == CometChatConstants.RECEIVER_TYPE_USER) {
            intent.putExtra("uid", (message.receiver as User).uid)
        } else {
            intent.putExtra("guid", (message.receiver as Group).guid)
        }
        intent.putExtra("messageId", message.id)
        startActivity(intent)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin SearchScreen.kt lines theme={null}
    // Handled inline via onMessageClick lambda in the CometChatSearch composable above
    ```
  </Tab>
</Tabs>

***

### 4. Scope search to a specific conversation (optional)

Restrict search results to a single user or group conversation.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Scope to a specific user conversation
    search.setUid("alice-uid")

    // Or scope to a specific group conversation
    search.setGuid("group-guid")
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // Scope to a specific user conversation
    CometChatSearch(
        uid = "alice-uid",
        modifier = Modifier.fillMaxSize(),
        onConversationClick = { /* handle click */ },
        onMessageClick = { /* handle click */ }
    )

    // Or scope to a specific group conversation
    CometChatSearch(
        guid = "group-guid",
        modifier = Modifier.fillMaxSize(),
        onConversationClick = { /* handle click */ },
        onMessageClick = { /* handle click */ }
    )
    ```
  </Tab>
</Tabs>

***

### 5. Configure search filters (optional)

Control which filter chips appear.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    search.setSearchFilters(
        listOf(
            UIKitConstants.SearchFilter.MESSAGES,
            UIKitConstants.SearchFilter.CONVERSATIONS
        )
    )
    search.setInitialSearchFilter(UIKitConstants.SearchFilter.MESSAGES)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.core.constants.SearchFilter

    CometChatSearch(
        searchFilters = listOf(
            SearchFilter.UNREAD,
            SearchFilter.GROUPS,
            SearchFilter.PHOTOS,
            SearchFilter.VIDEOS
        ),
        modifier = Modifier.fillMaxSize(),
        onConversationClick = { /* handle click */ },
        onMessageClick = { /* handle click */ }
    )
    ```
  </Tab>
</Tabs>

***

## Feature Matrix

| Feature              | Kotlin (XML Views)                 | Jetpack Compose                           |
| :------------------- | :--------------------------------- | :---------------------------------------- |
| Search interface     | `CometChatSearch` XML element      | `CometChatSearch()` composable            |
| Conversation results | `setOnConversationClicked`         | `onConversationClick` lambda              |
| Message results      | `setOnMessageClicked`              | `onMessageClick` lambda                   |
| Scoped search        | `setUid()` / `setGuid()`           | `uid` / `guid` parameters                 |
| Filter chips         | `setSearchFilters()`               | `searchFilters` parameter                 |
| Custom views         | `setEmptyView()`, `setErrorView()` | `emptyView`, `errorView` composable slots |

***

## Next Steps

<CardGroup>
  <Card title="Search" icon="magnifying-glass" href="/ui-kit/android/search">
    The search component reference
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/android/message-list">
    Display messages in a conversation
  </Card>

  <Card title="All Guides" icon="book" href="/ui-kit/android/guide-overview">
    Browse all feature and formatter guides
  </Card>

  <Card title="Sample App" icon="github" href="https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin">
    Full working sample application on GitHub
  </Card>
</CardGroup>


# Threaded Messages
Source: https://www.cometchat.com/docs/ui-kit/android/guide-threaded-messages

Implement threaded replies so users can respond to specific messages in a focused sub-conversation.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                                                                                                                                  |
  | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Packages       | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack`                                                                                                                                                   |
  | Key components | `CometChatThreadHeader`, `CometChatMessageList`, `CometChatMessageComposer`                                                                                                                                            |
  | Purpose        | Implement threaded replies so users can respond to specific messages in a focused sub-conversation.                                                                                                                    |
  | Related        | [Threaded Messages Header](/docs/ui-kit/android/threaded-messages-header), [Message List](/docs/ui-kit/android/message-list), [Message Composer](/docs/ui-kit/android/message-composer), [All Guides](/docs/ui-kit/android/guide-overview) |
</Accordion>

Implement threaded replies in your Android chat app using CometChat's UI Kit, enabling users to reply to specific messages in a focused sub-conversation.

## Overview

Threaded replies allow users to respond directly to a specific message in one-on-one or group chats, improving context and readability:

* Organizes related replies into a dedicated thread view.
* Mirrors functionality in Slack, Discord, and WhatsApp.
* Maintains clarity in active conversations.

Users tap a message → open thread screen → view parent message + replies → compose within thread.

## Prerequisites

* Android project in Android Studio.
* CometChat Android UI Kit v6 (`com.cometchat:chatuikit-kotlin` or `com.cometchat:chatuikit-jetpack`) added to your `build.gradle`.
* Valid CometChat **App ID**, **Auth Key**, and **Region** initialized.
* `<uses-permission android:name="android.permission.INTERNET"/>` in `AndroidManifest.xml`.
* Logged-in user via `CometChatUIKit.login()`.
* Existing `MessagesActivity` using `CometChatMessageList`.

## Components

| Component                     | Role                                                          |
| ----------------------------- | ------------------------------------------------------------- |
| `activity_thread_message.xml` | Defines thread UI: header, message list, composer, unblock.   |
| `ThreadMessageActivity`       | Hosts thread screen; initializes UI & ViewModel.              |
| `ThreadMessageViewModel`      | Fetches parent message & thread replies; manages state.       |
| `CometChatMessageList`        | Displays threaded replies when given parent message ID.       |
| `CometChatMessageComposer`    | Composes and sends replies with `parentMessageId`.            |
| `CometChatThreadHeader`       | Displays the parent message context at the top of the thread. |

## Integration Steps

### Step 1: Add Thread Layout

Create `res/layout/activity_thread_message.xml`:

```xml activity_thread_message.xml lines theme={null}
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical">

    <com.cometchat.uikit.kotlin.presentation.threadheader.ui.CometChatThreadHeader
        android:id="@+id/threadHeader"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    <com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
        android:id="@+id/threadMessageList"
        android:layout_width="match_parent"
        android:layout_height="0dp"
        android:layout_weight="1" />

    <LinearLayout
        android:id="@+id/unblockLayout"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:gravity="center"
        android:padding="12dp"
        android:visibility="gone">

        <Button
            android:id="@+id/unblockBtn"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:text="Unblock" />
    </LinearLayout>

    <com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
        android:id="@+id/threadComposer"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

</LinearLayout>
```

### Step 2: Set up ThreadMessageActivity

Initialize UI & handle blocked-user flows:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.kotlin.presentation.threadheader.ui.CometChatThreadHeader
    import com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
    import com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer

    class ThreadMessageActivity : AppCompatActivity() {
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.activity_thread_message)
            val header = findViewById<CometChatThreadHeader>(R.id.threadHeader)
            val messageList = findViewById<CometChatMessageList>(R.id.threadMessageList)
            val composer = findViewById<CometChatMessageComposer>(R.id.threadComposer)
            val unblock = findViewById<View>(R.id.unblockLayout)

            val rawMessage = intent.getStringExtra("raw_json")
            val viewModel = ViewModelProvider(this)[ThreadMessageViewModel::class.java]
            if (rawMessage != null) {
                val parentMessage = BaseMessage.processMessage(JSONObject(rawMessage))
                viewModel.setParentMessage(parentMessage)
            }

            lifecycleScope.launch {
                viewModel.parentMessage.collect { msg ->
                    msg?.let {
                        header.setParentMessage(it)
                        messageList.setParentMessage(it.id)
                        composer.setParentMessageId(it.id)
                    }
                }
            }

            // Handle blocked user
            if (isBlockedByMe) {
                composer.visibility = View.GONE
                unblock.visibility = View.VISIBLE
            }
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.compose.presentation.threadheader.ui.CometChatThreadHeader
    import com.cometchat.uikit.compose.presentation.messagelist.ui.CometChatMessageList
    import com.cometchat.uikit.compose.presentation.messagecomposer.ui.CometChatMessageComposer

    @Composable
    fun ThreadMessageScreen(rawJson: String, isBlockedByMe: Boolean = false) {
        val parentMessage = remember {
            BaseMessage.processMessage(JSONObject(rawJson))
        }

        Column(modifier = Modifier.fillMaxSize()) {
            CometChatThreadHeader(parentMessage = parentMessage)

            CometChatMessageList(
                parentMessageId = parentMessage.id,
                modifier = Modifier.weight(1f)
            )

            if (isBlockedByMe) {
                UnblockPrompt(onUnblock = { /* unblock logic */ })
            } else {
                CometChatMessageComposer(parentMessageId = parentMessage.id)
            }
        }
    }
    ```
  </Tab>
</Tabs>

### Step 3: Create ThreadMessageViewModel

Store parent message and expose via StateFlow:

```kotlin lines theme={null}
class ThreadMessageViewModel : ViewModel() {
    private val _parentMessage = MutableStateFlow<BaseMessage?>(null)
    val parentMessage: StateFlow<BaseMessage?> = _parentMessage.asStateFlow()
    var id: Long = 0
        private set

    fun setParentMessage(message: BaseMessage?) {
        if (message != null) {
            id = message.id
            _parentMessage.value = message
        }
    }
}
```

### Step 4: Hook Thread Entry from Message List

In your `MessagesActivity`, capture thread icon taps:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setOnThreadRepliesClick { context, baseMessage, template ->
        val intent = Intent(context, ThreadMessageActivity::class.java)
        intent.putExtra("raw_json", baseMessage.rawMessage.toString())
        intent.putExtra("reply_count", baseMessage.replyCount)
        context.startActivity(intent)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        onThreadRepliesClick = { baseMessage, template ->
            navController.navigate("thread/${baseMessage.rawMessage}")
        },
        modifier = Modifier.weight(1f)
    )
    ```
  </Tab>
</Tabs>

## Implementation Flow

1. User taps thread icon on a message.
2. `Intent` launches `ThreadMessageActivity` with raw message JSON (or Compose navigation).
3. ViewModel stores parent message and exposes via StateFlow.
4. Header & `MessageList` render parent + replies.
5. Composer sends new replies under the parent message.
6. Live updates flow automatically via UI Kit.

## Customization Options

* **Styling:** Override theme attributes or call setter methods on views.
* **Header Height:** `threadHeader.setMaxHeight(...)`.
* **Hide Reactions:** `threadHeader.setReactionVisibility(View.GONE)`.

## Filtering & Edge Cases

* **Group Membership:** Verify membership before enabling composer.
* **Empty Thread:** Show placeholder if no replies.
* **Blocked Users:** Composer hidden; use unblock layout.

## Blocked-User Handling

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    if (user.isBlockedByMe) {
        composer.visibility = View.GONE
        unblockLayout.visibility = View.VISIBLE
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    if (user.isBlockedByMe) {
        UnblockPrompt(onUnblock = { /* unblock logic */ })
    } else {
        CometChatMessageComposer(parentMessageId = parentMessage.id)
    }
    ```
  </Tab>
</Tabs>

## Group vs. User-Level Differences

| Scenario             | Behavior                                |
| -------------------- | --------------------------------------- |
| `ReceiverType.USER`  | Direct replies allowed if not blocked.  |
| `ReceiverType.GROUP` | Checks membership before thread access. |
| Blocked User         | Composer hidden; unblock layout shown.  |
| Not in Group         | Show option to join group first.        |

## Summary / Feature Matrix

| Feature                 | Component / Method                                    |
| ----------------------- | ----------------------------------------------------- |
| Show thread option      | `setOnThreadRepliesClick()`                           |
| Display thread messages | `messageList.setParentMessage(parentMessage.getId())` |
| Show parent message     | `header.setParentMessage(parentMessage)`              |
| Compose reply           | `composer.setParentMessageId(parentMessage.getId())`  |
| Handle blocked users    | `isBlockedByMe()`, hide composer + show unblock UI    |

## Next Steps & Further Reading

<CardGroup>
  <Card title="Android Sample App (Kotlin)">
    Explore this feature in the CometChat SampleApp:
    [GitHub → SampleApp](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin)
  </Card>
</CardGroup>


# Incoming Call
Source: https://www.cometchat.com/docs/ui-kit/android/incoming-call

Full-screen incoming call banner with caller avatar, name, call type indicator, and accept/reject buttons.

`CometChatIncomingCall` renders when the logged-in user receives an incoming voice or video call, displaying the caller's information and providing accept/reject controls.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatIncomingCall` is a call-handling component. It renders the incoming call screen and transitions to the ongoing call screen when the user accepts. Wire it to `CometChatOngoingCallActivity` after the user accepts the call.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_call.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.incomingcall.CometChatIncomingCall
        android:id="@+id/incoming_call"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    ```kotlin lines theme={null}
    val incomingCall = findViewById<CometChatIncomingCall>(R.id.incoming_call)
    incomingCall.setCall(call)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatIncomingCall(
        call = call
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add to your layout XML:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.incomingcall.CometChatIncomingCall
        android:id="@+id/incoming_call"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    Set the `Call` object — this is required:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.layout_activity)

        val incomingCall = findViewById<CometChatIncomingCall>(R.id.incoming_call)
        incomingCall.setCall(call)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    @Composable
    fun IncomingCallScreen() {
        CometChatIncomingCall(
            call = call
        )
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

***

## Actions and Events

### Callback Methods

#### `onAcceptClick`

Fires when the user taps the accept button.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    incomingCall.setOnAcceptClick {
        // Custom accept logic
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatIncomingCall(
        call = call,
        onAcceptClick = { /* custom accept logic */ }
    )
    ```
  </Tab>
</Tabs>

#### `onRejectClick`

Fires when the user taps the reject button.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    incomingCall.setOnRejectClick {
        // Custom reject logic
        finish()
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatIncomingCall(
        call = call,
        onRejectClick = { /* custom reject logic */ }
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    incomingCall.setOnError { exception ->
        Log.e("IncomingCall", "Error: ${exception.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatIncomingCall(
        call = call,
        onError = { exception ->
            Log.e("IncomingCall", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

### Global UI Events (CometChatCallEvents)

| Event            | Fires when         | Payload |
| ---------------- | ------------------ | ------- |
| `ccCallAccepted` | A call is accepted | `Call`  |
| `ccCallRejected` | A call is rejected | `Call`  |

### SDK Events (Real-Time, Automatic)

| SDK Listener              | Internal behavior                         |
| ------------------------- | ----------------------------------------- |
| `onIncomingCallReceived`  | Triggers the incoming call screen display |
| `onIncomingCallCancelled` | Dismisses the incoming call screen        |

***

## Functionality

| Method (Kotlin XML)                  | Compose Parameter                  | Description                     |
| ------------------------------------ | ---------------------------------- | ------------------------------- |
| `setCall(call)`                      | `call = call`                      | Set the Call object (required)  |
| `setOnAcceptClick { }`               | `onAcceptClick = { }`              | Override accept button behavior |
| `setOnRejectClick { }`               | `onRejectClick = { }`              | Override reject button behavior |
| `setOnError { }`                     | `onError = { }`                    | Error callback                  |
| `setDisableSoundForCalls(true)`      | `disableSoundForCalls = true`      | Disable incoming call ringtone  |
| `setCustomSoundForCalls(R.raw.tone)` | `customSoundForCalls = R.raw.tone` | Custom ringtone                 |

***

## Custom View Slots

### Leading View

Replace the avatar / left section.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val leadingView = LayoutInflater.from(this).inflate(R.layout.leading_view, null)
    val avatar = leadingView.findViewById<CometChatAvatar>(R.id.avatar)
    val callUser = call.callInitiator as User
    avatar.setAvatar(callUser.name, callUser.avatar)
    leadingView.layoutParams = LinearLayout.LayoutParams(
        Utils.convertDpToPx(this, 45),
        Utils.convertDpToPx(this, 45)
    )
    incomingCall.setLeadingView(leadingView)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatIncomingCall(
        call = call,
        leadingView = { c ->
            val caller = c.callInitiator as? User
            CometChatAvatar(
                imageUrl = caller?.avatar,
                name = caller?.name
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Title View

Replace the caller name / title text.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val titleView = LayoutInflater.from(this).inflate(R.layout.custom_title_view, null)
    val title = titleView.findViewById<TextView>(R.id.title)
    title.text = "George Allen"
    incomingCall.setTitleView(titleView)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatIncomingCall(
        call = call,
        titleView = { c ->
            val caller = c.callInitiator as? User
            Text(
                text = caller?.name ?: "",
                style = CometChatTheme.typography.heading4Medium
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Trailing View

Replace the right section of the incoming call card.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val trailingView = LayoutInflater.from(this).inflate(R.layout.trailing_view, null)
    val avatar = trailingView.findViewById<CometChatAvatar>(R.id.avatar)
    val callUser = call.callInitiator as User
    avatar.setAvatar(callUser.name, callUser.avatar)
    trailingView.layoutParams = LinearLayout.LayoutParams(
        Utils.convertDpToPx(this, 45),
        Utils.convertDpToPx(this, 45)
    )
    incomingCall.setTrailingView(trailingView)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatIncomingCall(
        call = call,
        trailingView = { c ->
            val caller = c.callInitiator as? User
            CometChatAvatar(
                imageUrl = caller?.avatar,
                name = caller?.name,
                modifier = Modifier.size(45.dp)
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Item View

Replace the entire incoming call card.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    incomingCall.setItemView(customView)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatIncomingCall(
        call = call,
        itemView = { c ->
            // Fully custom incoming call card
        }
    )
    ```
  </Tab>
</Tabs>

***

## Style

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Define a custom style in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="CustomIncomingCallStyle" parent="CometChatIncomingCallStyle">
        <item name="cometchatIncomingCallBackgroundColor">#AA9EE8</item>
        <item name="cometchatIncomingCallIconTint">?attr/cometchatPrimaryColor</item>
        <item name="cometchatIncomingCallRejectButtonBackgroundColor">?attr/cometchatColorWhite</item>
        <item name="cometchatIncomingCallAcceptButtonBackgroundColor">?attr/cometchatPrimaryColor</item>
        <item name="cometchatIncomingCallRejectButtonTextColor">?attr/cometchatErrorColor</item>
        <item name="cometchatIncomingCallAcceptButtonTextColor">?attr/cometchatColorWhite</item>
    </style>
    ```

    ```kotlin lines theme={null}
    incomingCall.setStyle(R.style.CustomIncomingCallStyle)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatIncomingCall(
        call = call,
        style = CometChatIncomingCallStyle.default().copy(
            backgroundColor = Color(0xFFAA9EE8),
            acceptButtonBackgroundColor = CometChatTheme.colors.primary,
            rejectButtonBackgroundColor = Color.White,
            rejectButtonTextColor = CometChatTheme.colors.error,
            acceptButtonTextColor = Color.White
        )
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

See [Component Styling](/docs/ui-kit/android/component-styling) for the full reference.

***

## Next Steps

<CardGroup>
  <Card title="Outgoing Call" icon="phone-arrow-up-right" href="/ui-kit/android/outgoing-call">
    Outgoing call screen with end-call button
  </Card>

  <Card title="Call Buttons" icon="phone" href="/ui-kit/android/call-buttons">
    Voice and video call buttons
  </Card>

  <Card title="Call Logs" icon="clock-rotate-left" href="/ui-kit/android/call-logs">
    View call history
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/android/conversations">
    Browse recent conversations
  </Card>
</CardGroup>


# Changelog
Source: https://www.cometchat.com/docs/ui-kit/android/link/changelog





# Figma Design
Source: https://www.cometchat.com/docs/ui-kit/android/link/figma





# Android Sample App
Source: https://www.cometchat.com/docs/ui-kit/android/link/sample





# Localize
Source: https://www.cometchat.com/docs/ui-kit/android/localize

Set the UI Kit language and override text labels to match your users' locale.

<Accordion title="AI Integration Quick Reference">
  | Field               | Value                                                                                                     |
  | ------------------- | --------------------------------------------------------------------------------------------------------- |
  | Import              | `com.cometchat.uikit.core.resources.localise.CometChatLocalize`                                           |
  | Set language        | `CometChatLocalize.setLocale(context, Language.FRENCH)`                                                   |
  | Get language        | `CometChatLocalize.getLocale(context)`                                                                    |
  | Supported languages | 19: ar, de, en, es, fr, hi, hu, it, ja, ko, lt, ms, nl, pl, pt, ru, sv, tr, zh                            |
  | Override labels     | `res/values/strings.xml` — override UI Kit string resource keys                                           |
  | Related             | [Theme Introduction](/docs/ui-kit/android/theme-introduction) · [Sound Manager](/docs/ui-kit/android/sound-manager) |
</Accordion>

Set the CometChat UI Kit language and override UI text so your app matches your users' locale.

***

## Core Concepts

* `CometChatLocalize` — utility object in `chatuikit-core` to set and read the UI Kit locale. Shared by both Kotlin XML and Jetpack Compose modules.
* `Language` — constants for supported language codes (`Language.ENGLISH`, `Language.FRENCH`, etc.)
* `strings.xml` — Android string resources that control visible text in UI Kit components. Override keys in your app's `strings.xml`.

### Supported Languages

| Language  | Code | Language   | Code |
| --------- | ---- | ---------- | ---- |
| Arabic    | `ar` | Korean     | `ko` |
| Chinese   | `zh` | Lithuanian | `lt` |
| Dutch     | `nl` | Malay      | `ms` |
| English   | `en` | Polish     | `pl` |
| French    | `fr` | Portuguese | `pt` |
| German    | `de` | Russian    | `ru` |
| Hindi     | `hi` | Spanish    | `es` |
| Hungarian | `hu` | Swedish    | `sv` |
| Italian   | `it` | Turkish    | `tr` |
| Japanese  | `ja` |            |      |

***

## Set the UI Kit Locale

Call `CometChatLocalize.setLocale()` before rendering any UI Kit components.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.core.resources.localise.CometChatLocalize
    import com.cometchat.uikit.core.resources.localise.Language

    // Set language to Hindi
    CometChatLocalize.setLocale(this, Language.HINDI)

    // Read current locale
    val currentLocale = CometChatLocalize.getLocale(this)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.core.resources.localise.CometChatLocalize
    import com.cometchat.uikit.core.resources.localise.Language

    // Set language before setContent {}
    CometChatLocalize.setLocale(this, Language.HINDI)

    setContent {
        CometChatTheme {
            // UI Kit composables will use Hindi strings
            CometChatConversations(...)
        }
    }
    ```
  </Tab>
</Tabs>

***

## Override UI Kit Labels

Override any UI Kit string by adding the same key to your app's `res/values/strings.xml`. No source code changes needed — Android's resource merging handles it.

```xml res/values/strings.xml lines theme={null}
<resources>
    <!-- Override the conversations list title -->
    <string name="cometchat_chats" translatable="true">Conversations</string>

    <!-- Override the "typing" indicator text -->
    <string name="cometchat_typing" translatable="true">writing...</string>
</resources>
```

<Frame>
  <img />
</Frame>

This works identically for both Kotlin XML Views and Jetpack Compose — both modules read from the same Android string resources.

***

## Customize Date & Time Labels

Override how timestamps like "Today", "Yesterday", and "X mins ago" are displayed.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Set a `DateTimeFormatterCallback` on individual components:

    ```kotlin lines theme={null}
    import com.cometchat.uikit.kotlin.shared.interfaces.DateTimeFormatterCallback
    import java.text.SimpleDateFormat
    import java.util.Date
    import java.util.Locale

    val messageList = findViewById<CometChatMessageList>(R.id.message_list)

    messageList.setDateTimeFormatter(object : DateTimeFormatterCallback {
        private val dateFormatter = SimpleDateFormat("dd MMM yyyy", Locale.getDefault())

        override fun time(timestamp: Long): String = SimpleDateFormat("hh:mm a", Locale.getDefault()).format(Date(timestamp))
        override fun today(timestamp: Long): String = "Today"
        override fun yesterday(timestamp: Long): String = "Yesterday"
        override fun lastWeek(timestamp: Long): String = "Last Week"
        override fun otherDays(timestamp: Long): String = dateFormatter.format(Date(timestamp))
        override fun minutes(diffInMinutesFromNow: Long, timestamp: Long): String = "$diffInMinutesFromNow mins ago"
        override fun hours(diffInHourFromNow: Long, timestamp: Long): String = "$diffInHourFromNow hrs ago"
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Pass a `dateTimeFormatter` parameter to the component:

    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        dateTimeFormatter = object : DateTimeFormatterCallback {
            override fun time(timestamp: Long): String = SimpleDateFormat("hh:mm a", Locale.getDefault()).format(Date(timestamp))
            override fun today(timestamp: Long): String = "Today"
            override fun yesterday(timestamp: Long): String = "Yesterday"
            override fun lastWeek(timestamp: Long): String = "Last Week"
            override fun otherDays(timestamp: Long): String = SimpleDateFormat("dd MMM yyyy", Locale.getDefault()).format(Date(timestamp))
            override fun minutes(diffInMinutesFromNow: Long, timestamp: Long): String = "$diffInMinutesFromNow mins ago"
            override fun hours(diffInHourFromNow: Long, timestamp: Long): String = "$diffInHourFromNow hrs ago"
        }
    )
    ```
  </Tab>
</Tabs>

***

## Additional API

| Method                                                        | Description                                                                 |
| ------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `CometChatLocalize.setLocale(context, language)`              | Sets the UI Kit language                                                    |
| `CometChatLocalize.getLocale(context)`                        | Returns the current locale country code                                     |
| `CometChatLocalize.getLanguage(context)`                      | Returns the current locale language code                                    |
| `CometChatLocalize.isRtl(context)`                            | Checks if the current locale is right-to-left                               |
| `CometChatLocalize.resetToDefault()`                          | Resets locale to system default                                             |
| `CometChatLocalize.createLocalizedContext(context, language)` | Creates a context with a specific locale without affecting the app globally |


# Mentions Formatter
Source: https://www.cometchat.com/docs/ui-kit/android/mentions-formatter-guide

Format and style @mentions in messages with customizable appearance and click handling.

<Accordion title="AI Integration Quick Reference">
  | Field          | Value                                                                                                          |
  | -------------- | -------------------------------------------------------------------------------------------------------------- |
  | Packages       | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack`                                           |
  | Key class      | `CometChatMentionsFormatter` (extends `CometChatTextFormatter`)                                                |
  | Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login("UID")`                                                     |
  | Purpose        | Format @mentions with styled tokens, suggestion list, and click handling for users and group members           |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin)                       |
  | Related        | [ShortCut Formatter](/docs/ui-kit/android/shortcut-formatter-guide) \| [All Guides](/docs/ui-kit/android/guide-overview) |
</Accordion>

`CometChatMentionsFormatter` extends `CometChatTextFormatter` to format @mentions in text messages. It styles mention tokens, generates suggestion lists as users type, and handles click events on rendered mentions across the message composer, message bubbles, and conversations list.

| Capability              | Description                                                                   |
| ----------------------- | ----------------------------------------------------------------------------- |
| Mention formatting      | Auto-formats mention placeholders into styled spans                           |
| Custom styles           | Colors, fonts, and backgrounds per context (composer, bubbles, conversations) |
| User and group mentions | Works with both individual users and group members                            |
| Suggestion list         | Generates mention candidates from user input                                  |
| Click handling          | Listener interface for tap on rendered mentions                               |

***

## Usage

### 1. Create the formatter

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)
    ```
  </Tab>
</Tabs>

### 2. Add to a formatters list

```kotlin theme={null}
val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
textFormatters.add(mentionFormatter)
```

### 3. Pass to a component

Use `setTextFormatters()` on [CometChatMessageComposer](/docs/ui-kit/android/message-composer), [CometChatMessageList](/docs/ui-kit/android/message-list), or [CometChatConversations](/docs/ui-kit/android/conversations).

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    messageComposer.setTextFormatters(textFormatters)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    CometChatMessageComposer(
        user = user,
        textFormatters = textFormatters
    )
    ```
  </Tab>
</Tabs>

***

## Styling Mentions

### Mention Click Handling

Set a click listener for mentions in message bubbles:

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)

    mentionFormatter.setOnMentionClick { context, user ->
        Toast.makeText(context, user.name, Toast.LENGTH_SHORT).show()
    }

    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)
    messageComposer.setTextFormatters(textFormatters)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)

    mentionFormatter.setOnMentionClick { ctx, user ->
        Toast.makeText(ctx, user.name, Toast.LENGTH_SHORT).show()
    }

    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)

    CometChatMessageComposer(
        user = chatUser,
        textFormatters = textFormatters
    )
    ```
  </Tab>
</Tabs>

### Composer Mention Style

Customize how mentions appear in the message composer input field:

<Frame>
  <img />
</Frame>

```xml themes.xml lines theme={null}
<style name="CustomMessageComposerMentionsStyle" parent="CometChatMessageComposerMentionsStyle">
    <item name="cometchatMentionTextAppearance">?attr/cometchatTextAppearanceBodyRegular</item>
    <item name="cometchatMentionTextColor">#000000</item>
    <item name="cometchatMentionBackgroundColor">#000000</item>
    <item name="cometchatSelfMentionTextColor">#30A46C</item>
    <item name="cometchatSelfMentionTextAppearance">?attr/cometchatTextAppearanceBodyRegular</item>
    <item name="cometchatSelfMentionBackgroundColor">#30A46C</item>
</style>
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)
    mentionFormatter.setMessageComposerMentionTextStyle(context, R.style.CustomMessageComposerMentionsStyle)

    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)
    messageComposer.setTextFormatters(textFormatters)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)
    mentionFormatter.setMessageComposerMentionTextStyle(context, R.style.CustomMessageComposerMentionsStyle)

    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)

    CometChatMessageComposer(
        user = chatUser,
        textFormatters = textFormatters
    )
    ```
  </Tab>
</Tabs>

### Message Bubble Mention Style

Customize mentions in incoming and outgoing message bubbles:

<Frame>
  <img />
</Frame>

```xml themes.xml lines theme={null}
<style name="CustomIncomingMessageBubbleMentionStyle" parent="CometChatIncomingBubbleMentionsStyle">
    <item name="cometchatMentionTextAppearance">?attr/cometchatTextAppearanceBodyRegular</item>
    <item name="cometchatMentionTextColor">#D6409F</item>
    <item name="cometchatMentionBackgroundColor">#D6409F</item>
    <item name="cometchatSelfMentionTextColor">#30A46C</item>
    <item name="cometchatSelfMentionTextAppearance">?attr/cometchatTextAppearanceBodyRegular</item>
    <item name="cometchatSelfMentionBackgroundColor">#30A46C</item>
</style>

<style name="CustomOutgoingMessageBubbleMentionStyle" parent="CometChatOutgoingBubbleMentionsStyle">
    <item name="cometchatMentionTextAppearance">?attr/cometchatTextAppearanceBodyRegular</item>
    <item name="cometchatMentionTextColor">#FFFFFF</item>
    <item name="cometchatMentionBackgroundColor">#F9F8FD</item>
    <item name="cometchatSelfMentionTextColor">#30A46C</item>
    <item name="cometchatSelfMentionTextAppearance">?attr/cometchatTextAppearanceBodyRegular</item>
    <item name="cometchatSelfMentionBackgroundColor">#30A46C</item>
</style>
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)
    mentionFormatter.setOutgoingBubbleMentionTextStyle(context, R.style.CustomOutgoingMessageBubbleMentionStyle)
    mentionFormatter.setIncomingBubbleMentionTextStyle(context, R.style.CustomIncomingMessageBubbleMentionStyle)

    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)
    messageList.setTextFormatters(textFormatters)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)
    mentionFormatter.setOutgoingBubbleMentionTextStyle(context, R.style.CustomOutgoingMessageBubbleMentionStyle)
    mentionFormatter.setIncomingBubbleMentionTextStyle(context, R.style.CustomIncomingMessageBubbleMentionStyle)

    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)

    CometChatMessageList(
        user = chatUser,
        textFormatters = textFormatters,
        modifier = Modifier.weight(1f)
    )
    ```
  </Tab>
</Tabs>

### Conversations Mention Style

Customize mentions in the conversations list last-message preview:

<Frame>
  <img />
</Frame>

```xml themes.xml lines theme={null}
<style name="CustomConversationsMentionsStyle" parent="CometChatConversationsMentionsStyle">
    <item name="cometchatMentionTextAppearance">?attr/cometchatTextAppearanceBodyRegular</item>
    <item name="cometchatMentionTextColor">#D6409F</item>
    <item name="cometchatMentionBackgroundColor">#D6409F</item>
    <item name="cometchatSelfMentionTextColor">#30A46C</item>
    <item name="cometchatSelfMentionTextAppearance">?attr/cometchatTextAppearanceBodyRegular</item>
    <item name="cometchatSelfMentionBackgroundColor">#30A46C</item>
</style>
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)
    mentionFormatter.setConversationsMentionTextStyle(context, R.style.CustomConversationsMentionsStyle)

    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)
    cometChatConversations.setTextFormatters(textFormatters)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)
    mentionFormatter.setConversationsMentionTextStyle(context, R.style.CustomConversationsMentionsStyle)

    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)

    CometChatConversations(
        textFormatters = textFormatters,
        onItemClick = { conversation -> /* navigate */ }
    )
    ```
  </Tab>
</Tabs>

***

## Customization Matrix

| What you want to change                       | Where                        | Property/API                                            | Example                                                                                               |
| --------------------------------------------- | ---------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Maximum number of mentions allowed            | `CometChatMentionsFormatter` | `setMentionLimit(int limit)`                            | `mentionFormatter.setMentionLimit(5)`                                                                 |
| Group members fetched for mention suggestions | `CometChatMentionsFormatter` | `.setGroupMembersRequestBuilder(...)`                   | `.setGroupMembersRequestBuilder(group -> GroupMembersRequest.GroupMembersRequestBuilder(group.guid))` |
| Users fetched for mention suggestions         | `CometChatMentionsFormatter` | `.setUsersRequestBuilder(...)`                          | `.setUsersRequestBuilder(UsersRequest.UsersRequestBuilder().friendsOnly(true))`                       |
| Who can be mentioned                          | `CometChatMentionsFormatter` | `.setMentionsType(...)`                                 | `.setMentionsType(UIKitConstants.MentionsType.USERS_AND_GROUP_MEMBERS)`                               |
| Where mentions are visible                    | `CometChatMentionsFormatter` | `.setMentionsVisibility(...)`                           | `.setMentionsVisibility(UIKitConstants.MentionsVisibility.BOTH)`                                      |
| Click action on a mention                     | `CometChatMentionsFormatter` | `setOnMentionClick`                                     | `mentionFormatter.setOnMentionClick { context, user -> }`                                             |
| Mention text style in composer                | `CometChatMentionsFormatter` | `setMessageComposerMentionTextStyle(context, styleRes)` | `mentionFormatter.setMessageComposerMentionTextStyle(context, R.style.CustomStyle)`                   |
| Mention text style in outgoing bubbles        | `CometChatMentionsFormatter` | `setOutgoingBubbleMentionTextStyle(context, styleRes)`  | `mentionFormatter.setOutgoingBubbleMentionTextStyle(context, R.style.CustomStyle)`                    |
| Mention text style in incoming bubbles        | `CometChatMentionsFormatter` | `setIncomingBubbleMentionTextStyle(context, styleRes)`  | `mentionFormatter.setIncomingBubbleMentionTextStyle(context, R.style.CustomStyle)`                    |
| Mention text style in conversations list      | `CometChatMentionsFormatter` | `setConversationsMentionTextStyle(context, styleRes)`   | `mentionFormatter.setConversationsMentionTextStyle(context, R.style.CustomStyle)`                     |

***

## Next Steps

<CardGroup>
  <Card title="Message Composer" icon="keyboard" href="/ui-kit/android/message-composer">
    Configure the composer where users type and send messages with mentions
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/android/message-list">
    Configure the message list where mention-styled bubbles are displayed
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/android/conversations">
    Configure the conversations list where mention-styled previews appear
  </Card>

  <Card title="ShortCut Formatter" icon="bolt" href="/ui-kit/android/shortcut-formatter-guide">
    Add shortcut text expansion to the message composer
  </Card>
</CardGroup>


# Message Bubble Styling
Source: https://www.cometchat.com/docs/ui-kit/android/message-bubble-styling

Configure and style incoming, outgoing, and specific message bubbles in your Android UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                                                            |
  | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Kotlin XML Views | Override XML styles extending `CometChatIncomingMessageBubbleStyle` / `CometChatOutgoingMessageBubbleStyle` in `themes.xml`                                      |
  | Jetpack Compose  | Pass `CometChatMessageListStyle.default().copy()` with nested bubble styles to `CometChatMessageList`                                                            |
  | Hub styles       | Incoming and Outgoing bubble styles act as central hubs for per-type bubble customization                                                                        |
  | Per-type styles  | Text, Image, Audio, Video, File, Sticker, Poll, Collaborative, Meet Call, Delete, Action, Call Action                                                            |
  | Related          | [Theme Introduction](/docs/ui-kit/android/theme-introduction) · [Component Styling](/docs/ui-kit/android/component-styling) · [Message List](/docs/ui-kit/android/message-list) |
</Accordion>

Configure and style incoming, outgoing, and specific message bubbles.

***

## Styling Architecture

Message bubbles follow a hub-and-spoke pattern:

1. **Hub styles** — `IncomingMessageBubbleStyle` and `OutgoingMessageBubbleStyle` control the base bubble appearance
2. **Per-type styles** — Text, Image, Audio, etc. are nested inside the hub styles

<Frame>
  <img />
</Frame>

### Global Setup

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <!-- Hub for Incoming Messages -->
    <style name="CustomIncomingBubble" parent="CometChatIncomingMessageBubbleStyle">
        <item name="cometchatMessageBubbleBackgroundColor">#FEEDE1</item>
    </style>

    <!-- Hub for Outgoing Messages -->
    <style name="CustomOutgoingBubble" parent="CometChatOutgoingMessageBubbleStyle">
        <item name="cometchatMessageBubbleBackgroundColor">#F76808</item>
    </style>

    <!-- Connect to AppTheme -->
    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatIncomingMessageBubbleStyle">@style/CustomIncomingBubble</item>
        <item name="cometchatOutgoingMessageBubbleStyle">@style/CustomOutgoingBubble</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        style = CometChatMessageListStyle.default().copy(
            incomingMessageBubbleStyle = CometChatIncomingMessageBubbleStyle.default().copy(
                backgroundColor = Color(0xFFFEEDE1)
            ),
            outgoingMessageBubbleStyle = CometChatOutgoingMessageBubbleStyle.default().copy(
                backgroundColor = Color(0xFFF76808)
            )
        )
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

***

## Core Message Bubbles

### Text Bubble

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="CustomIncomingTextBubble" parent="CometChatIncomingTextMessageBubbleStyle">
        <item name="cometchatTextBubbleBackgroundColor">#FEEDE1</item>
    </style>

    <style name="CustomOutgoingTextBubble" parent="CometChatOutgoingTextBubbleStyle">
        <item name="cometchatTextBubbleBackgroundColor">#F76808</item>
    </style>

    <style name="CustomIncomingBubble" parent="CometChatIncomingMessageBubbleStyle">
        <item name="cometchatTextBubbleStyle">@style/CustomIncomingTextBubble</item>
    </style>

    <style name="CustomOutgoingBubble" parent="CometChatOutgoingMessageBubbleStyle">
        <item name="cometchatTextBubbleStyle">@style/CustomOutgoingTextBubble</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // Inside CometChatMessageListStyle
    incomingMessageBubbleStyle = CometChatIncomingMessageBubbleStyle.default().copy(
        textBubbleStyle = CometChatTextBubbleStyle.default().copy(
            backgroundColor = Color(0xFFFEEDE1)
        )
    ),
    outgoingMessageBubbleStyle = CometChatOutgoingMessageBubbleStyle.default().copy(
        textBubbleStyle = CometChatTextBubbleStyle.default().copy(
            backgroundColor = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

### Image Bubble

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="CustomIncomingImageBubble" parent="CometChatIncomingImageMessageBubbleStyle">
        <item name="cometchatImageBubbleBackgroundColor">#FEEDE1</item>
    </style>

    <style name="CustomIncomingBubble" parent="CometChatIncomingMessageBubbleStyle">
        <item name="cometchatImageBubbleStyle">@style/CustomIncomingImageBubble</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    incomingMessageBubbleStyle = CometChatIncomingMessageBubbleStyle.default().copy(
        imageBubbleStyle = CometChatImageBubbleStyle.default().copy(
            backgroundColor = Color(0xFFFEEDE1)
        )
    )
    ```
  </Tab>
</Tabs>

### Images Bubble

Renders a message that carries **multiple image attachments** (`CometChatImagesBubble`) as a count-based grid (1, 2, 3, 4, or 5+ tiles). When there are more images than visible tiles, the last tile shows a "+N" overflow overlay. Tapping a tile opens the fullscreen gallery viewer. A caption renders underneath the grid. This is the multi-attachment bubble the list renders for image messages; the single-attachment [Image Bubble](#image-bubble) remains for standalone use.

**Default**

<Frame>
  <img alt="Images Bubble rendering a grid of image attachments with a +N overflow overlay on the last tile" />
</Frame>

The image grid derives its look from your [CometChat theme](/docs/ui-kit/android/theme-introduction). In **Jetpack Compose** it is governed by the dedicated `CometChatImagesBubbleStyle` class. Its grid-specific properties:

| Property                                        | Type                  | Description                                  |
| ----------------------------------------------- | --------------------- | -------------------------------------------- |
| `tileCornerRadius`                              | `Dp`                  | Corner radius of each grid tile              |
| `gridSpacing`                                   | `Dp`                  | Gap between tiles (default `2.dp`)           |
| `tilePlaceholderColor`                          | `Color`               | Shown while a tile's image loads             |
| `moreOverlayBackgroundColor`                    | `Color`               | Scrim over the last tile when items overflow |
| `moreOverlayTextColor` / `moreOverlayTextStyle` | `Color` / `TextStyle` | The "+N" overflow label                      |
| `captionTextColor` / `captionTextStyle`         | `Color` / `TextStyle` | The caption row under the grid               |

### Video Bubble

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="CustomIncomingVideoBubble" parent="CometChatIncomingVideoBubbleStyle">
        <item name="cometchatVideoBubbleBackgroundColor">#FEEDE1</item>
        <item name="cometchatVideoBubblePlayIconTint">#F76808</item>
    </style>

    <style name="CustomIncomingBubble" parent="CometChatIncomingMessageBubbleStyle">
        <item name="cometchatVideoBubbleStyle">@style/CustomIncomingVideoBubble</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    incomingMessageBubbleStyle = CometChatIncomingMessageBubbleStyle.default().copy(
        videoBubbleStyle = CometChatVideoBubbleStyle.default().copy(
            backgroundColor = Color(0xFFFEEDE1),
            playIconTint = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

### Videos Bubble

Renders a message that carries **multiple video attachments** (`CometChatVideosBubble`) as a count-based grid (1, 2, 3, 4, or 5+ tiles). Each tile shows a poster thumbnail with a centered play badge and a duration chip; the last tile shows a "+N" overflow overlay when there are more videos than visible tiles. Tapping a tile opens the fullscreen player. A caption renders underneath the grid. This is the multi-attachment bubble the list renders for video messages; the single-attachment [Video Bubble](#video-bubble) remains for standalone use.

**Default**

<Frame>
  <img alt="Videos Bubble rendering a grid of video thumbnails, each with a centered play badge, and a +N overflow overlay on the last tile" />
</Frame>

The video grid derives its look from your [CometChat theme](/docs/ui-kit/android/theme-introduction). In **Jetpack Compose** it is governed by the dedicated `CometChatVideosBubbleStyle` class. Its grid-specific properties:

| Property                                                                       | Type                  | Description                            |
| ------------------------------------------------------------------------------ | --------------------- | -------------------------------------- |
| `tileCornerRadius` / `gridSpacing`                                             | `Dp`                  | Tile corner radius and gap             |
| `tilePlaceholderColor`                                                         | `Color`               | Shown while a thumbnail loads          |
| `moreOverlayBackgroundColor` / `moreOverlayTextColor` / `moreOverlayTextStyle` | `Color` / `TextStyle` | The "+N" overflow overlay              |
| `playBadgeBackgroundColor` / `playIconTint`                                    | `Color`               | The centered play badge on video tiles |
| `durationChipBackgroundColor` / `durationTextColor` / `durationTextStyle`      | `Color` / `TextStyle` | The duration chip                      |
| `showVideoDuration`                                                            | `Boolean`             | Whether the duration chip is shown     |
| `captionTextColor` / `captionTextStyle`                                        | `Color` / `TextStyle` | The caption row under the grid         |

### Audio Bubble

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="CustomIncomingAudioBubble" parent="CometChatIncomingAudioBubbleStyle">
        <item name="cometchatAudioBubbleAudioWaveColor">#F76808</item>
        <item name="cometchatAudioBubblePlayIconTint">#F76808</item>
        <item name="cometchatAudioBubbleBackgroundColor">#FEEDE1</item>
    </style>

    <style name="CustomIncomingBubble" parent="CometChatIncomingMessageBubbleStyle">
        <item name="cometchatAudioBubbleStyle">@style/CustomIncomingAudioBubble</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    incomingMessageBubbleStyle = CometChatIncomingMessageBubbleStyle.default().copy(
        audioBubbleStyle = CometChatAudioBubbleStyle.default().copy(
            playIconTint = Color(0xFFF76808),
            backgroundColor = Color(0xFFFEEDE1)
        )
    )
    ```
  </Tab>
</Tabs>

### Audios Bubble

Renders a message carrying **audio file attachments** (`CometChatAudiosBubble`) — audio chosen through the file/audio picker — one player row per file, each with a play/pause button, a seekable progress bar, the time, the file name, and a download control. Four or more files collapse behind a "Show N more" toggle. Only one row plays at a time.

**Default**

<Frame>
  <img alt="Audios Bubble rendering stacked audio player rows, each with a play button, seek bar, time, file name, and download control, plus a Show N more toggle" />
</Frame>

<Note>
  This bubble is distinct from the [Audio Bubble](#audio-bubble), which renders **voice notes** recorded with the composer's microphone. Voice notes keep their waveform look and are never grouped with other attachments.
</Note>

In **Jetpack Compose** it is governed by `CometChatAudiosBubbleStyle`; the **Kotlin (XML Views)** list reuses your existing [Audio Bubble](#audio-bubble) style. Key Compose properties:

| Property                                                                     | Type                  | Description                                                             |
| ---------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------- |
| `cardBackgroundColor` / `cardCornerRadius`                                   | `Color` / `Dp`        | Each player card (applies only when the message carries multiple files) |
| `itemSpacing`                                                                | `Dp`                  | Vertical gap between cards                                              |
| `playButtonBackgroundColor` / `playIconTint`                                 | `Color`               | The play/pause circle                                                   |
| `seekFillColor` / `seekTrackColor` / `seekKnobColor` / `seekKnobBorderColor` | `Color`               | The seek bar                                                            |
| `titleTextColor` / `titleTextStyle`                                          | `Color` / `TextStyle` | File name text                                                          |
| `durationTextColor` / `durationTextStyle`                                    | `Color` / `TextStyle` | The "mm:ss / mm:ss" time text                                           |
| `downloadIconTint`                                                           | `Color`               | Per-card download icon                                                  |
| `toggleTextColor` / `toggleTextStyle`                                        | `Color` / `TextStyle` | The "Show N more" / "Show less" toggle                                  |
| `captionTextColor` / `captionTextStyle`                                      | `Color` / `TextStyle` | The caption row under the cards                                         |

### File Bubble

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="CustomIncomingFileBubble" parent="CometChatIncomingFileBubbleStyle">
        <item name="cometchatFileBubbleBackgroundColor">#FEEDE1</item>
        <item name="cometchatFileBubbleFileDownloadIconTint">#F76808</item>
    </style>

    <style name="CustomIncomingBubble" parent="CometChatIncomingMessageBubbleStyle">
        <item name="cometchatFileBubbleStyle">@style/CustomIncomingFileBubble</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    incomingMessageBubbleStyle = CometChatIncomingMessageBubbleStyle.default().copy(
        fileBubbleStyle = CometChatFileBubbleStyle.default().copy(
            backgroundColor = Color(0xFFFEEDE1),
            downloadIconTint = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

### Files Bubble

Renders a message carrying **document attachments** as a connected stack of file cards — each with a file-type icon (PDF, Word, Excel, PowerPoint, ZIP, …), the file name, and its size/extension metadata. Four or more files collapse behind a "+N more" toggle. Tapping a card opens the file. A caption renders under the stack.

**Default**

<Frame>
  <img alt="Files Bubble rendering a stack of file cards, each with a file-type icon, file name, and size metadata, plus a Show N more toggle" />
</Frame>

<Note>
  `cardBackgroundColor` only applies when the message carries **multiple** files — a single file card sits directly on the bubble background.
</Note>

In **Jetpack Compose** it is governed by `CometChatFilesBubbleStyle`; the **Kotlin (XML Views)** list reuses your existing [File Bubble](#file-bubble) style. Key Compose properties:

| Property                                                            | Type                  | Description                        |
| ------------------------------------------------------------------- | --------------------- | ---------------------------------- |
| `cardBackgroundColor` / `cardCornerRadius`                          | `Color` / `Dp`        | Each file card (multiples only)    |
| `itemSpacing`                                                       | `Dp`                  | Vertical gap between cards         |
| `fileIconBackgroundColor` / `fileIconCornerRadius` / `fileIconSize` | `Color` / `Dp`        | The file-type icon plate           |
| `titleTextColor` / `titleTextStyle`                                 | `Color` / `TextStyle` | File name text                     |
| `subtitleTextColor` / `subtitleTextStyle`                           | `Color` / `TextStyle` | File size/extension text           |
| `downloadIconTint`                                                  | `Color`               | Per-card download icon             |
| `toggleTextColor` / `toggleTextStyle`                               | `Color` / `TextStyle` | The "+N more" / "Show less" toggle |
| `captionTextColor` / `captionTextStyle`                             | `Color` / `TextStyle` | The caption row under the cards    |

<Note>
  Captions containing rich text (code blocks, quote blocks, inline code) render through the same pipeline as [Text Bubbles](#text-bubble), so their formatting looks identical across message types.
</Note>

***

### Sticker Bubble

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="CustomStickerBubble" parent="CometChatStickerBubbleStyle">
        <item name="cometchatStickerBubbleBackgroundColor">#FEEDE1</item>
    </style>

    <style name="CustomIncomingBubble" parent="CometChatIncomingMessageBubbleStyle">
        <item name="cometchatStickerBubbleStyle">@style/CustomStickerBubble</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    incomingMessageBubbleStyle = CometChatIncomingMessageBubbleStyle.default().copy(
        stickerBubbleStyle = CometChatStickerBubbleStyle.default().copy(
            backgroundColor = Color(0xFFFEEDE1)
        )
    )
    ```
  </Tab>
</Tabs>

### Poll Bubble

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="CustomOutgoingPollBubble" parent="CometChatOutgoingPollBubbleStyle">
        <item name="cometchatPollBubbleBackgroundColor">#F76808</item>
        <item name="cometchatPollBubbleProgressBackgroundColor">#FBAA75</item>
    </style>

    <style name="CustomOutgoingBubble" parent="CometChatOutgoingMessageBubbleStyle">
        <item name="cometchatPollBubbleStyle">@style/CustomOutgoingPollBubble</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    outgoingMessageBubbleStyle = CometChatOutgoingMessageBubbleStyle.default().copy(
        pollBubbleStyle = CometChatPollBubbleStyle.default().copy(
            backgroundColor = Color(0xFFF76808),
            progressBackgroundColor = Color(0xFFFBAA75)
        )
    )
    ```
  </Tab>
</Tabs>

### Collaborative Bubble

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="CustomCollaborativeBubble" parent="CometChatOutgoingCollaborativeBubbleStyle">
        <item name="cometchatCollaborativeBubbleBackgroundColor">#F76808</item>
        <item name="cometchatCollaborativeBubbleSeparatorColor">#FBAA75</item>
    </style>

    <style name="CustomOutgoingBubble" parent="CometChatOutgoingMessageBubbleStyle">
        <item name="cometchatCollaborativeBubbleStyle">@style/CustomCollaborativeBubble</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    outgoingMessageBubbleStyle = CometChatOutgoingMessageBubbleStyle.default().copy(
        collaborativeBubbleStyle = CometChatCollaborativeBubbleStyle.default().copy(
            backgroundColor = Color(0xFFF76808),
            separatorColor = Color(0xFFFBAA75)
        )
    )
    ```
  </Tab>
</Tabs>

### Meet Call Bubble

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="CustomMeetCallBubble" parent="CometChatOutgoingMeetCallBubbleStyle">
        <item name="cometchatMeetCallBubbleBackgroundColor">#F76808</item>
        <item name="cometchatMeetCallBubbleCallIconTint">#F76808</item>
    </style>

    <style name="CustomOutgoingBubble" parent="CometChatOutgoingMessageBubbleStyle">
        <item name="cometchatMeetCallBubbleStyle">@style/CustomMeetCallBubble</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    outgoingMessageBubbleStyle = CometChatOutgoingMessageBubbleStyle.default().copy(
        meetCallBubbleStyle = CometChatMeetCallBubbleStyle.default().copy(
            backgroundColor = Color(0xFFF76808),
            callIconTint = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

### Delete Bubble

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="CustomDeleteBubble" parent="CometChatOutgoingDeleteBubbleStyle">
        <item name="cometchatMessageBubbleBackgroundColor">#F76808</item>
    </style>

    <style name="CustomOutgoingBubble" parent="CometChatOutgoingMessageBubbleStyle">
        <item name="cometchatDeleteBubbleStyle">@style/CustomDeleteBubble</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    outgoingMessageBubbleStyle = CometChatOutgoingMessageBubbleStyle.default().copy(
        deleteBubbleStyle = CometChatDeleteBubbleStyle.default().copy(
            backgroundColor = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

***

## List-Level Bubbles

These bubbles are tied to the Message List style, not the Incoming/Outgoing hubs.

### Call Action Bubble

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="CustomCallActionBubble" parent="CometChatCallActionBubbleStyle">
        <item name="cometchatCallActionBubbleBackgroundColor">#FEEDE1</item>
        <item name="cometchatCallActionBubbleTextColor">#F76808</item>
        <item name="cometchatCallActionBubbleIconTint">#F76808</item>
    </style>

    <style name="CustomMessageListStyle" parent="CometChatMessageListStyle">
        <item name="cometchatMessageListCallActionBubbleStyle">@style/CustomCallActionBubble</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatMessageListStyle">@style/CustomMessageListStyle</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        style = CometChatMessageListStyle.default().copy(
            callActionBubbleStyle = CometChatCallActionBubbleStyle.default().copy(
                backgroundColor = Color(0xFFFEEDE1),
                textColor = Color(0xFFF76808),
                iconTint = Color(0xFFF76808)
            )
        )
    )
    ```
  </Tab>
</Tabs>

### Action Bubble

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="CustomActionBubble" parent="CometChatActionBubbleStyle">
        <item name="cometchatActionBubbleBackgroundColor">#FEEDE1</item>
        <item name="cometchatActionBubbleTextColor">#F76808</item>
    </style>

    <style name="CustomMessageListStyle" parent="CometChatMessageListStyle">
        <item name="cometchatMessageListActionBubbleStyle">@style/CustomActionBubble</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatMessageListStyle">@style/CustomMessageListStyle</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        style = CometChatMessageListStyle.default().copy(
            actionBubbleStyle = CometChatActionBubbleStyle.default().copy(
                backgroundColor = Color(0xFFFEEDE1),
                textColor = Color(0xFFF76808)
            )
        )
    )
    ```
  </Tab>
</Tabs>


# Message Composer
Source: https://www.cometchat.com/docs/ui-kit/android/message-composer

Message input area with send, attachment, voice note, sticker, and AI buttons. Supports text, media, mentions, and message editing.

`CometChatMessageComposer` renders the message input area and sends messages to the active conversation. It supports text, media, mentions, voice notes, stickers, and AI-powered features.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatMessageComposer` is an input component. Wire it with `CometChatMessageHeader` and `CometChatMessageList` to build a complete messaging layout.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_chat.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
        android:id="@+id/message_composer"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />
    ```

    ```kotlin lines theme={null}
    val messageComposer = findViewById<CometChatMessageComposer>(R.id.message_composer)
    messageComposer.setUser(user)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageComposer(
        user = user
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add to your layout XML:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
        android:id="@+id/composer"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />
    ```

    Set a `User` or `Group`:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.your_layout)

        val composer = findViewById<CometChatMessageComposer>(R.id.composer)
        composer.setUser(user)
        // or composer.setGroup(group)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    @Composable
    fun ComposerScreen() {
        CometChatMessageComposer(
            user = user
            // or group = group
        )
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

<Warning>
  The MessageComposer manages runtime permissions. To ensure the **ActivityResultLauncher** is properly initialized, create the composer in the **onCreate** state of an activity. If using a fragment, load it in the activity's `onCreate`.
</Warning>

***

## Actions and Events

### Callback Methods

#### `onSendButtonClick`

Fires when the send button is tapped. Override to intercept or replace the default message-sending logic.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageComposer.setOnSendButtonClick { context, baseMessage ->
        // Custom send logic
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageComposer(
        user = user,
        onSendButtonClick = { context, baseMessage ->
            // Custom send logic
        }
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageComposer.setOnError { context, exception ->
        Log.e("Composer", "Error: ${exception.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageComposer(
        user = user,
        onError = { context, exception ->
            Log.e("Composer", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

### SDK Events

The MessageComposer does not attach SDK listeners directly. Typing indicators are managed internally when `disableTypingEvents` is `false` (default).

***

## Functionality

| Method (Kotlin XML)                  | Compose Parameter                  | Description                                                                                                                                                                                     |
| ------------------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setUser(user)`                      | `user = user`                      | Set target user for 1-on-1 conversations                                                                                                                                                        |
| `setGroup(group)`                    | `group = group`                    | Set target group for group conversations                                                                                                                                                        |
| `setOnSendButtonClick { }`           | `onSendButtonClick = { }`          | Override send button behavior                                                                                                                                                                   |
| `setParentMessageId(id)`             | `parentMessageId = id`             | Set parent message ID for threaded replies                                                                                                                                                      |
| `setTextFormatters(list)`            | `textFormatters = list`            | Custom text formatters (mentions, etc.)                                                                                                                                                         |
| `setEnableRichTextFormatting(true)`  | `enableRichTextFormatting = true`  | Enable rich text formatting                                                                                                                                                                     |
| `setEnableMultipleAttachments(true)` | `enableMultipleAttachments = true` | Multi-select attachment picking with a preview tray (default `true`); `false` reverts to legacy single-attachment, send-immediately behavior. See [Multiple Attachments](#multiple-attachments) |

***

## Multiple Attachments

The composer supports sending several attachments in one go. Tapping a media or file option opens a multi-select picker; the picks are staged in an **attachment tray** above the input box, upload immediately, and are sent together when the user taps send.

**How it works:**

* **Multi-select picking** — the photo/video picker and the document picker both allow selecting multiple items, capped to the app's per-message limit. Camera captures and picker audio stage into the same tray.
* **Attachment tray** — each staged file shows as a tile (thumbnail for media, chip for files/audio) with a live upload progress indicator, a ✕ to cancel or remove, and tap-to-retry on a transfer failure. The tray is only visible while at least one file is staged.
* **Upload before send** — files upload as soon as they are staged (via the SDK's upload-first flow); the send button stays disabled until every tile finishes uploading. Text typed in the composer becomes the **caption** of the batch, with rich text formatting preserved.
* **One message per attachment type** — a mixed pick is split into separate messages in a fixed order (images → videos → audios → files) that share a `batchId` and render as grouped bubbles in the message list.
* **Clipboard paste** — images, videos, documents, and audio copied to the clipboard can be pasted straight into the composer and stage into the tray.
* **Voice notes stay standalone** — a mic recording always sends immediately as its own message and is never staged. Audio chosen through the file picker, by contrast, stages as a file attachment.
* Editing a media message edits its **caption** only; the message's attachments are preserved.

### Limits and Validation

Limits are governed by the app's server settings (CometChat dashboard) — the composer reads them at runtime through the SDK.

| Limit             | Setting                          | Behavior on violation                                                                                                                                |
| ----------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Files per message | `file.count.max` (default 10)    | Picker selection is capped; overflow picks are dropped and a `MAX_ATTACHMENTS_EXCEEDED` error is emitted ("You can attach up to N files at a time.") |
| Per-file size     | `file.size.max` (default 100 MB) | The file stages as a **rejected** (non-retryable) error tile; sending is blocked until it is removed                                                 |
| File type         | Server-side validation           | The upload is refused by the server and the file becomes a **rejected** error tile                                                                   |

Each tile carries an `AttachmentUploadStatus` (`UPLOADING`, `DONE`, `FAILED`, `REJECTED`, `CANCELLED`) mapped directly from the SDK's per-file upload callbacks, so the tray shows the right affordance — cancel while uploading, **retry** on a `FAILED` (transient) tile, **remove** on a `REJECTED` (non-retryable) tile. Errors surface through the composer ViewModel's `errorEvent`, which you can observe to show your own snack bar.

### Disabling Multiple Attachments

Set the flag to `false` to restore the legacy behavior — single-item pickers that send immediately with no tray:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageComposer.setEnableMultipleAttachments(false)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageComposer(
        user = user,
        enableMultipleAttachments = false
    )
    ```
  </Tab>
</Tabs>

This is composer-side only: received multi-attachment messages still render with the grouped bubbles (see [Message List](/docs/ui-kit/android/message-list)).

### Styling the Attachment Tray (Compose)

In the Compose UI Kit the tray strip is themed through `CometChatAttachmentTrayStyle`:

```kotlin lines theme={null}
CometChatMessageComposer(
    user = user,
    attachmentTrayStyle = CometChatAttachmentTrayStyle.default().copy(
        backgroundColor = Color(0xFFFEEDE1),
        tileSpacing = 8.dp
    )
)
```

The individual staged-tile visuals and the per-type message bubbles are covered in [Message Bubble Styling](/docs/ui-kit/android/message-bubble-styling).

***

## Custom View Slots

### Header View

Custom view above the text input area.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val view = LayoutInflater.from(context).inflate(R.layout.custom_header_layout, null)
    messageComposer.setHeaderView(view)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageComposer(
        user = user,
        headerView = {
            Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFEDEAFA))) {
                Row(Modifier.padding(8.dp), verticalAlignment = Alignment.CenterVertically) {
                    Icon(painterResource(R.drawable.ic_notes), "Notes")
                    Spacer(Modifier.width(4.dp))
                    Text("Notes")
                }
            }
        }
    )
    ```
  </Tab>
</Tabs>

### Send Button View

Replace the default send button.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val imageView = ImageView(this)
    imageView.setImageResource(R.drawable.custom_send_button)
    imageView.setOnClickListener {
        Toast.makeText(this, "Custom Send Button Clicked!", Toast.LENGTH_SHORT).show()
    }
    messageComposer.setSendButtonView(imageView)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageComposer(
        user = user,
        sendButtonView = {
            IconButton(onClick = { /* custom send */ }) {
                Icon(painterResource(R.drawable.custom_send_button), "Send")
            }
        }
    )
    ```
  </Tab>
</Tabs>

### Auxiliary Button View

Replace the auxiliary button area (stickers, AI).

<Frame>
  <img />
</Frame>

<Note>
  If you override the auxiliary button with `setAuxiliaryButtonView()`, retrieve the default auxiliary buttons via `CometChatUIKit.getDataSource().getAuxiliaryOption()` and include them in your custom layout to preserve sticker/AI buttons.
</Note>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val linearLayout = LinearLayout(this)
    linearLayout.orientation = LinearLayout.HORIZONTAL

    // Preserve default auxiliary buttons
    val defaultView = CometChatUIKit.getDataSource().getAuxiliaryOption(
        this, user, group,
        messageComposer.composerViewModel.getIdMap(),
        messageComposer.additionParameter
    )
    linearLayout.addView(defaultView)

    // Add custom button
    val customButton = ImageView(this)
    customButton.setImageResource(R.drawable.save_icon)
    linearLayout.addView(customButton)

    messageComposer.setAuxiliaryButtonView(linearLayout)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageComposer(
        user = user,
        auxiliaryButtonView = {
            Row {
                // Custom button alongside defaults
                IconButton(onClick = { /* action */ }) {
                    Icon(painterResource(R.drawable.save_icon), "Save")
                }
            }
        }
    )
    ```
  </Tab>
</Tabs>

### Attachment Options

Replace the default attachment options.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val actionList = ArrayList<CometChatMessageComposerAction>()

    val action1 = CometChatMessageComposerAction()
    action1.title = "Custom Option 1"
    action1.icon = R.drawable.ic_cp_1
    action1.onClick = {
        Toast.makeText(context, "Custom Option 1", Toast.LENGTH_SHORT).show()
    }
    actionList.add(action1)

    messageComposer.setAttachmentOptions(actionList)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageComposer(
        user = user,
        attachmentOptions = listOf(
            CometChatMessageComposerAction(
                title = "Custom Option 1",
                icon = R.drawable.ic_cp_1,
                onClick = { /* handle */ }
            )
        )
    )
    ```
  </Tab>
</Tabs>

### Text Formatters (Mentions)

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)
    mentionFormatter.setMessageComposerMentionTextStyle(context, R.style.CustomMentionsStyle)

    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)
    messageComposer.setTextFormatters(textFormatters)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)

    CometChatMessageComposer(
        user = user,
        textFormatters = listOf(mentionFormatter)
    )
    ```
  </Tab>
</Tabs>

***

## Style

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Define a custom style in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="CustomMessageComposerStyle" parent="CometChatMessageComposerStyle">
        <item name="cometchatMessageComposerBackgroundColor">#FEEDE1</item>
        <item name="cometchatMessageComposerInputBackgroundColor">#FFFFFF</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatMessageComposerStyle">@style/CustomMessageComposerStyle</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageComposer(
        user = user,
        style = CometChatMessageComposerStyle.default().copy(
            backgroundColor = Color(0xFFFEEDE1),
            inputBackgroundColor = Color.White
        )
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

See [Component Styling](/docs/ui-kit/android/component-styling) for the full reference.

***

## ViewModel

```kotlin lines theme={null}
val viewModel = ViewModelProvider(this)
    .get(CometChatMessageComposerViewModel::class.java)
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageComposer.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageComposer(
        user = user,
        messageComposerViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

See [ViewModel & Data](/docs/ui-kit/android/customization-viewmodel-data) for state observation and custom repositories.

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="messages" href="/ui-kit/android/message-list">
    Display messages in a conversation
  </Card>

  <Card title="Message Header" icon="heading" href="/ui-kit/android/message-header">
    Display user/group info in the toolbar
  </Card>

  <Card title="Message Template" icon="puzzle-piece" href="/ui-kit/android/message-template">
    Customize message bubble structure
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/android/component-styling">
    Detailed styling reference
  </Card>
</CardGroup>


# Message Header
Source: https://www.cometchat.com/docs/ui-kit/android/message-header

Header bar displaying user/group avatar, name, status, typing indicator, call buttons, and back navigation.

`CometChatMessageHeader` is a header bar component that sits at the top of a chat screen, displaying the avatar, name, and status of the user or group in the conversation.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatMessageHeader` sits at the top of a chat screen. Wire it alongside `CometChatMessageList` and `CometChatMessageComposer` to build a complete messaging layout.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_chat.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader
        android:id="@+id/message_header"
        android:layout_width="match_parent"
        android:layout_height="56dp" />
    ```

    ```kotlin lines theme={null}
    val messageHeader = findViewById<CometChatMessageHeader>(R.id.message_header)
    messageHeader.setUser(user)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageHeader(
        user = user
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add to your layout XML:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader
        android:id="@+id/header"
        android:layout_width="match_parent"
        android:layout_height="56dp" />
    ```

    Set a `User` or `Group` on the component — this is required for it to display data:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.your_layout)

        val messageHeader = findViewById<CometChatMessageHeader>(R.id.header)
        messageHeader.setUser(user)
        // or messageHeader.setGroup(group)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    @Composable
    fun ChatHeader() {
        CometChatMessageHeader(
            user = user
            // or group = group
        )
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

***

## Actions and Events

### Callback Methods

#### `onBackPress`

Fires when the user presses the back button in the header.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageHeader.setOnBackPress {
        finish()
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageHeader(
        user = user,
        onBackPress = { /* navigate back */ }
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageHeader.setOnError { exception ->
        Log.e("MessageHeader", "Error: ${exception.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageHeader(
        user = user,
        onError = { exception ->
            Log.e("MessageHeader", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

| SDK Listener                                                                                | Internal behavior                        |
| ------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `onUserOnline` / `onUserOffline`                                                            | Updates online/offline status indicator  |
| `onTypingStarted` / `onTypingEnded`                                                         | Shows/hides typing indicator in subtitle |
| `onGroupMemberJoined` / `onGroupMemberLeft` / `onGroupMemberKicked` / `onGroupMemberBanned` | Updates group member count               |

***

## Functionality

| Method (Kotlin XML)                     | Compose Parameter        | Description                      |
| --------------------------------------- | ------------------------ | -------------------------------- |
| `setUser(user)`                         | `user = user`            | Display a user's header details  |
| `setGroup(group)`                       | `group = group`          | Display a group's header details |
| `setBackButtonVisibility(View.VISIBLE)` | `hideBackButton = false` | Toggle back button               |
| `setOnBackPress { }`                    | `onBackPress = { }`      | Back button callback             |

***

## Custom View Slots

### Leading View

Replace the avatar / left section.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageHeader.setLeadingView(object : MessageHeaderViewHolderListener() {
        override fun createView(context: Context, user: User?, group: Group?): View {
            return ImageView(context).apply {
                layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp)
            }
        }

        override fun bindView(context: Context, createdView: View, user: User?, group: Group?) {
            val imageView = createdView as ImageView
            // Load avatar image
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageHeader(
        user = user,
        leadingView = { u, g ->
            CometChatAvatar(
                imageUrl = u?.avatar,
                name = u?.name
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

Replace the subtitle text below the user's or group's name.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageHeader.setSubtitleView(object : MessageHeaderViewHolderListener() {
        override fun createView(context: Context, user: User?, group: Group?): View {
            return TextView(context)
        }

        override fun bindView(context: Context, createdView: View, user: User?, group: Group?) {
            val textView = createdView as TextView
            if (user != null) {
                textView.text = user.status
            } else if (group != null) {
                textView.text = "${group.membersCount} members"
            }
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageHeader(
        user = user,
        subtitleView = { u, g ->
            Text(
                text = u?.status ?: "${g?.membersCount} members",
                style = CometChatTheme.typography.caption1Regular
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Trailing View

Replace the right section (action buttons).

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageHeader.setTrailingView(object : MessageHeaderViewHolderListener() {
        override fun createView(context: Context, user: User?, group: Group?): View {
            return ImageView(context).apply {
                setImageResource(R.drawable.save_icon)
                layoutParams = LinearLayout.LayoutParams(24.dp, 24.dp)
            }
        }

        override fun bindView(context: Context, createdView: View, user: User?, group: Group?) {
            // Bind trailing view data
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageHeader(
        user = user,
        trailingView = { u, g ->
            IconButton(onClick = { /* action */ }) {
                Icon(painterResource(R.drawable.save_icon), "Save")
            }
        }
    )
    ```
  </Tab>
</Tabs>

### Item View

Replace the entire default header with a fully customized layout.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageHeader.setItemView(object : MessageHeaderViewHolderListener() {
        override fun createView(context: Context, user: User?, group: Group?): View {
            return LayoutInflater.from(context).inflate(R.layout.custom_message_header, null)
        }

        override fun bindView(context: Context, createdView: View, user: User?, group: Group?) {
            val avatar = createdView.findViewById<CometChatAvatar>(R.id.avatar)
            val title = createdView.findViewById<TextView>(R.id.title)
            if (user != null) {
                avatar.setAvatar(user.name, user.avatar)
                title.text = user.name
            } else if (group != null) {
                avatar.setAvatar(group.name, group.icon)
                title.text = group.name
            }
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageHeader(
        user = user,
        itemView = { u, g ->
            Row(verticalAlignment = Alignment.CenterVertically) {
                CometChatAvatar(imageUrl = u?.avatar, name = u?.name)
                Spacer(Modifier.width(8.dp))
                Text(u?.name ?: g?.name ?: "")
            }
        }
    )
    ```
  </Tab>
</Tabs>

***

## Style

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Define a custom style in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="CustomMessageHeaderStyle" parent="CometChatMessageHeaderStyle">
        <item name="cometchatMessageHeaderBackgroundColor">#FEEDE1</item>
        <item name="cometchatMessageHeaderTitleTextColor">#F76808</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatMessageHeaderStyle">@style/CustomMessageHeaderStyle</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageHeader(
        user = user,
        style = CometChatMessageHeaderStyle.default().copy(
            backgroundColor = Color(0xFFFEEDE1),
            titleTextColor = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

See [Component Styling](/docs/ui-kit/android/component-styling) for the full reference.

***

## ViewModel

```kotlin lines theme={null}
val viewModel = ViewModelProvider(this)
    .get(CometChatMessageHeaderViewModel::class.java)
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageHeader.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageHeader(
        user = user,
        messageHeaderViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

See [ViewModel & Data](/docs/ui-kit/android/customization-viewmodel-data) for state observation and custom repositories.

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="messages" href="/ui-kit/android/message-list">
    Display messages in a conversation
  </Card>

  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/android/message-composer">
    Rich input for sending messages
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/android/component-styling">
    Detailed styling reference
  </Card>

  <Card title="ViewModel & Data" icon="database" href="/ui-kit/android/customization-viewmodel-data">
    Custom ViewModels and repositories
  </Card>
</CardGroup>


# Message List
Source: https://www.cometchat.com/docs/ui-kit/android/message-list

Scrollable list of messages for a conversation with real-time updates, reactions, threaded replies, and message actions.

`CometChatMessageList` renders a scrollable list of messages for a conversation with real-time updates for new messages, edits, deletions, reactions, and threaded replies.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatMessageList` is a message display component. It requires either a `User` or `Group` object to fetch and render messages. Wire it with `CometChatMessageHeader` and `CometChatMessageComposer` to build a complete messaging layout.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_chat.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
        android:id="@+id/message_list"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    ```kotlin lines theme={null}
    val messageList = findViewById<CometChatMessageList>(R.id.message_list)
    messageList.setUser(user)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add to your layout XML:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
        android:id="@+id/message_list"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    Set a `User` or `Group` — this is required:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.your_layout)

        val messageList = findViewById<CometChatMessageList>(R.id.message_list)
        messageList.setUser(user)
        // or messageList.setGroup(group)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    @Composable
    fun MessagesScreen() {
        CometChatMessageList(
            user = user
            // or group = group
        )
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

<Warning>
  Simply adding the `MessageList` component to the layout will only display the loading indicator. You must supply a `User` or `Group` object to fetch messages.
</Warning>

***

## Filtering

Pass a `MessagesRequest.MessagesRequestBuilder` to control what loads:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setMessagesRequestBuilder(
        MessagesRequest.MessagesRequestBuilder()
            .setSearchKeyword("hello")
            .setLimit(30)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        messagesRequestBuilder = MessagesRequest.MessagesRequestBuilder()
            .setSearchKeyword("hello")
            .setLimit(30)
    )
    ```
  </Tab>
</Tabs>

### Filter Recipes

| Recipe                | Builder method               |
| --------------------- | ---------------------------- |
| Search by keyword     | `.setSearchKeyword("hello")` |
| Filter by UID         | `.setUID("user_uid")`        |
| Filter by GUID        | `.setGUID("group_guid")`     |
| Limit per page        | `.setLimit(30)`              |
| Unread only           | `.setUnread(true)`           |
| Hide deleted messages | `.hideDeletedMessages(true)` |

<Warning>
  Pass the builder object, not the result of `.build()`. The component calls `.build()` internally.
</Warning>

***

## Actions and Events

### Callback Methods

#### `onThreadRepliesClick`

Fires when a user taps a threaded message bubble.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setOnThreadRepliesClick { context, baseMessage, template ->
        // Navigate to thread view
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        onThreadRepliesClick = { context, baseMessage, template ->
            // Navigate to thread view
        }
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setOnError { exception ->
        Log.e("MessageList", "Error: ${exception.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        onError = { exception ->
            Log.e("MessageList", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched and loaded.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setOnLoad { messages ->
        Log.d("MessageList", "Loaded ${messages.size}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        onLoad = { messages ->
            Log.d("MessageList", "Loaded ${messages.size}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setOnEmpty {
        Log.d("MessageList", "No messages")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        onEmpty = { /* no messages */ }
    )
    ```
  </Tab>
</Tabs>

### SDK Events (Real-Time, Automatic)

The component listens to SDK message events internally. No manual setup needed.

> Automatic: new messages, edits, deletions, and reactions update the list in real time.

***

## Functionality

| Method (Kotlin XML)                  | Compose Parameter                  | Description                                                                                                                                   |
| ------------------------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `setUser(user)`                      | `user = user`                      | Set user for 1-on-1 conversation                                                                                                              |
| `setGroup(group)`                    | `group = group`                    | Set group for group conversation                                                                                                              |
| `setHideLoadingState(true)`          | `hideLoadingState = true`          | Hide loading indicator                                                                                                                        |
| `setHideEmptyState(true)`            | `hideEmptyState = true`            | Hide empty state view                                                                                                                         |
| `setHideErrorState(true)`            | `hideErrorState = true`            | Hide error state view                                                                                                                         |
| `setStartFromUnreadMessages(true)`   | `startFromUnreadMessages = true`   | Scroll to first unread on load                                                                                                                |
| `setLoadLastAgentConversation(true)` | `loadLastAgentConversation = true` | Load last agent conversation                                                                                                                  |
| `setMessagesRequestBuilder(builder)` | `messagesRequestBuilder = builder` | Custom message request builder                                                                                                                |
| `setBubbleFactories(list)`           | `bubbleFactories = list`           | Set custom bubble factories for message types                                                                                                 |
| `setOnThreadRepliesClick { }`        | `onThreadRepliesClick = { }`       | Thread reply tap callback                                                                                                                     |
| `setEnableMultipleAttachments(true)` | `enableMultipleAttachments = true` | Render multi-attachment messages with per-type bubbles and batch grouping (default `true`). See [Multiple Attachments](#multiple-attachments) |

***

## Multiple Attachments

Media messages that carry multiple attachments render with dedicated per-type bubbles — an image grid for images, a video grid for videos, a stacked player list for audio files, and a connected card stack for documents (see [Message Bubble Styling](/docs/ui-kit/android/message-bubble-styling) for each one).

When a single composer send is split into several messages (one per attachment type), the list **groups them visually as one batch**: the avatar and sender name appear only on the first message of the batch, the timestamp and read receipt only on the last, while reactions stay per message. Grouping is derived from list-neighbor adjacency on the `batchId` the composer stamps on each message — there are no separate index/count keys. A mic-recorded voice note carries a `voice_note` marker and always renders standalone, never grouped.

The behavior is on by default and can be toggled:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val messageList = findViewById<CometChatMessageList>(R.id.message_list)
    messageList.setEnableMultipleAttachments(true) // default
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        enableMultipleAttachments = true // default
    )
    ```
  </Tab>
</Tabs>

Setting it to `false` renders every media message with the classic single-attachment bubbles instead.

***

## Custom View Slots

### Header View

Custom view displayed at the top of the message list.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setHeaderView(View.inflate(context, R.layout.custom_header_layout, null))
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        headerView = {
            Row {
                Text("Notes")
                Spacer(Modifier.width(8.dp))
                Text("Pinned Messages")
            }
        }
    )
    ```
  </Tab>
</Tabs>

### Footer View

Custom view displayed at the bottom of the message list.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setFooterView(View.inflate(context, R.layout.custom_footer_layout, null))
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        footerView = {
            Text("End of messages")
        }
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setEmptyView(customEmptyView)
    messageList.setErrorView(customErrorView)
    messageList.setLoadingView(customLoadingView)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        emptyView = { Text("No messages yet") },
        errorView = { onRetry -> Button(onClick = onRetry) { Text("Retry") } },
        loadingView = { CircularProgressIndicator() }
    )
    ```
  </Tab>
</Tabs>

### Text Formatters (Mentions)

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)
    mentionFormatter.setMessageListMentionTextStyle(context, R.style.CustomMentionsStyle)

    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)
    messageList.setTextFormatters(textFormatters)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    val mentionFormatter = CometChatMentionsFormatter(context)

    CometChatMessageList(
        user = user,
        textFormatters = listOf(mentionFormatter)
    )
    ```
  </Tab>
</Tabs>

***

## Bubble Factory

`CometChatMessageList` uses a factory-based pattern to render message content. Each message type (text, image, video, etc.) has a corresponding `BubbleFactory` that creates and binds the bubble view. You can replace existing factories or register new ones for custom message types.

### How It Works

When a message is displayed, the list resolves a factory key from the message's `category` and `type` (e.g., `message_text`, `custom_location`). If a matching `BubbleFactory` is registered, it handles view creation and binding. Otherwise, the built-in `InternalContentRenderer` handles default rendering.

A `BubbleFactory` has two lifecycle phases:

1. `create*View(context)` — called once when the ViewHolder is created. The message object is **not** available at this point.
2. `bind*View(view, message, alignment, ...)` — called every time a message is displayed. This is where you populate the view with message data.

### Replacing an Existing Bubble Factory

Override how a built-in message type renders by registering a factory with the same category and type:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    class CustomTextBubbleFactory : BubbleFactory() {

        override fun getCategory(): String = CometChatConstants.CATEGORY_MESSAGE
        override fun getType(): String = CometChatConstants.MESSAGE_TYPE_TEXT

        override fun createContentView(context: Context): View {
            return TextView(context).apply {
                setPadding(24, 16, 24, 16)
            }
        }

        override fun bindContentView(
            view: View,
            message: BaseMessage,
            alignment: UIKitConstants.MessageBubbleAlignment,
            holder: RecyclerView.ViewHolder?,
            position: Int
        ) {
            (view as TextView).text = (message as? TextMessage)?.text ?: ""
        }
    }

    // Replace the default text bubble
    messageList.setBubbleFactories(listOf(CustomTextBubbleFactory()))
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    class CustomTextBubbleFactory : BubbleFactory {

        override fun getCategory(): String = CometChatConstants.CATEGORY_MESSAGE
        override fun getType(): String = CometChatConstants.MESSAGE_TYPE_TEXT

        override fun getContentView(
            message: BaseMessage,
            alignment: UIKitConstants.MessageBubbleAlignment,
            style: CometChatMessageBubbleStyle,
            textFormatters: List<CometChatTextFormatter>
        ): @Composable () -> Unit = {
            Text(
                text = (message as? TextMessage)?.text ?: "",
                modifier = Modifier.padding(horizontal = 24.dp, vertical = 16.dp)
            )
        }
    }

    CometChatMessageList(
        user = user,
        bubbleFactories = listOf(CustomTextBubbleFactory())
    )
    ```
  </Tab>
</Tabs>

### Adding a New Bubble Factory for Custom Messages

Register a factory for a custom message type that the SDK doesn't handle by default:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    class LocationBubbleFactory : BubbleFactory() {

        override fun getCategory(): String = CometChatConstants.CATEGORY_CUSTOM
        override fun getType(): String = "location"

        override fun createContentView(context: Context): View {
            return LayoutInflater.from(context)
                .inflate(R.layout.bubble_location, null)
        }

        override fun bindContentView(
            view: View,
            message: BaseMessage,
            alignment: UIKitConstants.MessageBubbleAlignment,
            holder: RecyclerView.ViewHolder?,
            position: Int
        ) {
            val customMessage = message as? CustomMessage ?: return
            val lat = customMessage.customData?.optDouble("latitude") ?: 0.0
            val lng = customMessage.customData?.optDouble("longitude") ?: 0.0
            view.findViewById<TextView>(R.id.tv_coordinates).text = "$lat, $lng"
        }
    }

    messageList.setBubbleFactories(listOf(LocationBubbleFactory()))
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    class LocationBubbleFactory : BubbleFactory {

        override fun getCategory(): String = CometChatConstants.CATEGORY_CUSTOM
        override fun getType(): String = "location"

        override fun getContentView(
            message: BaseMessage,
            alignment: UIKitConstants.MessageBubbleAlignment,
            style: CometChatMessageBubbleStyle,
            textFormatters: List<CometChatTextFormatter>
        ): @Composable () -> Unit = {
            val customMessage = message as? CustomMessage
            val lat = customMessage?.customData?.optDouble("latitude") ?: 0.0
            val lng = customMessage?.customData?.optDouble("longitude") ?: 0.0
            Text(text = "$lat, $lng")
        }
    }

    CometChatMessageList(
        user = user,
        bubbleFactories = listOf(LocationBubbleFactory())
    )
    ```
  </Tab>
</Tabs>

### Replacing the Entire Bubble

Override `getBubbleView` to replace the entire message bubble (including all slots like header, footer, avatar) instead of just the content area:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    class FullCustomBubbleFactory : BubbleFactory() {

        override fun getCategory(): String = CometChatConstants.CATEGORY_CUSTOM
        override fun getType(): String = "meeting"

        override fun createBubbleView(context: Context): View {
            return LayoutInflater.from(context)
                .inflate(R.layout.bubble_meeting_full, null)
        }

        override fun bindBubbleView(
            view: View,
            message: BaseMessage,
            alignment: UIKitConstants.MessageBubbleAlignment,
            holder: RecyclerView.ViewHolder?,
            position: Int
        ) {
            val customMessage = message as? CustomMessage ?: return
            view.findViewById<TextView>(R.id.tv_meeting_title).text =
                customMessage.customData?.optString("title") ?: "Meeting"
        }
    }

    messageList.setBubbleFactories(listOf(FullCustomBubbleFactory()))
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    class FullCustomBubbleFactory : BubbleFactory {

        override fun getCategory(): String = CometChatConstants.CATEGORY_CUSTOM
        override fun getType(): String = "meeting"

        override fun getBubbleView(
            message: BaseMessage,
            alignment: UIKitConstants.MessageBubbleAlignment
        ): (@Composable () -> Unit)? = {
            val customMessage = message as? CustomMessage
            val title = customMessage?.customData?.optString("title") ?: "Meeting"
            Text(text = title)
        }
    }

    CometChatMessageList(
        user = user,
        bubbleFactories = listOf(FullCustomBubbleFactory())
    )
    ```
  </Tab>
</Tabs>

### Bubble Slot Reference

Each `BubbleFactory` can override individual slots within the bubble:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    | Slot          | Create Method            | Bind Method            | Description                                                             |
    | ------------- | ------------------------ | ---------------------- | ----------------------------------------------------------------------- |
    | Bubble (full) | `createBubbleView()`     | `bindBubbleView()`     | Replaces the entire bubble. When non-null, all other slots are ignored. |
    | Content       | `createContentView()`    | `bindContentView()`    | Main message content (required).                                        |
    | Leading       | `createLeadingView()`    | `bindLeadingView()`    | Avatar area on the left side.                                           |
    | Header        | `createHeaderView()`     | `bindHeaderView()`     | Sender name and timestamp.                                              |
    | Reply         | `createReplyView()`      | `bindReplyView()`      | Quoted/reply-to message preview.                                        |
    | Bottom        | `createBottomView()`     | `bindBottomView()`     | Below content (e.g., moderation).                                       |
    | Status Info   | `createStatusInfoView()` | `bindStatusInfoView()` | Timestamp and read receipts.                                            |
    | Thread        | `createThreadView()`     | `bindThreadView()`     | Threaded replies indicator.                                             |
    | Footer        | `createFooterView()`     | `bindFooterView()`     | Reactions and additional footer content.                                |
  </Tab>

  <Tab title="Jetpack Compose">
    | Slot          | Method                | Description                                                             |
    | ------------- | --------------------- | ----------------------------------------------------------------------- |
    | Bubble (full) | `getBubbleView()`     | Replaces the entire bubble. When non-null, all other slots are ignored. |
    | Content       | `getContentView()`    | Main message content (required).                                        |
    | Leading       | `getLeadingView()`    | Avatar area on the left side.                                           |
    | Header        | `getHeaderView()`     | Sender name and timestamp.                                              |
    | Reply         | `getReplyView()`      | Quoted/reply-to message preview.                                        |
    | Bottom        | `getBottomView()`     | Below content (e.g., moderation).                                       |
    | Status Info   | `getStatusInfoView()` | Timestamp and read receipts.                                            |
    | Thread        | `getThreadView()`     | Threaded replies indicator.                                             |
    | Footer        | `getFooterView()`     | Reactions and additional footer content.                                |
  </Tab>
</Tabs>

***

## Bubble Slot View Providers

While `BubbleFactory` customizes rendering per message type, slot view providers let you override a specific slot across all message types. This is useful when you want consistent customization (e.g., always show a custom avatar or always add a custom footer) regardless of the message type.

<Note>
  Slot view providers take priority over `BubbleFactory` slot methods. If both are set, the provider wins.
</Note>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Use `BubbleViewProvider` — an interface with `createView()` (called once per ViewHolder) and `bindView()` (called each time a message binds):

    ```kotlin lines theme={null}
    // Custom leading view (avatar) for all messages
    messageList.setLeadingViewProvider(object : BubbleViewProvider {
        override fun createView(
            context: Context,
            message: BaseMessage,
            alignment: UIKitConstants.MessageBubbleAlignment
        ): View? {
            return if (alignment == UIKitConstants.MessageBubbleAlignment.LEFT) {
                CometChatAvatar(context)
            } else null
        }

        override fun bindView(
            view: View,
            message: BaseMessage,
            alignment: UIKitConstants.MessageBubbleAlignment
        ) {
            (view as? CometChatAvatar)?.setUser(message.sender)
        }
    })

    // Custom status info view for all messages
    messageList.setStatusInfoViewProvider(object : BubbleViewProvider {
        override fun createView(
            context: Context,
            message: BaseMessage,
            alignment: UIKitConstants.MessageBubbleAlignment
        ): View? {
            return TextView(context).apply { textSize = 10f }
        }

        override fun bindView(
            view: View,
            message: BaseMessage,
            alignment: UIKitConstants.MessageBubbleAlignment
        ) {
            (view as? TextView)?.text = formatTimestamp(message.sentAt)
        }
    })
    ```

    Available provider setters:

    | Method                        | Slot                                   |
    | ----------------------------- | -------------------------------------- |
    | `setLeadingViewProvider()`    | Avatar area                            |
    | `setHeaderViewProvider()`     | Sender name / timestamp                |
    | `setReplyViewProvider()`      | Reply-to preview                       |
    | `setContentViewProvider()`    | Main content (overrides all factories) |
    | `setBottomViewProvider()`     | Below content (moderation)             |
    | `setStatusInfoViewProvider()` | Timestamp / receipts                   |
    | `setThreadViewProvider()`     | Thread replies indicator               |
    | `setFooterViewProvider()`     | Reactions / footer                     |
  </Tab>

  <Tab title="Jetpack Compose">
    Pass composable lambdas that receive the message and its alignment:

    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        leadingView = { message, alignment ->
            if (alignment == UIKitConstants.MessageBubbleAlignment.LEFT) {
                CometChatAvatar(user = message.sender)
            }
        },
        statusInfoView = { message, alignment ->
            Text(
                text = formatTimestamp(message.sentAt),
                style = CometChatTheme.typography.caption1Regular
            )
        },
        footerView = { message, alignment ->
            // Custom reactions display
            MessageReactions(message = message)
        }
    )
    ```

    Available slot parameters:

    | Parameter        | Type                                                  | Slot                                   |
    | ---------------- | ----------------------------------------------------- | -------------------------------------- |
    | `leadingView`    | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Avatar area                            |
    | `headerView`     | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Sender name / timestamp                |
    | `replyView`      | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Reply-to preview                       |
    | `contentView`    | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Main content (overrides all factories) |
    | `bottomView`     | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Below content (moderation)             |
    | `statusInfoView` | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Timestamp / receipts                   |
    | `threadView`     | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Thread replies indicator               |
    | `footerView`     | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Reactions / footer                     |
  </Tab>
</Tabs>

***

## Message Options

Message options are the contextual actions shown when a user long-presses a message bubble (e.g., Reply, Copy, Edit, Delete). You can control their visibility, replace the entire options list, or append custom options.

### Toggling Default Option Visibility

Each built-in option has a visibility setter. Pass `View.VISIBLE` or `View.GONE`:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Hide specific options
    messageList.setDeleteMessageOptionVisibility(View.GONE)
    messageList.setEditMessageOptionVisibility(View.GONE)
    messageList.setTranslateMessageOptionVisibility(View.GONE)

    // Show an option that's hidden by default
    messageList.setMarkAsUnreadOptionVisibility(View.VISIBLE)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        hideDeleteOption = true,
        hideEditOption = true,
        hideTranslateOption = true,
        showMarkAsUnreadOption = true
    )
    ```
  </Tab>
</Tabs>

Available visibility methods (Kotlin XML):

| Method                                  | Default   | Description       |
| --------------------------------------- | --------- | ----------------- |
| `setReplyInThreadOptionVisibility()`    | `VISIBLE` | Reply in thread   |
| `setReplyOptionVisibility()`            | `VISIBLE` | Reply to message  |
| `setCopyMessageOptionVisibility()`      | `VISIBLE` | Copy message text |
| `setEditMessageOptionVisibility()`      | `VISIBLE` | Edit sent message |
| `setDeleteMessageOptionVisibility()`    | `VISIBLE` | Delete message    |
| `setMessageReactionOptionVisibility()`  | `VISIBLE` | Add reaction      |
| `setMessageInfoOptionVisibility()`      | `VISIBLE` | View message info |
| `setTranslateMessageOptionVisibility()` | `VISIBLE` | Translate message |
| `setShareMessageOptionVisibility()`     | `VISIBLE` | Share message     |
| `setMarkAsUnreadOptionVisibility()`     | `GONE`    | Mark as unread    |

### Replacing All Options (`setOptions`)

Use `setOptions` to completely replace the default options for a message. Return a list to override, or `null` to fall back to defaults:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setOptions { message ->
        listOf(
            CometChatMessageOption(
                id = "custom_pin",
                title = "Pin Message",
                icon = R.drawable.ic_pin,
                onClick = { pinMessage(message) }
            ),
            CometChatMessageOption(
                id = UIKitConstants.MessageOption.COPY,
                title = context.getString(R.string.cometchat_copy),
                icon = R.drawable.cometchat_ic_copy,
                onClick = { copyMessage(message) }
            )
        )
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        options = { message ->
            listOf(
                CometChatMessageOption(
                    id = "custom_pin",
                    title = "Pin Message",
                    icon = R.drawable.ic_pin,
                    onClick = { pinMessage(message) }
                ),
                CometChatMessageOption(
                    id = UIKitConstants.MessageOption.COPY,
                    title = context.getString(R.string.cometchat_copy),
                    icon = R.drawable.cometchat_ic_copy,
                    onClick = { copyMessage(message) }
                )
            )
        }
    )
    ```
  </Tab>
</Tabs>

> When `setOptions` returns a non-null list, `addOptions` is not invoked.

### Appending Custom Options (`addOptions`)

Use `addOptions` to append additional options after the default ones. This is invoked only when `setOptions` is not set or returns `null`:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.addOptions { message ->
        listOf(
            CometChatMessageOption(
                id = "custom_bookmark",
                title = "Bookmark",
                icon = R.drawable.ic_bookmark,
                onClick = { bookmarkMessage(message) }
            ),
            CometChatMessageOption(
                id = "custom_remind",
                title = "Remind Me",
                icon = R.drawable.ic_alarm,
                onClick = { setReminder(message) }
            )
        )
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        addOptions = { message ->
            listOf(
                CometChatMessageOption(
                    id = "custom_bookmark",
                    title = "Bookmark",
                    icon = R.drawable.ic_bookmark,
                    onClick = { bookmarkMessage(message) }
                ),
                CometChatMessageOption(
                    id = "custom_remind",
                    title = "Remind Me",
                    icon = R.drawable.ic_alarm,
                    onClick = { setReminder(message) }
                )
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Conditional Options Per Message

Both `setOptions` and `addOptions` receive the `BaseMessage`, so you can return different options based on message type, sender, or any other condition:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setOptions { message ->
        when {
            // Custom options for your own messages
            message.sender?.uid == CometChat.getLoggedInUser()?.uid -> listOf(
                CometChatMessageOption(id = "edit", title = "Edit", icon = R.drawable.cometchat_ic_edit),
                CometChatMessageOption(id = "delete", title = "Delete", icon = R.drawable.cometchat_ic_delete)
            )
            // Default options for others' messages
            else -> null
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        options = { message ->
            when {
                message.sender?.uid == CometChat.getLoggedInUser()?.uid -> listOf(
                    CometChatMessageOption(id = "edit", title = "Edit", icon = R.drawable.cometchat_ic_edit),
                    CometChatMessageOption(id = "delete", title = "Delete", icon = R.drawable.cometchat_ic_delete)
                )
                else -> null // fall back to defaults
            }
        }
    )
    ```
  </Tab>
</Tabs>

### CometChatMessageOption Reference

| Property          | Type               | Description                                                                |
| ----------------- | ------------------ | -------------------------------------------------------------------------- |
| `id`              | `String`           | Unique identifier (use `UIKitConstants.MessageOption.*` for built-in IDs). |
| `title`           | `String`           | Display text for the option.                                               |
| `titleColor`      | `@ColorInt Int`    | Text color (0 for default).                                                |
| `icon`            | `@DrawableRes Int` | Drawable resource for the option icon.                                     |
| `iconTintColor`   | `@ColorInt Int`    | Icon tint color (0 for default).                                           |
| `titleAppearance` | `@StyleRes Int`    | Text appearance style resource.                                            |
| `backgroundColor` | `@ColorInt Int`    | Background color for the option row.                                       |
| `onClick`         | `(() -> Unit)?`    | Callback invoked when the option is tapped.                                |

***

## Style

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Define a custom style in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="CustomMessageListStyle" parent="CometChatMessageListStyle">
        <item name="cometchatMessageListBackgroundColor">#F5F5F5</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatMessageListStyle">@style/CustomMessageListStyle</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        style = CometChatMessageListStyle.default().copy(
            backgroundColor = Color(0xFFF5F5F5)
        )
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

See [Component Styling](/docs/ui-kit/android/component-styling) for the full reference.

***

## ViewModel

```kotlin lines theme={null}
val viewModel = ViewModelProvider(this)
    .get(CometChatMessageListViewModel::class.java)
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        messageListViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

See [ViewModel & Data](/docs/ui-kit/android/customization-viewmodel-data) for state observation and custom repositories.

***

## Next Steps

<CardGroup>
  <Card title="Message Header" icon="heading" href="/ui-kit/android/message-header">
    Display user/group info in the toolbar
  </Card>

  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/android/message-composer">
    Rich input for sending messages
  </Card>

  <Card title="Message Template" icon="puzzle-piece" href="/ui-kit/android/message-template">
    Customize message bubble structure
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/android/component-styling">
    Detailed styling reference
  </Card>
</CardGroup>


# Message Template
Source: https://www.cometchat.com/docs/ui-kit/android/message-template

Define and customize message bubble structure, layout, and behavior using MessageTemplate.

A `MessageTemplate` defines and customizes both the structure and the behavior of the MessageBubble. It acts as a schema for creating message bubble components, allowing you to manage the appearance and interactions of message bubbles within your application.

## When to Use This

* Customize the header, content, footer, bottom, or status info view of a message bubble
* Replace the default bubble layout with a completely custom view
* Add or modify the long-press options on a message bubble
* Create a new template for a custom message type (e.g., a contact card)
* Change how a specific message type (text, image, etc.) renders in the [MessageList](/docs/ui-kit/android/message-list)

## Prerequisites

* CometChat Android UI Kit dependency added
* `CometChatUIKit.init()` called and completed
* A logged-in CometChat user
* Familiarity with the [MessageList](/docs/ui-kit/android/message-list) component

***

## Quick Start

1. Get the list of existing message templates from the data source:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val messageTemplates = CometChatUIKit.getDataSource()
        .getMessageTemplates(messageList.additionParameter)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    val messageTemplates = CometChatUIKit.getDataSource()
        .getMessageTemplates(additionParameter)
    ```
  </Tab>
</Tabs>

2. Find the template for the message type you want to customize:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    for (template in messageTemplates) {
        if (template.type == UIKitConstants.MessageType.TEXT) {
            // Customize text message template
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    for (template in messageTemplates) {
        if (template.type == UIKitConstants.MessageType.TEXT) {
            // Customize text message template
        }
    }
    ```
  </Tab>
</Tabs>

3. Customize a view on the matched template:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    template.setContentView(object : MessagesViewHolderListener() {
        override fun createView(
            context: Context,
            cometChatMessageBubble: CometChatMessageBubble,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment
        ): View {
            return LayoutInflater.from(context).inflate(R.layout.your_custom_layout, null)
        }

        override fun bindView(
            context: Context, view: View, baseMessage: BaseMessage,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment,
            viewHolder: RecyclerView.ViewHolder, list: List<BaseMessage>, i: Int
        ) {
            // Bind your custom view data here
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    template.setContentView { baseMessage, alignment ->
        // Return your custom composable content
        Text(text = (baseMessage as? TextMessage)?.text ?: "")
    }
    ```
  </Tab>
</Tabs>

4. Apply the modified templates to the MessageList:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    messageList.setTemplates(messageTemplates)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatMessageList(
        user = user,
        templates = messageTemplates
    )
    ```
  </Tab>
</Tabs>

***

## Core Concepts

### MessageBubble Structure

<Frame>
  <img />
</Frame>

The `MessageBubble` structure is broken down into these views:

1. **Leading view** — Sender's avatar. Left for incoming, right for outgoing.
2. **Header view** — Sender's name. Useful in group chats.
3. **Content view** — Core message content (text, images, videos, etc.).
4. **Bottom view** — Additional elements like link previews or "load more" buttons.
5. **Footer view** — Timestamp and delivery/read status.

### Template Properties

* **Type**: `setType()` maps the template to a `CometChatMessage` type.
* **Category**: `setCategory()` links the template with a message category.

```kotlin lines theme={null}
messageTemplate.setType(UIKitConstants.MessageType.CUSTOM)
messageTemplate.setCategory(UIKitConstants.MessageCategory.CUSTOM)
```

***

## Implementation

### Header View

Customize the header area above the content view.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    template.setHeaderView(object : MessagesViewHolderListener() {
        override fun createView(
            context: Context,
            cometChatMessageBubble: CometChatMessageBubble,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment
        ): View {
            return layoutInflater.inflate(R.layout.message_template_header_view, null)
        }

        override fun bindView(
            context: Context, view: View, baseMessage: BaseMessage,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment,
            viewHolder: RecyclerView.ViewHolder, list: List<BaseMessage>, i: Int
        ) {
            val textView = view.findViewById<TextView>(R.id.name_with_status)
            textView.text = baseMessage.sender.name + " • 🗓️ In meeting"
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    template.setHeaderView { baseMessage, alignment ->
        Text(
            text = "${baseMessage.sender.name} • 🗓️ In meeting",
            style = CometChatTheme.typography.caption2Regular,
            color = CometChatTheme.colors.primary
        )
    }
    ```
  </Tab>
</Tabs>

### Content View

Customize the main content area of the message bubble.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    template.setContentView(object : MessagesViewHolderListener() {
        override fun createView(
            context: Context,
            cometChatMessageBubble: CometChatMessageBubble,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment
        ): View {
            return LayoutInflater.from(context).inflate(R.layout.image_bubble_content_view, null)
        }

        override fun bindView(
            context: Context, view: View, baseMessage: BaseMessage,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment,
            viewHolder: RecyclerView.ViewHolder, list: List<BaseMessage>, i: Int
        ) {
            val imageBubble = view.findViewById<CometChatImageBubble>(R.id.imageBubble)
            val mediaMessage = baseMessage as MediaMessage
            val attachment = mediaMessage.attachment
            imageBubble.setImageUrl(
                Utils.getFileFromLocalPath(mediaMessage),
                attachment?.fileUrl ?: "",
                attachment?.fileExtension?.equals("gif", ignoreCase = true) ?: false
            )
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    template.setContentView { baseMessage, alignment ->
        val mediaMessage = baseMessage as? MediaMessage
        Column {
            CometChatImageBubble(
                imageUrl = mediaMessage?.attachment?.fileUrl ?: ""
            )
            Text(
                text = "Buy Now",
                textAlign = TextAlign.Center,
                color = CometChatTheme.colors.primary
            )
        }
    }
    ```
  </Tab>
</Tabs>

### Status Info View

Customize the status info area (delivery/read status indicators).

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Replace status info with a minimal spacer
    template.setStatusInfoView(object : MessagesViewHolderListener() {
        override fun createView(
            context: Context,
            cometChatMessageBubble: CometChatMessageBubble,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment
        ): View {
            val view = View(context)
            view.layoutParams = LinearLayout.LayoutParams(1.dp, 12.dp)
            return view
        }

        override fun bindView(
            context: Context, view: View, baseMessage: BaseMessage,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment,
            viewHolder: RecyclerView.ViewHolder, list: List<BaseMessage>, i: Int
        ) { }
    })

    // Move status content to footer
    template.setFooterView(object : MessagesViewHolderListener() {
        override fun createView(
            context: Context,
            cometChatMessageBubble: CometChatMessageBubble,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment
        ): View {
            return LayoutInflater.from(context).inflate(R.layout.status_info_layout, null)
        }

        override fun bindView(
            context: Context, view: View, baseMessage: BaseMessage,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment,
            viewHolder: RecyclerView.ViewHolder, list: List<BaseMessage>, i: Int
        ) {
            val tvTime = view.findViewById<TextView>(R.id.time)
            val receipt = view.findViewById<CometChatMessageReceipt>(R.id.receipt)
            if (messageBubbleAlignment == UIKitConstants.MessageBubbleAlignment.RIGHT) {
                receipt.visibility = View.VISIBLE
                receipt.setMessageReceipt(MessageReceiptUtils.MessageReceipt(baseMessage))
            } else {
                receipt.visibility = View.GONE
            }
            tvTime.text = SimpleDateFormat("hh:mm a").format(baseMessage.sentAt * 1000)
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    template.setStatusInfoView { _, _ ->
        Spacer(Modifier.height(12.dp))
    }

    template.setFooterView { baseMessage, alignment ->
        Row(
            modifier = Modifier.fillMaxWidth(),
            horizontalArrangement = Arrangement.End,
            verticalAlignment = Alignment.CenterVertically
        ) {
            Text(
                text = SimpleDateFormat("hh:mm a").format(baseMessage.sentAt * 1000),
                style = CometChatTheme.typography.caption2Regular
            )
            if (alignment == UIKitConstants.MessageBubbleAlignment.RIGHT) {
                CometChatMessageReceipt(message = baseMessage)
            }
        }
    }
    ```
  </Tab>
</Tabs>

### Bottom View

Extend the bubble with additional elements beneath the content view.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    template.setBottomView(object : MessagesViewHolderListener() {
        override fun createView(
            context: Context,
            cometChatMessageBubble: CometChatMessageBubble,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment
        ): View {
            return LayoutInflater.from(context).inflate(R.layout.message_template_bottom_view, null)
        }

        override fun bindView(
            context: Context, view: View, baseMessage: BaseMessage,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment,
            viewHolder: RecyclerView.ViewHolder, list: List<BaseMessage>, i: Int
        ) {
            // Bind bottom view data
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    template.setBottomView { baseMessage, alignment ->
        // Custom bottom content
        Text("Link preview or additional info")
    }
    ```
  </Tab>
</Tabs>

### Footer View

Customize the footer area (timestamp and delivery status).

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    template.setFooterView(object : MessagesViewHolderListener() {
        override fun createView(
            context: Context,
            cometChatMessageBubble: CometChatMessageBubble,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment
        ): View {
            return LayoutInflater.from(context).inflate(R.layout.message_template_footer_view, null)
        }

        override fun bindView(
            context: Context, view: View, baseMessage: BaseMessage,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment,
            viewHolder: RecyclerView.ViewHolder, list: List<BaseMessage>, i: Int
        ) {
            val tvTime = view.findViewById<TextView>(R.id.time)
            tvTime.text = SimpleDateFormat("hh:mm a").format(baseMessage.sentAt * 1000)
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    template.setFooterView { baseMessage, alignment ->
        Text(
            text = SimpleDateFormat("hh:mm a").format(baseMessage.sentAt * 1000),
            style = CometChatTheme.typography.caption2Regular
        )
    }
    ```
  </Tab>
</Tabs>

### Bubble View

Replace the entire message bubble with a fully custom layout.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    template.setBubbleView(object : MessagesViewHolderListener() {
        override fun createView(
            context: Context,
            cometChatMessageBubble: CometChatMessageBubble,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment
        ): View {
            return LayoutInflater.from(context).inflate(R.layout.custom_bubble_view, null)
        }

        override fun bindView(
            context: Context, view: View, baseMessage: BaseMessage,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment,
            viewHolder: RecyclerView.ViewHolder, list: List<BaseMessage>, i: Int
        ) {
            // Bind entire custom bubble
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    template.setBubbleView { baseMessage, alignment ->
        Card {
            Column(Modifier.padding(12.dp)) {
                Text(baseMessage.sender.name)
                Text((baseMessage as? TextMessage)?.text ?: "")
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Options

Customize the long-press action menu for a message type.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    template.setOptions { context, baseMessage, isLeftAligned ->
        listOf(
            CometChatPopupMenu.MenuItem(
                id = "bookmark",
                name = "Bookmark",
                onClick = { /* handle */ }
            )
        )
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    template.setOptions { context, baseMessage, isLeftAligned ->
        listOf(
            MenuItem(id = "bookmark", name = "Bookmark", onClick = { /* handle */ })
        )
    }
    ```
  </Tab>
</Tabs>

***

## Creating a New Template

Create a template for a custom message type (e.g., a contact card):

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val contactTemplate = CometChatMessageTemplate()
    contactTemplate.setType("contact")
    contactTemplate.setCategory(UIKitConstants.MessageCategory.CUSTOM)

    contactTemplate.setContentView(object : MessagesViewHolderListener() {
        override fun createView(
            context: Context,
            cometChatMessageBubble: CometChatMessageBubble,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment
        ): View {
            return LayoutInflater.from(context).inflate(R.layout.contact_card_bubble, null)
        }

        override fun bindView(
            context: Context, view: View, baseMessage: BaseMessage,
            messageBubbleAlignment: UIKitConstants.MessageBubbleAlignment,
            viewHolder: RecyclerView.ViewHolder, list: List<BaseMessage>, i: Int
        ) {
            val customMessage = baseMessage as CustomMessage
            val name = view.findViewById<TextView>(R.id.contact_name)
            name.text = customMessage.customData?.getString("name") ?: ""
        }
    })

    // Add to existing templates
    val templates = CometChatUIKit.getDataSource()
        .getMessageTemplates(messageList.additionParameter)
    templates.add(contactTemplate)
    messageList.setTemplates(templates)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    val contactTemplate = CometChatMessageTemplate()
    contactTemplate.setType("contact")
    contactTemplate.setCategory(UIKitConstants.MessageCategory.CUSTOM)

    contactTemplate.setContentView { baseMessage, alignment ->
        val customMessage = baseMessage as? CustomMessage
        val name = customMessage?.customData?.optString("name") ?: ""
        Card {
            Row(Modifier.padding(12.dp), verticalAlignment = Alignment.CenterVertically) {
                CometChatAvatar(name = name)
                Spacer(Modifier.width(8.dp))
                Text(name)
            }
        }
    }

    val templates = CometChatUIKit.getDataSource()
        .getMessageTemplates(additionParameter)
        .toMutableList()
    templates.add(contactTemplate)

    CometChatMessageList(
        user = user,
        templates = templates
    )
    ```
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="messages" href="/ui-kit/android/message-list">
    Display messages in a conversation
  </Card>

  <Card title="Message Bubble Styling" icon="paintbrush" href="/ui-kit/android/message-bubble-styling">
    Style individual bubble types
  </Card>

  <Card title="Component Styling" icon="palette" href="/ui-kit/android/component-styling">
    Detailed styling reference
  </Card>

  <Card title="View Slots" icon="puzzle-piece" href="/ui-kit/android/customization-view-slots">
    Replace specific UI regions
  </Card>
</CardGroup>


# Methods
Source: https://www.cometchat.com/docs/ui-kit/android/methods

Use CometChatUIKit wrapper methods for initialization, authentication, user creation, and message sending.

<Accordion title="AI Integration Quick Reference">
  | Field              | Value                                                                                                         |
  | ------------------ | ------------------------------------------------------------------------------------------------------------- |
  | Kotlin (XML Views) | `com.cometchat:chatuikit-kotlin-android`                                                                      |
  | Jetpack Compose    | `com.cometchat:chatuikit-compose-android`                                                                     |
  | Import             | `com.cometchat.uikit.core.CometChatUIKit`                                                                     |
  | Init               | `CometChatUIKit.init(context, uiKitSettings, callback)`                                                       |
  | Login (dev)        | `CometChatUIKit.login("UID", callback)`                                                                       |
  | Login (prod)       | `CometChatUIKit.loginWithAuthToken("AUTH_TOKEN", callback)`                                                   |
  | Other methods      | `CometChatUIKit.logout()`, `CometChatUIKit.getLoggedInUser()`, `CometChatUIKit.createUser(user, callback)`    |
  | Send messages      | `CometChatUIKit.sendTextMessage()`, `CometChatUIKit.sendMediaMessage()`, `CometChatUIKit.sendCustomMessage()` |
  | Note               | Use these wrapper methods instead of raw SDK calls — they manage internal UI Kit eventing                     |
</Accordion>

`CometChatUIKit` provides wrapper methods around the CometChat SDK for initialization, authentication, user creation, date formatting, and sending messages — while automatically managing internal UI Kit events so that components like Message List and Conversations stay in sync.

## When to use this

* You need to initialize the CometChat UI Kit and SDK before rendering any UI components.
* You need to log a user in or out of CometChat using an Auth Key (development) or Auth Token (production).
* You need to create a new CometChat user dynamically from your app.
* You need to send text, media, or custom messages through the UI Kit so that the Message List and Conversations components update automatically.
* You need to customize how dates and times are displayed across all UI Kit components.

## Prerequisites

* The `com.cometchat:chatuikit-kotlin-android` or `com.cometchat:chatuikit-compose-android` dependency added to your project.
* Your CometChat App ID, Region, and Auth Key (or Auth Token) from the [CometChat dashboard](https://app.cometchat.com/).
* `CometChatUIKit.init()` called before invoking any other UI Kit method.

## API reference

### Initialization

#### Init

You must invoke this method before using any other methods provided by the UI Kit. This initialization ensures the UI Kit and Chat SDK function correctly in your application. Call this as one of the first lines of code in your application's lifecycle.

<Warning>
  Make sure you replace the `APP_ID`, `REGION` and `AUTH_KEY` with your CometChat App ID, Region and Auth Key in the below code. The `Auth Key` is an optional property of the `UIKitSettings` Class. It is intended for use primarily during proof-of-concept (POC) development or in the early stages of application development. You can use the [Auth Token](#login-using-auth-token) to log in securely.
</Warning>

**Signature:**

```kotlin theme={null}
import com.cometchat.uikit.core.CometChatUIKit
import com.cometchat.uikit.core.UIKitSettings

CometChatUIKit.init(context: Context, authSettings: UIKitSettings, callbackListener: CometChat.CallbackListener<String>)
```

> **What this does:** Accepts a `Context`, a `UIKitSettings` configuration object, and a `CallbackListener` that reports success or failure.

The `UIKitSettings` is an important parameter of the `init()` function. It serves as the base settings object, housing properties such as `appId`, `region`, and `authKey`.

| Method                               | Type                          | Description                                                                                                                           |
| ------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **setAppId**                         | `String`                      | Sets the unique ID for the app, available on dashboard                                                                                |
| **setRegion**                        | `String`                      | Sets the region for the app ('us' or 'eu')                                                                                            |
| **setAuthKey**                       | `String`                      | Sets the auth key for the app, available on dashboard                                                                                 |
| **subscribePresenceForAllUsers**     | `String`                      | Sets subscription type for tracking the presence of all users                                                                         |
| **subscribePresenceForFriends**      | `String`                      | Sets subscription type for tracking the presence of friends                                                                           |
| **subscribePresenceForRoles**        | `String`                      | Sets subscription type for tracking the presence of users with specified roles                                                        |
| **setAutoEstablishSocketConnection** | `Boolean`                     | Configures if web socket connections will established automatically on app initialization or be done manually, set to true by default |
| **setAIFeatures**                    | `List<AIExtensionDataSource>` | Sets the AI Features that need to be added in UI Kit                                                                                  |
| **setExtensions**                    | `List<ExtensionsDataSource>`  | Sets the list of extension that need to be added in UI Kit                                                                            |
| **dateTimeFormatterCallback**        | `DateTimeFormatterCallback`   | Interface containing callback methods to format different types of timestamps.                                                        |

**Usage:**

```kotlin theme={null}
import com.cometchat.uikit.core.CometChatUIKit
import com.cometchat.uikit.core.UIKitSettings

val uiKitSettings: UIKitSettings = UIKitSettingsBuilder()
    .setRegion(your_region)
    .setAppId(your_appID)
    .setAuthKey(your_authKey)
    .subscribePresenceForAllUsers()
    .build()

CometChatUIKit.init(context, uiKitSettings, object : CometChat.CallbackListener<String>() {
    override fun onSuccess(response: String) {
        Log.i(TAG, "CometChat init onSuccess: $response")
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "CometChat init exception: $e")
    }
})
```

> **What this does:** Creates a `UIKitSettings` object with your app ID, region, and auth key, then initializes the CometChat UI Kit. On success, the SDK and UI Kit are ready for use. On error, the `CometChatException` provides failure details.

***

### Authentication

#### Login using Auth Key

Only the `UID` of a user is needed to log in. This simple authentication procedure is useful when you are creating a POC or if you are in the development phase. For production apps, use [Auth Token](#login-using-auth-token) instead of Auth Key.

**Signature:**

```kotlin theme={null}
CometChatUIKit.login(uid: String, callbackListener: CometChat.CallbackListener<User>)
```

> **What this does:** Accepts a user ID string and a `CallbackListener` that returns the logged-in `User` object on success.

**Usage:**

```kotlin theme={null}
CometChatUIKit.login(UID, object : CometChat.CallbackListener<User>() {
    override fun onSuccess(user: User) {
        Log.i(TAG, "CometChat Login Successful : $user")
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "CometChat Login Failed : ${e.message}")
    }
})
```

> **What this does:** Logs in a user by their `UID` using the Auth Key configured during initialization. On success, the `User` object is returned.

***

#### Login using Auth Token

This advanced authentication procedure does not use the Auth Key directly in your client code thus ensuring safety.

1. [Create a User](https://api-explorer.cometchat.com/reference/creates-user) via the CometChat API when the user signs up in your app.
2. [Create an Auth Token](https://api-explorer.cometchat.com/reference/create-authtoken) via the CometChat API for the new user and save the token in your database.
3. Load the Auth Token in your client and pass it to the `loginWithAuthToken()` method.

**Signature:**

```kotlin theme={null}
CometChatUIKit.loginWithAuthToken(authToken: String, callbackListener: CometChat.CallbackListener<User>)
```

**Usage:**

```kotlin theme={null}
CometChatUIKit.loginWithAuthToken(AuthToken, object : CometChat.CallbackListener<User>() {
    override fun onSuccess(user: User) {
        Log.i(TAG, "CometChat Login Successful : $user")
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "CometChat Login Failed : ${e.message}")
    }
})
```

> **What this does:** Logs in a user using a server-generated Auth Token instead of an Auth Key. This is the recommended approach for production apps because the Auth Key never appears in client code.

***

### Logout

The CometChat UI Kit and Chat SDK effectively handle the session of the logged-in user within the framework. Before a new user logs in, it is crucial to clean this data to avoid potential conflicts or unexpected behavior. This can be achieved by invoking the `logout()` function.

**Signature:**

```kotlin theme={null}
CometChatUIKit.logout(callbackListener: CometChat.CallbackListener<String>)
```

**Usage:**

```kotlin theme={null}
CometChatUIKit.logout(object : CometChat.CallbackListener<String>() {
    override fun onSuccess(s: String) {
        // your action on logout
    }

    override fun onError(e: CometChatException) {
        // Error handling
    }
})
```

> **What this does:** Logs out the current user, clears the session data, and tears down the internal event system. Call this before logging in a different user to avoid conflicts.

***

### Create User

You can dynamically create users on CometChat using the `createUser()` function. This is useful when users are registered or authenticated by your system and then need to be created on CometChat.

**Signature:**

```kotlin theme={null}
CometChatUIKit.createUser(user: User, callbackListener: CometChat.CallbackListener<User>)
```

**Usage:**

```kotlin theme={null}
val user = User("user_uid", "user_name")
user.setAvatar("user_avatar_url")

CometChatUIKit.createUser(user, object : CometChat.CallbackListener<User>() {
    override fun onSuccess(user: User) {
        // Action on success
    }

    override fun onError(e: CometChatException) {
        // Action on error
    }
})
```

> **What this does:** Creates a new user on CometChat with the specified UID, name, and avatar URL. On success, the created `User` object is returned.

***

### DateFormatter

By providing a custom implementation of the `DateTimeFormatterCallback`, you can globally configure how time and date values are displayed across all UI components in the CometChat UI Kit. This ensures consistent formatting for labels such as "Today", "Yesterday", "X minutes ago", and more, throughout the entire application.

Each method in the interface corresponds to a specific case:

`time(long timestamp)` → Custom full timestamp format

`today(long timestamp)` → Called when a message is from today

`yesterday(long timestamp)` → Called for yesterday's messages

`lastWeek(long timestamp)` → Messages from the past week

`otherDays(long timestamp)` → Older messages

`minute(long timestamp)` / `hour(long timestamp)` → Exact time unit

`minutes(long diffInMinutesFromNow, long timestamp)` → e.g., "5 minutes ago"

`hours(long diffInHourFromNow, long timestamp)` → e.g., "2 hours ago"

**Usage:**

```kotlin theme={null}
import java.text.SimpleDateFormat
import java.util.*
import com.cometchat.uikit.core.UIKitSettings

val uiKitSettings = UIKitSettings.UIKitSettingsBuilder()
    .setAppId(appId)
    .setRegion(region)
    .setDateTimeFormatterCallback(object : DateTimeFormatterCallback {

        private val fullTimeFormatter = SimpleDateFormat("hh:mm a", Locale.getDefault())
        private val dateFormatter = SimpleDateFormat("dd MMM yyyy", Locale.getDefault())

        override fun time(timestamp: Long): String {
            return fullTimeFormatter.format(Date(timestamp))
        }

        override fun today(timestamp: Long): String {
            return "Today"
        }

        override fun yesterday(timestamp: Long): String {
            return "Yesterday"
        }

        override fun lastWeek(timestamp: Long): String {
            return "Last Week"
        }

        override fun otherDays(timestamp: Long): String {
            return dateFormatter.format(Date(timestamp))
        }

        override fun minutes(diffInMinutesFromNow: Long, timestamp: Long): String {
            return "$diffInMinutesFromNow mins ago"
        }

        override fun hours(diffInHourFromNow: Long, timestamp: Long): String {
            return "$diffInHourFromNow hrs ago"
        }
    })
    .setAuthKey(authKey)
    .subscribePresenceForAllUsers()
    .build()

CometChatUIKit.init(context, uiKitSettings, object : CometChat.CallbackListener<String>() {
    override fun onSuccess(s: String?) {
        Log.d("CometChatInit", "Success: $s")
    }

    override fun onError(e: CometChatException?) {
        Log.e("CometChatInit", "Error: ${e?.message}")
    }
})
```

> **What this does:** Configures a custom `DateTimeFormatterCallback` on `UIKitSettings` and passes it to `CometChatUIKit.init()`. This globally overrides how timestamps appear across all UI Kit components.

***

### Base Message

#### Text Message

To send a text message to a single user or a group, use the `sendTextMessage()` function. This function requires a `TextMessage` object as its argument, which contains the necessary information for delivering the message.

> It's essential to understand the difference between `CometChatUIKit.sendTextMessage()` and `CometChat.sendTextMessage()`. When you use `CometChatUIKit.sendTextMessage()`, it automatically adds the message to the Message List and Conversations components, taking care of all related cases for you. On the other hand, `CometChat.sendTextMessage()` only sends the message and doesn't automatically update these components in the UI Kit.

**Signature:**

```kotlin theme={null}
CometChatUIKit.sendTextMessage(textMessage: TextMessage, messageCallbackListener: CometChat.CallbackListener<TextMessage>)
```

**Usage:**

```kotlin theme={null}
val textMessage = TextMessage("receiver_uid", "your_text_message", CometChatConstants.RECEIVER_TYPE_USER)
CometChatUIKit.sendTextMessage(textMessage, object : CometChat.CallbackListener<TextMessage>() {
    override fun onSuccess(message: TextMessage) {
        // Action on success
    }

    override fun onError(e: CometChatException) {
        // Action on error
    }
})
```

> **What this does:** Creates a `TextMessage` targeting a user with the receiver type `RECEIVER_TYPE_USER`, then sends it through the UI Kit. The message automatically appears in the Message List and Conversations components.

***

#### Media Message

To send a media message to a single user or a group, use the `sendMediaMessage()` function. This function requires a `MediaMessage` object as its argument.

> When you use `CometChatUIKit.sendMediaMessage()`, it automatically adds the message to the Message List and Conversations components. `CometChat.sendMediaMessage()` only sends the message without updating UI Kit components.

**Signature:**

```kotlin theme={null}
CometChatUIKit.sendMediaMessage(mediaMessage: MediaMessage, messageCallbackListener: CometChat.CallbackListener<MediaMessage>)
```

**Usage:**

```kotlin theme={null}
val mediaMessage = MediaMessage("receiver_uid", File("your_filePath"), CometChatConstants.MESSAGE_TYPE_FILE, CometChatConstants.RECEIVER_TYPE_USER)

CometChatUIKit.sendMediaMessage(mediaMessage, object : CometChat.CallbackListener<MediaMessage>() {
    override fun onSuccess(mediaMessage: MediaMessage) {
        // Action on success
    }

    override fun onError(e: CometChatException) {
        // Action on error
    }
})
```

> **What this does:** Creates a `MediaMessage` with a file path and message type `MESSAGE_TYPE_FILE`, then sends it through the UI Kit.

***

#### Custom Message

To send a custom message to a single user or a group, use the `sendCustomMessage()` function. This function requires a `CustomMessage` object as its argument.

> When you use `CometChatUIKit.sendCustomMessage()`, it automatically adds the message to the Message List and Conversations components. `CometChat.sendCustomMessage()` only sends the message without updating UI Kit components.

**Signature:**

```kotlin theme={null}
CometChatUIKit.sendCustomMessage(customMessage: CustomMessage, messageCallbackListener: CometChat.CallbackListener<CustomMessage>)
```

**Usage:**

```kotlin theme={null}
val customType = "your_message_type"
val customData = JSONObject()

customData.put("key1", "value1")
customData.put("key2", "value2")
customData.put("key3", "value3")
customData.put("key4", "value4")

val customMessage = CustomMessage("receiver_uid", CometChatConstants.RECEIVER_TYPE_USER, customType, customData)

CometChatUIKit.sendCustomMessage(customMessage, object : CometChat.CallbackListener<CustomMessage>() {
    override fun onSuccess(customMessage: CustomMessage) {
        // Action on success
    }

    override fun onError(e: CometChatException) {
        // Action on error
    }
})
```

> **What this does:** Creates a `CustomMessage` with a custom type string and JSON data payload, then sends it through the UI Kit.

> Note: To display custom messages in the [MessageList](/docs/ui-kit/android/message-list), you must create and register a new [MessageTemplate](/docs/ui-kit/android/message-template) that defines how to render your custom message type.

***

## Next steps

<CardGroup>
  <Card title="Events Reference" icon="bolt" href="/ui-kit/android/events">
    Listen for real-time UI Kit events for users, groups, conversations, messages, and calls
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/android/message-list">
    Display and customize the message list where sent messages appear
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/android/conversations">
    Display and customize the conversations list that updates when messages are sent
  </Card>
</CardGroup>


# Notification Feed
Source: https://www.cometchat.com/docs/ui-kit/android/notification-feed

Full-screen notification feed component with category filtering, card rendering, real-time updates, and engagement reporting.

`CometChatNotificationFeed` displays a scrollable notification feed where each item is rendered as a native card using the CometChat Cards library. It handles fetching, pagination, category filtering, timestamp grouping, real-time updates, and read/delivered/engagement reporting automatically.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatNotificationFeed` is a full-screen component. Drop it into an Activity, Fragment, or navigation destination. It manages its own data fetching, state, and real-time listeners — you just handle navigation callbacks.

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    @Composable
    fun NotificationsScreen(onBack: () -> Unit) {
        CometChatNotificationFeed(
            modifier = Modifier.fillMaxSize(),
            showBackButton = true,
            onBackPress = onBack,
            onItemClick = { item ->
                // Handle item tap (e.g., open detail or deep link)
            }
        )
    }
    ```
  </Tab>

  <Tab title="Kotlin (XML Views)">
    ```xml theme={null}
    <com.cometchat.uikit.kotlin.presentation.notificationfeed.ui.CometChatNotificationFeed
        android:id="@+id/notificationFeed"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    ```kotlin theme={null}
    val feed = findViewById<CometChatNotificationFeed>(R.id.notificationFeed)
    feed.init(this) // Pass Activity or Fragment — needed to create the ViewModel
    feed.onItemClick = { item -> /* navigate */ }
    feed.onBackPress = { finish() }
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    @Composable
    fun NotificationsScreen() {
        CometChatNotificationFeed(
            modifier = Modifier.fillMaxSize()
        )
    }
    ```
  </Tab>

  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val feed = CometChatNotificationFeed(this)
        setContentView(feed)
        feed.init(this) // Required — binds the ViewModel to this Activity's lifecycle
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()` and a user logged in.

***

## Filtering Feed Items

Control what loads using custom request builders:

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    CometChatNotificationFeed(
        feedRequestBuilder = NotificationFeedRequest.NotificationFeedRequestBuilder()
            .setLimit(30)
            .setReadState(FeedReadState.UNREAD)
            .setCategory("promotions")
    )
    ```
  </Tab>

  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    feed.setFeedRequestBuilder(
        NotificationFeedRequest.NotificationFeedRequestBuilder()
            .setLimit(30)
            .setReadState(FeedReadState.UNREAD)
            .setCategory("promotions")
    )
    feed.init(this)
    ```
  </Tab>
</Tabs>

### Filter Options

| Builder Method                 | Description                          |
| ------------------------------ | ------------------------------------ |
| `.setLimit(int)`               | Items per page (default 20, max 100) |
| `.setReadState(FeedReadState)` | `READ`, `UNREAD`, or `ALL`           |
| `.setCategory(String)`         | Filter by category ID                |
| `.setChannelId(String)`        | Filter by channel                    |
| `.setTags(List<String>)`       | Filter by tags                       |
| `.setDateFrom(String)`         | ISO 8601 date lower bound            |
| `.setDateTo(String)`           | ISO 8601 date upper bound            |

<Warning>
  Pass the builder object, not the result of `.build()`. The component calls `.build()` internally.
</Warning>

***

## Actions and Events

### Callback Methods

#### `onItemClick`

Fires when a feed item card is tapped.

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    CometChatNotificationFeed(
        onItemClick = { item ->
            // item.id, item.content (Card JSON), item.category
        }
    )
    ```
  </Tab>

  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    feed.onItemClick = { item ->
        // Handle item tap
    }
    ```
  </Tab>
</Tabs>

#### `onActionClick`

Fires when an interactive element (button, link) inside a card is tapped.

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    CometChatNotificationFeed(
        onActionClick = { item, actionMap ->
            // actionMap contains action type and parameters
            val actionType = actionMap["type"] as? String
            when (actionType) {
                "openUrl" -> openBrowser(actionMap["url"] as String)
                "chatWithUser" -> navigateToChat(actionMap["uid"] as String)
            }
        }
    )
    ```
  </Tab>

  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    feed.onActionClick = { item, actionMap ->
        val actionType = actionMap["type"] as? String
        // Handle action
    }
    ```
  </Tab>
</Tabs>

#### `onError`

Fires when an internal error occurs (network failure, SDK exception).

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    CometChatNotificationFeed(
        onError = { exception ->
            Log.e("Feed", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>

  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    feed.onError = { exception ->
        Log.e("Feed", "Error: ${exception.message}")
    }
    ```
  </Tab>
</Tabs>

#### `onBackPress`

Fires when the back button in the header is tapped.

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    CometChatNotificationFeed(
        showBackButton = true,
        onBackPress = { /* navigate back */ }
    )
    ```
  </Tab>

  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    feed.setShowBackButton(true)
    feed.onBackPress = { finish() }
    ```
  </Tab>
</Tabs>

### Automatic Behaviors

The component handles these automatically — no manual setup needed:

| Behavior             | Description                                             |
| -------------------- | ------------------------------------------------------- |
| Real-time updates    | New items appear at the top via WebSocket listener      |
| Delivery reporting   | Items are reported as delivered when fetched            |
| Read reporting       | Items are reported as read after 1 second of visibility |
| Unread count polling | Polls unread count every 30 seconds to update badges    |
| Infinite scroll      | Fetches next page when scrolling near the bottom        |
| Pull-to-refresh      | Resets and fetches fresh data on pull                   |
| Timestamp grouping   | Groups items as "Today", "Yesterday", day name, or date |
| Category filtering   | Filter chips row for category-based filtering           |

***

## Functionality

| Method (XML Views)                 | Compose Parameter                | Description                  |
| ---------------------------------- | -------------------------------- | ---------------------------- |
| `setTitle("Notifications")`        | `title = "Notifications"`        | Header title text            |
| `setShowHeader(true)`              | `showHeader = true`              | Toggle header visibility     |
| `setShowBackButton(false)`         | `showBackButton = false`         | Toggle back button           |
| `setShowFilterChips(true)`         | `showFilterChips = true`         | Toggle category filter chips |
| `setFeedRequestBuilder(...)`       | `feedRequestBuilder = ...`       | Custom feed request          |
| `setCategoriesRequestBuilder(...)` | `categoriesRequestBuilder = ...` | Custom categories request    |

***

## Custom View Slots

### Header View

Replace the entire header:

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    CometChatNotificationFeed(
        headerView = {
            Row(
                modifier = Modifier.fillMaxWidth().padding(16.dp),
                verticalAlignment = Alignment.CenterVertically
            ) {
                Text("My Notifications", style = CometChatTheme.typography.heading1Bold)
            }
        }
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    CometChatNotificationFeed(
        emptyStateView = {
            Column(
                modifier = Modifier.fillMaxSize(),
                horizontalAlignment = Alignment.CenterHorizontally,
                verticalArrangement = Arrangement.Center
            ) {
                Text("No notifications yet")
            }
        },
        errorStateView = { exception, onRetry ->
            Column(horizontalAlignment = Alignment.CenterHorizontally) {
                Text("Something went wrong")
                Button(onClick = onRetry) { Text("Retry") }
            }
        },
        loadingStateView = {
            Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                CircularProgressIndicator()
            }
        }
    )
    ```
  </Tab>
</Tabs>

***

## Style

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    CometChatNotificationFeed(
        style = CometChatNotificationFeedStyle(
            backgroundColor = Color(0xFFF5F5F5),
            headerBackgroundColor = Color.White,
            headerTitleColor = Color(0xFF141414),
            chipActiveBackgroundColor = Color(0xFF3399FF),
            chipActiveTextColor = Color.White,
            chipInactiveBackgroundColor = Color.White,
            chipInactiveTextColor = Color(0xFF727272),
            cardBackgroundColor = Color.White,
            cardBorderColor = Color(0xFFE0E0E0),
            cardBorderRadius = 12.dp,
            unreadIndicatorColor = Color(0xFF3399FF)
        )
    )
    ```
  </Tab>

  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    feed.setStyle(CometChatNotificationFeedStyle(
        backgroundColor = Color.parseColor("#F5F5F5"),
        headerTitleColor = Color.parseColor("#141414"),
        chipActiveBackgroundColor = Color.parseColor("#3399FF"),
        chipActiveTextColor = Color.WHITE,
        chipInactiveBackgroundColor = Color.TRANSPARENT,
        chipInactiveTextColor = Color.DKGRAY,
        cardBackgroundColor = Color.WHITE,
        cardBorderColor = Color.parseColor("#E0E0E0"),
        unreadIndicatorColor = Color.parseColor("#3399FF")
    ))
    ```
  </Tab>
</Tabs>

### Style Properties

| Property                       | Description                       |
| ------------------------------ | --------------------------------- |
| `backgroundColor`              | Screen background color           |
| `headerBackgroundColor`        | Header bar background             |
| `headerTitleColor`             | Header title text color           |
| `headerBorderColor`            | Divider below header              |
| `chipActiveBackgroundColor`    | Selected filter chip background   |
| `chipActiveTextColor`          | Selected filter chip text         |
| `chipInactiveBackgroundColor`  | Unselected filter chip background |
| `chipInactiveTextColor`        | Unselected filter chip text       |
| `chipBorderColor`              | Filter chip border                |
| `badgeActiveBackgroundColor`   | Active chip badge background      |
| `badgeActiveTextColor`         | Active chip badge text            |
| `badgeInactiveBackgroundColor` | Inactive chip badge background    |
| `badgeInactiveTextColor`       | Inactive chip badge text          |
| `timestampTextColor`           | Section header timestamp color    |
| `cardBackgroundColor`          | Card container background         |
| `cardBorderColor`              | Card container border             |
| `cardBorderRadius`             | Card corner radius                |
| `cardBorderWidth`              | Card border width                 |
| `unreadIndicatorColor`         | Unread dot indicator color        |
| `separatorColor`               | Separator between cards           |

All colors default to `Color.Unspecified` (Compose) or `0` (XML) to inherit from `CometChatTheme`. Override individual values without losing theme support.

***

## ViewModel Access

The component uses `CometChatNotificationFeedViewModel` from the shared `chatuikit-core` module. You can provide a custom ViewModel for advanced scenarios:

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    val viewModel: CometChatNotificationFeedViewModel = viewModel(
        factory = CometChatNotificationFeedViewModelFactory(
            feedRequestBuilder = customBuilder,
            pollingIntervalMs = 60_000L // 1 minute polling
        )
    )

    CometChatNotificationFeed(
        viewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

### ViewModel Factory Parameters

| Parameter                  | Default | Description                                    |
| -------------------------- | ------- | ---------------------------------------------- |
| `feedRequestBuilder`       | null    | Custom feed request builder                    |
| `categoriesRequestBuilder` | null    | Custom categories request builder              |
| `enableListeners`          | true    | Enable WebSocket listeners (false for testing) |
| `pollingIntervalMs`        | 30000   | Unread count polling interval in ms            |

***

## Common Patterns

### Show only unread items

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    CometChatNotificationFeed(
        feedRequestBuilder = NotificationFeedRequest.NotificationFeedRequestBuilder()
            .setReadState(FeedReadState.UNREAD)
    )
    ```
  </Tab>
</Tabs>

### Hide filter chips and header

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    CometChatNotificationFeed(
        showHeader = false,
        showFilterChips = false
    )
    ```
  </Tab>

  <Tab title="Kotlin (XML Views)">
    ```kotlin theme={null}
    feed.setShowHeader(false)
    feed.setShowFilterChips(false)
    ```
  </Tab>
</Tabs>

### Custom categories request

<Tabs>
  <Tab title="Jetpack Compose">
    ```kotlin theme={null}
    CometChatNotificationFeed(
        categoriesRequestBuilder = NotificationCategoriesRequest.NotificationCategoriesRequestBuilder()
            .setLimit(10)
    )
    ```
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup>
  <Card title="Campaigns Feature" icon="bullhorn" href="/ui-kit/android/campaigns">
    Overview of how campaigns work end-to-end
  </Card>

  <Card title="SDK Campaigns API" icon="code" href="/sdk/android/v5/campaigns">
    Low-level SDK APIs for feed items, categories, and engagement
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/android/component-styling">
    Full styling reference for all components
  </Card>

  <Card title="ViewModel & Data" icon="database" href="/ui-kit/android/customization-viewmodel-data">
    Custom ViewModels, repositories, and ListOperations
  </Card>
</CardGroup>


# Building A One-to-One / Group Chat
Source: https://www.cometchat.com/docs/ui-kit/android/one-to-one-chat

Launch a direct one-on-one or group chat screen without a conversation list for focused messaging.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                                                                           |
  | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Components   | `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`                                                                                    |
  | Layout       | Single chat window — no conversation list                                                                                                                       |
  | Prerequisite | Complete [Kotlin Integration](/docs/ui-kit/android/getting-started-kotlin) or [Jetpack Compose Integration](/docs/ui-kit/android/getting-started-jetpack) Steps 1–3 first |
  | Pattern      | Support chat, embedded widgets, focused messaging                                                                                                               |
</Accordion>

This guide builds a single chat window — no sidebar, no conversation list. Users go directly into a one-to-one or group chat. Good for support chat, dating apps, or notification-driven flows.

This assumes you've already completed the integration guide for your chosen UI toolkit (project created, dependencies installed, init + login working).

***

## What You're Building

<Frame>
  <img />
</Frame>

Three components stacked vertically:

1. **Message header** — displays user/group name, avatar, and status
2. **Message list** — real-time chat history with scrolling
3. **Message composer** — text input with media and attachments

***

## Step 1: Set Up the Message Screen

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Create an Activity — `MessageActivity` to display the full-screen chat interface.

    **Layout** — `activity_message.xml`:

    ```xml activity_message.xml lines theme={null}
    <LinearLayout
        xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:orientation="vertical">

        <com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader
            android:id="@+id/message_header"
            android:layout_width="match_parent"
            android:layout_height="wrap_content" />

        <com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
            android:id="@+id/message_list"
            android:layout_width="match_parent"
            android:layout_height="0dp"
            android:layout_weight="1" />

        <com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
            android:id="@+id/message_composer"
            android:layout_width="match_parent"
            android:layout_height="wrap_content" />

    </LinearLayout>
    ```

    **Activity** — `MessageActivity.kt`:

    ```kotlin MessageActivity.kt lines theme={null}
    import android.os.Bundle
    import android.widget.Toast
    import androidx.activity.enableEdgeToEdge
    import androidx.appcompat.app.AppCompatActivity
    import com.cometchat.chat.models.Group
    import com.cometchat.chat.models.User
    import com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
    import com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader
    import com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList

    class MessageActivity : AppCompatActivity() {

        private lateinit var messageHeader: CometChatMessageHeader
        private lateinit var messageList: CometChatMessageList
        private lateinit var messageComposer: CometChatMessageComposer

        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            enableEdgeToEdge()
            setContentView(R.layout.activity_message)

            messageHeader = findViewById(R.id.message_header)
            messageList = findViewById(R.id.message_list)
            messageComposer = findViewById(R.id.message_composer)

            val user = intent.getSerializableExtra("user") as? User
            val group = intent.getSerializableExtra("group") as? Group

            when {
                user != null -> {
                    messageHeader.setUser(user)
                    messageList.setUser(user)
                    messageComposer.setUser(user)
                }
                group != null -> {
                    messageHeader.setGroup(group)
                    messageList.setGroup(group)
                    messageComposer.setGroup(group)
                }
                else -> {
                    Toast.makeText(this, "Missing user or group data", Toast.LENGTH_SHORT).show()
                    finish()
                }
            }

            messageHeader.setOnBackPress { finish() }
        }
    }
    ```

    <Warning>
      You must use an activity that supports the **lifecycle** API (`AppCompatActivity`, `ComponentActivity`, or `FragmentActivity`) to properly manage the UI Kit's lifecycle events.
    </Warning>
  </Tab>

  <Tab title="Jetpack Compose">
    Create a `MessageScreen` composable with header, list, and composer stacked vertically:

    ```kotlin MessageScreen.kt lines theme={null}
    import androidx.compose.foundation.layout.Column
    import androidx.compose.foundation.layout.WindowInsets
    import androidx.compose.foundation.layout.consumeWindowInsets
    import androidx.compose.foundation.layout.fillMaxSize
    import androidx.compose.foundation.layout.fillMaxWidth
    import androidx.compose.foundation.layout.imePadding
    import androidx.compose.foundation.layout.navigationBarsPadding
    import androidx.compose.foundation.layout.padding
    import androidx.compose.foundation.layout.statusBars
    import androidx.compose.material3.Scaffold
    import androidx.compose.runtime.Composable
    import androidx.compose.ui.Modifier
    import com.cometchat.chat.models.Group
    import com.cometchat.chat.models.User
    import com.cometchat.uikit.compose.presentation.messagecomposer.ui.CometChatMessageComposer
    import com.cometchat.uikit.compose.presentation.messageheader.ui.CometChatMessageHeader
    import com.cometchat.uikit.compose.presentation.messagelist.ui.CometChatMessageList

    @Composable
    fun MessageScreen(
        user: User? = null,
        group: Group? = null,
        onBack: () -> Unit
    ) {
        Scaffold(
            contentWindowInsets = WindowInsets.statusBars
        ) { paddingValues ->
            Column(
                modifier = Modifier
                    .fillMaxSize()
                    .padding(paddingValues)
                    .consumeWindowInsets(paddingValues)
                    .navigationBarsPadding()
                    .imePadding()
            ) {
                CometChatMessageHeader(
                    modifier = Modifier.fillMaxWidth(),
                    user = user,
                    group = group,
                    hideBackButton = false,
                    onBackPress = onBack
                )

                CometChatMessageList(
                    modifier = Modifier
                        .fillMaxWidth()
                        .weight(1f),
                    user = user,
                    group = group
                )

                CometChatMessageComposer(
                    modifier = Modifier.fillMaxWidth(),
                    user = user,
                    group = group
                )
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Step 2: Launch a One-to-One Chat

To open a direct chat with a specific user, pass the `User` object when launching the screen.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // From any Activity — pass the User object via Intent
    val intent = Intent(this, MessageActivity::class.java)
    intent.putExtra("user", user) // User is Serializable
    startActivity(intent)
    ```

    Full example after login:

    ```kotlin MainActivity.kt lines theme={null}
    private fun loginUser() {
        CometChatUIKit.login("cometchat-uid-1", object : CometChat.CallbackListener<User>() {
            override fun onSuccess(user: User) {
                Log.d(TAG, "Login successful: ${user.uid}")

                // Fetch the target user, then launch the chat
                CometChat.getUser("cometchat-uid-2", object : CometChat.CallbackListener<User>() {
                    override fun onSuccess(targetUser: User) {
                        val intent = Intent(this@MainActivity, MessageActivity::class.java)
                        intent.putExtra("user", targetUser)
                        startActivity(intent)
                    }

                    override fun onError(e: CometChatException?) {
                        Log.e(TAG, "Error fetching user: ${e?.message}")
                    }
                })
            }

            override fun onError(e: CometChatException) {
                Log.e(TAG, "Login failed: ${e.message}")
            }
        })
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // Pass the User object directly to the composable
    MessageScreen(
        user = targetUser,
        onBack = { /* navigate back */ }
    )
    ```

    Full example after login:

    ```kotlin MainActivity.kt lines theme={null}
    setContent {
        when {
            error != null -> {
                Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                    Text(error ?: "Unknown error")
                }
            }
            !isReady -> {
                Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                    CircularProgressIndicator()
                }
            }
            else -> {
                // targetUser is fetched after login
                MessageScreen(
                    user = targetUser,
                    onBack = { finish() }
                )
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Step 3: Launch a Group Chat

To open a group chat, pass the `Group` object instead.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // From any Activity — pass the Group object via Intent
    val intent = Intent(this, MessageActivity::class.java)
    intent.putExtra("group", group) // Group is Serializable
    startActivity(intent)
    ```

    Full example after login:

    ```kotlin MainActivity.kt lines theme={null}
    private fun loginUser() {
        CometChatUIKit.login("cometchat-uid-1", object : CometChat.CallbackListener<User>() {
            override fun onSuccess(user: User) {
                Log.d(TAG, "Login successful: ${user.uid}")

                // Fetch the target group, then launch the chat
                CometChat.getGroup("cometchat-guid-1", object : CometChat.CallbackListener<Group>() {
                    override fun onSuccess(group: Group) {
                        val intent = Intent(this@MainActivity, MessageActivity::class.java)
                        intent.putExtra("group", group)
                        startActivity(intent)
                    }

                    override fun onError(e: CometChatException?) {
                        Log.e(TAG, "Error fetching group: ${e?.message}")
                    }
                })
            }

            override fun onError(e: CometChatException) {
                Log.e(TAG, "Login failed: ${e.message}")
            }
        })
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    // Pass the Group object directly to the composable
    MessageScreen(
        group = targetGroup,
        onBack = { /* navigate back */ }
    )
    ```

    Full example after login:

    ```kotlin MainActivity.kt lines theme={null}
    setContent {
        when {
            error != null -> {
                Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                    Text(error ?: "Unknown error")
                }
            }
            !isReady -> {
                Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                    CircularProgressIndicator()
                }
            }
            else -> {
                // targetGroup is fetched after login
                MessageScreen(
                    group = targetGroup,
                    onBack = { finish() }
                )
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Step 4: Register Activity & Permissions

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add the activity to your `AndroidManifest.xml`:

    ```xml AndroidManifest.xml lines theme={null}
    <application ...>
        <activity android:name=".MessageActivity" />
    </application>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    No additional activities needed — everything runs inside your existing `MainActivity`.
  </Tab>
</Tabs>

Ensure you've added the required permissions in your `AndroidManifest.xml`:

```xml AndroidManifest.xml lines theme={null}
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/android/components-overview">
    Explore all available UI Kit components and their customization options
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/android/theme-introduction">
    Customize colors, fonts, and styles to match your brand
  </Card>

  <Card title="Integration" icon="rocket" href="/ui-kit/android/getting-started">
    Back to the main integration guide
  </Card>

  <Card title="Feature Guides" icon="book" href="/ui-kit/android/guide-overview">
    Add capabilities like threaded messages, blocking, and group management
  </Card>
</CardGroup>


# Outgoing Call
Source: https://www.cometchat.com/docs/ui-kit/android/outgoing-call

Full-screen outgoing call UI with recipient avatar, name, call status, and end-call button.

`CometChatOutgoingCall` renders the outgoing call screen and transitions to the ongoing call screen when the receiver accepts. It displays the recipient's avatar, name, call status, and an end-call button.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatOutgoingCall` is a call-initiation component. Wire it to `CometChatCallEvents` to handle call-accepted and call-rejected transitions.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_call.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.outgoingcall.CometChatOutgoingCall
        android:id="@+id/outgoing_call"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    ```kotlin lines theme={null}
    val outgoingCall = findViewById<CometChatOutgoingCall>(R.id.outgoing_call)
    outgoingCall.setCall(call)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatOutgoingCall(
        call = call
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add to your layout XML:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.outgoingcall.CometChatOutgoingCall
        android:id="@+id/outgoing_call"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    Set the `Call` object — this is required:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_call)

        val outgoingCall = findViewById<CometChatOutgoingCall>(R.id.outgoing_call)
        outgoingCall.setCall(call)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    @Composable
    fun OutgoingCallScreen() {
        CometChatOutgoingCall(
            call = call
        )
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

***

## Actions and Events

### Callback Methods

#### `onEndCallClick`

Fires when the end-call button is tapped. Default: cancels the outgoing call via the SDK.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    outgoingCall.setOnEndCallClick {
        // Custom end-call logic
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatOutgoingCall(
        call = call,
        onEndCallClick = { /* custom end-call logic */ }
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    outgoingCall.setOnError { context, exception ->
        Log.e("OutgoingCall", "Error: ${exception.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatOutgoingCall(
        call = call,
        onError = { context, exception ->
            Log.e("OutgoingCall", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

### Global UI Events (CometChatCallEvents)

| Event            | Fires when                         | Payload |
| ---------------- | ---------------------------------- | ------- |
| `ccCallAccepted` | Outgoing call accepted by receiver | `Call`  |
| `ccCallRejected` | Outgoing call rejected by receiver | `Call`  |

### SDK Events (Real-Time, Automatic)

| SDK Listener             | Internal behavior                                   |
| ------------------------ | --------------------------------------------------- |
| `onOutgoingCallAccepted` | Transitions to the ongoing call screen              |
| `onOutgoingCallRejected` | Finishes the activity or invokes back-press handler |

***

## Functionality

| Method (Kotlin XML)                  | Compose Parameter                  | Description                       |
| ------------------------------------ | ---------------------------------- | --------------------------------- |
| `setCall(call)`                      | `call = call`                      | Set the Call object (required)    |
| `setOnEndCallClick { }`              | `onEndCallClick = { }`             | Override end-call button behavior |
| `setOnError { }`                     | `onError = { }`                    | Error callback                    |
| `setDisableSoundForCalls(true)`      | `disableSoundForCalls = true`      | Disable outgoing call ringtone    |
| `setCustomSoundForCalls(R.raw.tone)` | `customSoundForCalls = R.raw.tone` | Custom ringtone                   |

***

## Custom View Slots

### Title View

Replace the name / title text area.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    outgoingCall.setTitleView { context, call ->
        val titleView = LayoutInflater.from(context).inflate(R.layout.custom_title_view, null)
        val tvTitle = titleView.findViewById<TextView>(R.id.title_text)
        val user = call?.callReceiver as User
        tvTitle.text = user.name + " <> " + call.sender.uid
        titleView
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatOutgoingCall(
        call = call,
        titleView = { c ->
            val receiver = c.callReceiver as? User
            Text(
                text = "${receiver?.name} <> ${c.sender.uid}",
                style = CometChatTheme.typography.caption1Regular
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Avatar View

Replace the avatar / profile picture area.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    outgoingCall.setAvatarView { context, call ->
        val avatarView = LayoutInflater.from(context).inflate(R.layout.custom_avatar_view, null)
        val avatar = avatarView.findViewById<CometChatAvatar>(R.id.avatar)
        val user = call?.receiver as User
        avatar.setAvatar(user.uid, user.avatar)
        avatarView
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatOutgoingCall(
        call = call,
        avatarView = { c ->
            val receiver = c.callReceiver as? User
            CometChatAvatar(
                imageUrl = receiver?.avatar,
                name = receiver?.name,
                modifier = Modifier.size(100.dp)
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Cancel Button View

Replace the end-call button.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    outgoingCall.setEndCallView { context, call ->
        val endCallView = LayoutInflater.from(context).inflate(R.layout.end_call_button, null)
        endCallView.setOnClickListener {
            Toast.makeText(context, "End call clicked", Toast.LENGTH_SHORT).show()
        }
        val layoutParams = LinearLayout.LayoutParams(
            ViewGroup.LayoutParams.MATCH_PARENT,
            ViewGroup.LayoutParams.WRAP_CONTENT
        )
        layoutParams.bottomMargin = Utils.convertDpToPx(context, 40)
        endCallView.layoutParams = layoutParams
        endCallView
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatOutgoingCall(
        call = call,
        cancelButtonView = { c ->
            Button(
                onClick = { /* end call */ },
                colors = ButtonDefaults.buttonColors(containerColor = Color.Red),
                modifier = Modifier
                    .fillMaxWidth()
                    .padding(horizontal = 16.dp, vertical = 40.dp)
            ) {
                Icon(painterResource(R.drawable.cometchat_ic_end_call), "End Call")
                Spacer(Modifier.width(16.dp))
                Text("End Call")
            }
        }
    )
    ```
  </Tab>
</Tabs>

***

## Style

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Define a custom style in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="CustomOutgoingCallStyle" parent="CometChatOutgoingCallStyle">
        <item name="cometchatOutgoingCallBackgroundColor">#FEEDE1</item>
        <item name="cometchatOutgoingCallTitleTextColor">#F76808</item>
        <item name="cometchatOutgoingCallSubtitleTextColor">#F76808</item>
    </style>
    ```

    ```kotlin lines theme={null}
    outgoingCall.setStyle(R.style.CustomOutgoingCallStyle)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatOutgoingCall(
        call = call,
        style = CometChatOutgoingCallStyle.default().copy(
            backgroundColor = Color(0xFFFEEDE1),
            titleTextColor = Color(0xFFF76808),
            subtitleTextColor = Color(0xFFF76808)
        )
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

See [Component Styling](/docs/ui-kit/android/component-styling) for the full reference.

***

## Next Steps

<CardGroup>
  <Card title="Incoming Call" icon="phone-arrow-down-left" href="/ui-kit/android/incoming-call">
    Incoming call notification with accept/reject
  </Card>

  <Card title="Call Buttons" icon="phone" href="/ui-kit/android/call-buttons">
    Voice and video call buttons
  </Card>

  <Card title="Call Logs" icon="clock-rotate-left" href="/ui-kit/android/call-logs">
    View call history
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/android/conversations">
    Browse recent conversations
  </Card>
</CardGroup>


# Android UI Kit
Source: https://www.cometchat.com/docs/ui-kit/android/overview

Prebuilt, customizable UI components for chat & messaging, voice & video calling — for both Jetpack Compose and Kotlin XML Views.

<Accordion title="AI Integration Quick Reference">
  | Field              | Value                                                             |
  | ------------------ | ----------------------------------------------------------------- |
  | Kotlin (XML Views) | `com.cometchat:chatuikit-kotlin-android` v6.x                     |
  | Jetpack Compose    | `com.cometchat:chatuikit-compose-android` v6.x                    |
  | Shared core        | `chatuikit-core` (ViewModels, repositories, data sources, events) |
  | Peer deps          | `com.cometchat:chat-sdk-android` >=4.x, `minSdk` 28               |
  | Calling            | Optional — `com.cometchat:calls-sdk-android`                      |
  | Source             | [GitHub](https://github.com/cometchat/cometchat-uikit-android)    |
</Accordion>

The CometChat Android UI Kit provides prebuilt, customizable UI components for adding chat, voice, and video calling to any Android app. Every component handles its own data fetching, real-time listeners, and state — so you drop it in and it works.

It ships in two flavors that share the same core (ViewModels, repositories, events), so you get identical behavior whichever you choose:

* **Jetpack Compose** — native Material 3 composables for modern, Compose-first apps.
* **Kotlin (XML Views)** — drop-in Views for existing XML layout–based apps.

<Frame>
  <img />
</Frame>

***

## Get Started

Every integration starts the same way — install the SDK, initialize, and log in — then you build the UI with your chosen toolkit. Start with the prerequisites, then pick a path:

<Card title="Prerequisites & Setup" icon="key" href="/ui-kit/android/getting-started">
  App credentials, Gradle install, `init()`, and `login()` — shared by both toolkits
</Card>

<CardGroup>
  <Card title="Jetpack Compose" icon="layer-group" href="/ui-kit/android/getting-started-jetpack">
    Build your chat UI with native Material 3 composables
  </Card>

  <Card title="Kotlin (XML Views)" icon="file-code" href="/ui-kit/android/getting-started-kotlin">
    Build your chat UI with drop-in XML Views
  </Card>
</CardGroup>

***

## Try It

See the UI Kit in action before you write any code:

<CardGroup>
  <Card title="Google Play Demo" icon="play" href="https://link.cometchat.com/android-demo-app">
    Try the full chat experience on your device
  </Card>

  <Card title="Sample App" icon="code" href="https://github.com/cometchat/cometchat-uikit-android">
    Clone, add your credentials, and start building
  </Card>
</CardGroup>

Download the CometChat demo app from Google Play:

[<img />](https://link.cometchat.com/android-demo-app)

Or scan the QR code to install directly:

<Frame>
  <img />
</Frame>

***

## Explore

<CardGroup>
  <Card title="Components" icon="grid-2" href="/ui-kit/android/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Features" icon="comments" href="/ui-kit/android/core-features">
    Chat, calling, AI, and extensions
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/android/theme-introduction">
    Colors, fonts, dark mode, and custom styling
  </Card>

  <Card title="Guides" icon="book" href="/ui-kit/android/guide-overview">
    Threaded messages, new chat, search, and more
  </Card>

  <Card title="Key Concepts" icon="lightbulb" href="/fundamentals/key-concepts">
    Essential terminology and platform features
  </Card>

  <Card title="Architecture" icon="sitemap" href="/ui-kit/android/architecture-data-flow">
    How components, ViewModels, and data flow fit together
  </Card>
</CardGroup>

***

## Resources

<CardGroup>
  <Card title="Sample App" icon="github" href="https://github.com/cometchat/cometchat-uikit-android">
    Working reference app
  </Card>

  <Card title="Figma" icon="figma" href="https://www.figma.com/community/file/1444324233177163609/cometchat-ui-kit-for-android">
    Design resources and prototyping
  </Card>

  <Card title="Migration Guide" icon="arrow-up" href="/ui-kit/android/upgrading-from-v5">
    Upgrading from v5
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/android/troubleshooting">
    Common issues and fixes
  </Card>

  <Card title="Support" icon="headset" href="https://help.cometchat.com/hc/en-us/requests/new">
    Open a support ticket
  </Card>
</CardGroup>


# Search
Source: https://www.cometchat.com/docs/ui-kit/android/search

Real-time search interface for finding conversations and messages with filters, scopes, and customization options.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatSearch",
    "package": "com.cometchat.uikit.kotlin.presentation.search (XML Views) / com.cometchat.uikit.compose.presentation.search (Compose)",
    "xmlElement": "<com.cometchat.uikit.kotlin.presentation.search.ui.CometChatSearch />",
    "description": "Real-time search interface for finding conversations and messages with filters, scopes, and customization options.",
    "primaryOutput": {
      "conversationClicked": {
        "method": "setOnConversationClicked",
        "type": "OnItemClick<Conversation>"
      },
      "messageClicked": {
        "method": "setOnMessageClicked",
        "type": "OnItemClick<BaseMessage>"
      }
    },
    "methods": {
      "data": {
        "setConversationsRequestBuilder": {
          "type": "ConversationsRequest.ConversationsRequestBuilder",
          "default": "SDK default",
          "note": "Pass the builder, not the result of .build()"
        },
        "setMessagesRequestBuilder": {
          "type": "MessagesRequest.MessagesRequestBuilder",
          "default": "SDK default",
          "note": "Pass the builder, not the result of .build()"
        }
      },
      "callbacks": {
        "setOnConversationClicked": "OnItemClick<Conversation>",
        "setOnMessageClicked": "OnItemClick<BaseMessage>",
        "setOnBackPressListener": "OnBackPress",
        "setOnError": "OnError",
        "setOnEmpty": "OnEmpty",
        "setOnLoadMessages": "OnLoad<BaseMessage>",
        "setOnLoadConversations": "OnLoad<Conversation>"
      },
      "visibility": {
        "setEmptyStateVisibility": { "type": "int (View.VISIBLE | View.GONE)", "default": "View.VISIBLE" },
        "setErrorStateVisibility": { "type": "int", "default": "View.VISIBLE" }
      },
      "functionality": {
        "setUid": { "type": "String", "note": "Scope search to a specific user conversation" },
        "setGuid": { "type": "String", "note": "Scope search to a specific group conversation" },
        "setSearchFilters": { "type": "List<UIKitConstants.SearchFilter>", "note": "Filters rendered as chips" },
        "setInitialSearchFilter": { "type": "UIKitConstants.SearchFilter", "note": "Default active filter on load" },
        "setSearchIn": { "type": "List<SearchScope>", "note": "Entities to search in" },
        "setHideGroupType": { "type": "boolean", "default": "false" },
        "setHideUserStatus": { "type": "boolean", "default": "false" }
      },
      "viewSlots": {
        "setConversationItemView": "ConversationsSearchViewHolderListener — entire conversation item row",
        "setTextMessageItemView": "MessagesSearchViewHolderListener<TextMessage> — text message item",
        "setImageMessageItemView": "MessagesSearchViewHolderListener<MediaMessage> — image message item",
        "setAudioMessageItemView": "MessagesSearchViewHolderListener<MediaMessage> — audio message item",
        "setVideoMessageItemView": "MessagesSearchViewHolderListener<MediaMessage> — video message item",
        "setDocumentMessageItemView": "MessagesSearchViewHolderListener<MediaMessage> — document message item",
        "setLinkMessageItemView": "MessagesSearchViewHolderListener<TextMessage> — link message item",
        "setInitialView": "@LayoutRes int — initial state before search",
        "setEmptyView": "@LayoutRes int — empty state",
        "setLoadingView": "View — loading state",
        "setErrorView": "View — error state"
      },
      "advanced": {
        "setTextFormatters": "List<CometChatTextFormatter> — custom text formatters",
        "setDateTimeFormatter": "DateTimeFormatterCallback — custom date/time formatting",
        "setMentionAllLabelId": "String id, String mentionAllLabel — custom mention-all label",
        "setHintText": "String — search bar hint text"
      },
      "style": {
        "setStyle": {
          "type": "@StyleRes int",
          "parent": "CometChatSearchStyle"
        }
      }
    },
    "events": [],
    "sdkListeners": []
  }
  ```
</Accordion>

## Where It Fits

`CometChatSearch` is a composite search component. It searches across conversations and messages in real time and emits the selected result via `setOnConversationClicked` or `setOnMessageClicked`. Wire it to navigation so tapping a conversation opens the message view, or tapping a message scrolls to it in context.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin ChatActivity.kt lines theme={null}
    class ChatActivity : AppCompatActivity() {

        private lateinit var search: CometChatSearch
        private lateinit var messageHeader: CometChatMessageHeader
        private lateinit var messageList: CometChatMessageList
        private lateinit var messageComposer: CometChatMessageComposer

        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.activity_chat)

            search = findViewById(R.id.cometchat_search)
            messageHeader = findViewById(R.id.message_header)
            messageList = findViewById(R.id.message_list)
            messageComposer = findViewById(R.id.message_composer)

            search.setOnConversationClicked { view, position, conversation ->
                val user = conversation.conversationWith as? User
                user?.let {
                    messageHeader.setUser(it)
                    messageList.setUser(it)
                    messageComposer.setUser(it)
                }
            }

            search.setOnMessageClicked { view, position, baseMessage ->
                // Navigate to the message in context
            }
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        onMessageClick = { message ->
            Log.i(TAG, "Message Clicked!")
        }
    )
    ```
  </Tab>
</Tabs>

## Quick Start

Add the component to your layout XML:

```xml activity_search.xml lines theme={null}
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/main"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".ui.activity.SearchActivity">

    <com.cometchat.uikit.kotlin.presentation.search.ui.CometChatSearch
        android:id="@+id/cometchat_search"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:layout_constraintTop_toTopOf="parent"/>

</androidx.constraintlayout.widget.ConstraintLayout>
```

<Frame>
  <img />
</Frame>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the `cometchat-chat-uikit-android` dependency added.

To add programmatically in an Activity:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin SearchActivity.kt lines theme={null}
    class SearchActivity : AppCompatActivity() {
        private lateinit var binding: ActivitySearchBinding

        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            binding = ActivitySearchBinding.inflate(layoutInflater)
            setContentView(binding.root)
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        onMessageClick = { message ->
            Log.i(TAG, "Message Clicked!")
        }
    )
    ```
  </Tab>
</Tabs>

## Actions and Events

### Callback Methods

#### `setOnConversationClicked`

Fires when a user taps a conversation from the search results. Primary navigation hook — set the active conversation and render the message view.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin SearchActivity.kt lines theme={null}
    binding.cometchatSearch.setOnConversationClicked { view, position, conversation ->
        Log.i(TAG, "onCreate: Conversation Clicked !")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        onConversationClick = { conversation ->
            Log.i(TAG, "Conversation Clicked!")
        }
    )
    ```
  </Tab>
</Tabs>

> **What this does:** Replaces the default conversation-click behavior. When a user taps a conversation item, your custom lambda executes. The callback receives the view, position, and `Conversation` object.

#### `setOnMessageClicked`

Fires when a user taps a message from the search results. Use to navigate to the message in context.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin SearchActivity.kt lines theme={null}
    binding.cometchatSearch.setOnMessageClicked { view, position, baseMessage ->
        Log.i(TAG, "onCreate: Message Clicked !")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        onMessageClick = { message ->
            Log.i(TAG, "Message Clicked!")
        }
    )
    ```
  </Tab>
</Tabs>

> **What this does:** Registers a callback that fires when the user taps a message in the search results. The callback receives the view, position, and `BaseMessage` object.

#### `setOnBackPressListener`

Fires when the user presses the back button in the search bar. Default: no predefined behavior.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin SearchActivity.kt lines theme={null}
    binding.cometchatSearch.setOnBackPressListener {
        Log.i(TAG, "onCreate: Back Pressed !")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        onBackPress = {
            Log.i(TAG, "Back Pressed!")
        }
    )
    ```
  </Tab>
</Tabs>

#### `setOnError`

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

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin SearchActivity.kt lines theme={null}
    binding.cometchatSearch.onError = OnError {
        Log.i(TAG, "onCreate: Error Occurred ! ${it.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        onError = { exception ->
            Log.i(TAG, "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `setOnLoadMessages`

Fires when the message list is successfully fetched and loaded, helping track when message search results are ready.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin SearchActivity.kt lines theme={null}
    binding.cometchatSearch.setOnLoadMessages(OnLoad<BaseMessage> { list ->
        Log.i(TAG, "Messages loaded: ${list.size}")
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        onLoadMessages = { messages ->
            Log.i(TAG, "Messages loaded: ${messages.size}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `setOnLoadConversations`

Fires when the conversation list is successfully fetched and loaded, helping track when conversation search results are ready.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin SearchActivity.kt lines theme={null}
    binding.cometchatSearch.setOnLoadConversations(OnLoad<Conversation> { list ->
        Log.i(TAG, "Conversations loaded: ${list.size}")
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        onLoadConversations = { conversations ->
            Log.i(TAG, "Conversations loaded: ${conversations.size}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `setOnEmpty`

Fires when the search returns no results, enabling custom handling such as showing a placeholder.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin SearchActivity.kt lines theme={null}
    binding.cometchatSearch.onEmpty = OnEmpty {
        Log.i(TAG, "onCreate: No Results Found !")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        onEmpty = {
            Log.i(TAG, "No Results Found!")
        }
    )
    ```
  </Tab>
</Tabs>

* **Verify**: After setting an action callback, trigger the corresponding user interaction (tap a conversation result, tap a message result, press back, cause an error, or search for a term with no results) and confirm your custom logic executes.

### Global UI Events

The `CometChatSearch` component does not produce any global UI events.

### SDK Events (Real-Time, Automatic)

The `CometChatSearch` component does not listen to any SDK events internally. Search results are fetched on demand when the user types a query.

## Functionality

Small functional customizations such as toggling visibility of UI elements and configuring search scope.

| Methods                   | Description                                               | Code                                                             |
| ------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------- |
| `setEmptyStateVisibility` | Hides the empty state when search returns no results      | `.setEmptyStateVisibility(View.GONE);`                           |
| `setErrorStateVisibility` | Hides the error state on search failure                   | `.setErrorStateVisibility(View.GONE);`                           |
| `setSearchFilters`        | List of filters rendered as chips in the search component | `.setSearchFilters(filters);`                                    |
| `setInitialSearchFilter`  | The filter which will be active by default on load        | `.setInitialSearchFilter(UIKitConstants.SearchFilter.MESSAGES);` |
| `setSearchIn`             | List of entities in which the search should be performed  | `.setSearchIn(scopes);`                                          |
| `setHideGroupType`        | Hides the group type icon in conversation leading view    | `.setHideGroupType(true);`                                       |
| `setHideUserStatus`       | Hides the user's online/offline status indicator          | `.setHideUserStatus(true);`                                      |

* **Verify**: After calling a visibility or functionality method, confirm the corresponding UI element is shown or hidden, or the search scope is correctly applied.

## Custom View Slots

Each slot replaces a section of the default UI. Conversation item slots use the `ConversationsSearchViewHolderListener` pattern (`createView` + `bindView`). Message item slots use the `MessagesSearchViewHolderListener` pattern.

| Slot                   | Method                                                                       | Replaces                     |
| ---------------------- | ---------------------------------------------------------------------------- | ---------------------------- |
| Conversation item view | `setConversationItemView(ConversationsSearchViewHolderListener)`             | Entire conversation item row |
| Text message item      | `setTextMessageItemView(MessagesSearchViewHolderListener<TextMessage>)`      | Text message item            |
| Image message item     | `setImageMessageItemView(MessagesSearchViewHolderListener<MediaMessage>)`    | Image message item           |
| Audio message item     | `setAudioMessageItemView(MessagesSearchViewHolderListener<MediaMessage>)`    | Audio message item           |
| Video message item     | `setVideoMessageItemView(MessagesSearchViewHolderListener<MediaMessage>)`    | Video message item           |
| Document message item  | `setDocumentMessageItemView(MessagesSearchViewHolderListener<MediaMessage>)` | Document message item        |
| Link message item      | `setLinkMessageItemView(MessagesSearchViewHolderListener<TextMessage>)`      | Link message item            |
| Initial view           | `setInitialView(@LayoutRes int)`                                             | Initial state before search  |
| Empty view             | `setEmptyView(@LayoutRes int)`                                               | Empty state                  |
| Loading view           | `setLoadingView(View)`                                                       | Loading spinner              |
| Error view             | `setErrorView(View)`                                                         | Error state                  |

### `setConversationItemView`

Replace the entire conversation item row in search results.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin SearchActivity.kt lines theme={null}
    binding.cometchatSearch.setConversationItemView(object : ConversationsSearchViewHolderListener() {
        override fun createView(context: Context?, listItem: View?): View? {
            return layoutInflater.inflate(R.layout.custom_conversation_search_item, null)
        }

        override fun bindView(
            context: Context?,
            createdView: View?,
            conversation: Conversation?,
            holder: RecyclerView.ViewHolder?,
            conversationList: List<Conversation?>?,
            position: Int
        ) {
            val titleTv = createdView?.findViewById<android.widget.TextView>(R.id.tv_title)
            conversation?.let {
                if (it.conversationType == CometChatConstants.CONVERSATION_TYPE_USER) {
                    titleTv?.text = (it.conversationWith as User).name
                } else {
                    titleTv?.text = (it.conversationWith as Group).name
                }
            }
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        conversationItemView = { conversation ->
            Row(modifier = Modifier.padding(16.dp)) {
                val name = when (conversation.conversationType) {
                    CometChatConstants.CONVERSATION_TYPE_USER ->
                        (conversation.conversationWith as User).name
                    else ->
                        (conversation.conversationWith as Group).name
                }
                Text(text = name ?: "", style = MaterialTheme.typography.bodyLarge)
            }
        }
    )
    ```
  </Tab>
</Tabs>

> **What this does:** Registers a `ConversationsSearchViewHolderListener` for conversation items in search results. The `createView` method inflates a custom layout, and `bindView` populates it with the conversation name based on whether it's a user or group conversation.

### `setTextMessageItemView`

Replace the text message item view in search results.

Define a custom layout XML:

```xml custom_message_item_view.xml lines theme={null}
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="horizontal"
    android:padding="16dp"
    android:background="#E8E4F3">

    <TextView
        android:id="@+id/tv_sender_name"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="George Alan:"
        android:textColor="#6B4FBB"
        android:textSize="16sp"
        android:textStyle="bold"
        android:layout_marginEnd="4dp" />

    <TextView
        android:id="@+id/tv_message"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:layout_weight="1"
        android:text="That works for me. Yes, let's go a..."
        android:textColor="#4A4A4A"
        android:textSize="16sp"
        android:ellipsize="end"
        android:maxLines="1" />
</LinearLayout>
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin SearchActivity.kt lines theme={null}
    binding.cometchatSearch.setTextMessageItemView(object : MessagesSearchViewHolderListener<TextMessage>() {
        override fun createView(
            context: Context?,
            listItem: View?
        ): View? {
            return layoutInflater.inflate(R.layout.custom_message_item_view, null)
        }

        override fun bindView(
            context: Context?,
            createdView: View?,
            message: TextMessage?,
            holder: RecyclerView.ViewHolder?,
            messagesList: List<BaseMessage?>?,
            position: Int
        ) {
            val titleTv = createdView?.findViewById<android.widget.TextView>(R.id.tv_sender_name)
            val messageTv = createdView?.findViewById<android.widget.TextView>(R.id.tv_message)

            titleTv?.text = message?.sender?.name
            messageTv?.text = message?.text
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        textMessageItemView = { message ->
            Row(
                modifier = Modifier
                    .fillMaxWidth()
                    .background(Color(0xFFE8E4F3))
                    .padding(16.dp)
            ) {
                Text(
                    text = "${message.sender?.name}: ",
                    color = Color(0xFF6B4FBB),
                    fontWeight = FontWeight.Bold
                )
                Text(
                    text = message.text ?: "",
                    color = Color(0xFF4A4A4A),
                    maxLines = 1,
                    overflow = TextOverflow.Ellipsis
                )
            }
        }
    )
    ```
  </Tab>
</Tabs>

> **What this does:** Registers a `MessagesSearchViewHolderListener` for text messages. The `createView` method inflates the custom layout, and `bindView` populates the sender name and message text from the `TextMessage` object.

<Frame>
  <img />
</Frame>

### Other Message Item Views

The following message item view methods follow the same `MessagesSearchViewHolderListener` pattern as `setTextMessageItemView`:

| Method                       | Message Type     | Generic Type                                     |
| ---------------------------- | ---------------- | ------------------------------------------------ |
| `setImageMessageItemView`    | Image Message    | `MessagesSearchViewHolderListener<MediaMessage>` |
| `setVideoMessageItemView`    | Video Message    | `MessagesSearchViewHolderListener<MediaMessage>` |
| `setAudioMessageItemView`    | Audio Message    | `MessagesSearchViewHolderListener<MediaMessage>` |
| `setDocumentMessageItemView` | Document Message | `MessagesSearchViewHolderListener<MediaMessage>` |
| `setLinkMessageItemView`     | Link Message     | `MessagesSearchViewHolderListener<TextMessage>`  |

### `setInitialView`

Sets a custom view displayed when the search component is rendered and no search has been performed.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setInitialView(R.layout.your_initial_view)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        initialView = {
            // Your custom initial composable
            Text("Start searching...")
        }
    )
    ```
  </Tab>
</Tabs>

### `setEmptyView`

Configures a custom view displayed when the search returns no results.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setEmptyView(R.layout.your_empty_view)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        emptyView = {
            // Your custom empty state composable
            Text("No results found")
        }
    )
    ```
  </Tab>
</Tabs>

### `setLoadingView`

Sets a custom loading view displayed when search results are being fetched.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setLoadingView(loadingView)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        loadingView = {
            // Your custom loading composable
            CircularProgressIndicator()
        }
    )
    ```
  </Tab>
</Tabs>

### `setErrorView`

Defines a custom error state view that appears when an issue occurs while searching.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setErrorView(errorView)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        errorView = { onRetry ->
            // Your custom error composable
            Column {
                Text("Something went wrong")
                Button(onClick = onRetry) { Text("Retry") }
            }
        }
    )
    ```
  </Tab>
</Tabs>

* **Verify**: After setting any custom view slot, confirm the custom view renders in the correct position within the search result items, and the data binding populates correctly for each result.

## Common Patterns

### Messages-only search

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setSearchFilters(
        listOf(UIKitConstants.SearchFilter.MESSAGES)
    )
    binding.cometchatSearch.setInitialSearchFilter(UIKitConstants.SearchFilter.MESSAGES)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.core.constants.SearchFilter

    CometChatSearch(
        searchFilters = listOf(SearchFilter.UNREAD),
        modifier = Modifier.fillMaxSize()
    )
    ```
  </Tab>
</Tabs>

### Filter by message type

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setMessagesRequestBuilder(
        MessagesRequest.MessagesRequestBuilder().setLimit(10)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.core.constants.SearchFilter

    CometChatSearch(
        searchFilters = listOf(SearchFilter.UNREAD),
        modifier = Modifier.fillMaxSize()
    )
    ```
  </Tab>
</Tabs>

### Scope search to a specific user

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setUid("user123")
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        uid = "user123",
        modifier = Modifier.fillMaxSize()
    )
    ```
  </Tab>
</Tabs>

### Scope search to a specific group

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setGuid("group123")
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        guid = "group123",
        modifier = Modifier.fillMaxSize()
    )
    ```
  </Tab>
</Tabs>

## Advanced Methods

### Search Scope

#### `setUid`

Scopes the search to a specific user's conversation.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setUid("user123")
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        uid = "user123",
        modifier = Modifier.fillMaxSize()
    )
    ```
  </Tab>
</Tabs>

#### `setGuid`

Scopes the search to a specific group's conversation.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setGuid("group123")
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        guid = "group123",
        modifier = Modifier.fillMaxSize()
    )
    ```
  </Tab>
</Tabs>

### Request Builders

#### `setConversationsRequestBuilder`

Sets a `ConversationsRequest.ConversationsRequestBuilder` to filter conversation search results. Pass the builder instance — not the result of `.build()`. For all available builder options, refer to the [ConversationRequestBuilder](/docs/sdk/android/retrieve-conversations) documentation.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setConversationsRequestBuilder(
        ConversationsRequest.ConversationsRequestBuilder().setLimit(10)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        guid = "group123",
        modifier = Modifier.fillMaxSize()
    )
    ```
  </Tab>
</Tabs>

#### `setMessagesRequestBuilder`

Sets a `MessagesRequest.MessagesRequestBuilder` to filter message search results. For all available builder options, refer to the [MessagesRequestBuilder](/docs/sdk/android/additional-message-filtering) documentation.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setMessagesRequestBuilder(
        MessagesRequest.MessagesRequestBuilder().setLimit(5)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        guid = "group123",
        modifier = Modifier.fillMaxSize()
    )
    ```
  </Tab>
</Tabs>

### Text Formatters

#### `setTextFormatters`

Enables developers to define and apply text formatters that dynamically modify or transform message content before rendering it in the UI. Text formatters can be used for:

* Automatically converting URLs into clickable links
* Applying Markdown or rich text styling
* Replacing certain words or patterns with emojis or predefined text
* Censoring specific words for moderation

For implementation details, refer to the [MentionsFormatter Guide](/docs/ui-kit/android/mentions-formatter-guide).

### Date/Time Formatting

#### `setDateTimeFormatter`

Provides a custom implementation of `DateTimeFormatterCallback` to configure how time and date values are displayed in search results.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    import java.text.SimpleDateFormat
    import java.util.*

    binding.cometchatSearch.setDateTimeFormatter(object : DateTimeFormatterCallback {

        private val fullTimeFormatter = SimpleDateFormat("hh:mm a", Locale.getDefault())
        private val dateFormatter = SimpleDateFormat("dd MMM yyyy", Locale.getDefault())

        override fun time(timestamp: Long): String {
            return fullTimeFormatter.format(Date(timestamp))
        }

        override fun today(timestamp: Long): String {
            return "Today"
        }

        override fun yesterday(timestamp: Long): String {
            return "Yesterday"
        }

        override fun lastWeek(timestamp: Long): String {
            return "Last Week"
        }

        override fun otherDays(timestamp: Long): String {
            return dateFormatter.format(Date(timestamp))
        }

        override fun minutes(diffInMinutesFromNow: Long, timestamp: Long): String {
            return "$diffInMinutesFromNow mins ago"
        }

        override fun hours(diffInHourFromNow: Long, timestamp: Long): String {
            return "$diffInHourFromNow hrs ago"
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatSearch(
        guid = "group123",
        modifier = Modifier.fillMaxSize()
    )
    ```
  </Tab>
</Tabs>

> **What this does:** Provides a custom date/time formatter that displays "Today", "Yesterday", "Last Week" for recent messages, a "dd MMM yyyy" format for older messages, and relative time strings like "5 mins ago" or "2 hrs ago" for recent activity.

### Other Advanced Methods

| Method                 | Type                                | Description                                                         |
| ---------------------- | ----------------------------------- | ------------------------------------------------------------------- |
| `setMentionAllLabelId` | `String id, String mentionAllLabel` | Sets a custom label for the "mention all" feature for a specific ID |
| `setHintText`          | `String`                            | Sets the hint text displayed in the search bar                      |

## Style

The component uses XML theme styles. Define a custom style with parent `CometChatSearchStyle` in `themes.xml`, then apply with `setStyle()`.

<Frame>
  <img />
</Frame>

```xml themes.xml lines theme={null}
    <style name="CustomSearchStyle" parent="CometChatSearchStyle">
        <item name="cometchatSearchBackgroundColor">#EDEAFA</item>

        <item name="cometchatSearchFilterChipTextAppearance">@style/textStyleTimesNewRoman</item>

        <item name="cometchatSearchSectionHeaderTextAppearance">@style/textStyleTimesNewRoman</item>
        <item name="cometchatSearchSectionHeaderBackgroundColor">#EDEAFA</item>

        <item name="cometchatSearchConversationItemBackgroundColor">#EDEAFA</item>
        <item name="cometchatSearchConversationSubtitleTextAppearance">@style/textStyleTimesNewRoman</item>
        <item name="cometchatSearchConversationTitleTextAppearance">@style/textStyleTimesNewRoman</item>
        <item name="cometchatSearchConversationTimestampTextAppearance">?attr/cometchatTextAppearanceCaption1Bold</item>

        <item name="cometchatSearchSeeMoreTextAppearance">@style/textStyleTimesNewRoman</item>

        <item name="cometchatSearchMessageItemBackgroundColor">#EDEAFA</item>
        <item name="cometchatSearchMessageTitleTextAppearance">@style/textStyleTimesNewRoman</item>
        <item name="cometchatSearchMessageSubtitleTextAppearance">@style/textStyleTimesNewRoman</item>
        <item name="cometchatSearchMessageTimestampTextAppearance">@style/textStyleTimesNewRoman</item>

        <item name="cometchatSearchBarTextAppearance">@style/textStyleTimesNewRoman</item>
    </style>

    <style name="textStyleTimesNewRoman">
        <item name="android:fontFamily">@font/times_new_roman_regular</item>
    </style>
```

> **What this does:** Defines a custom search style that sets a light purple background color (`#EDEAFA`) for the search component, conversation items, and message items, and applies a Times New Roman font to all text elements including filter chips, section headers, conversation titles/subtitles, message titles/subtitles, timestamps, "see more" text, and the search bar.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    binding.cometchatSearch.setStyle(R.style.CustomSearchStyle)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.compose.presentation.search.style.CometChatSearchStyle

    CometChatSearch(
        style = CometChatSearchStyle.default().copy(
            backgroundColor = Color(0xFFEDEAFA),
            searchBarBackgroundColor = Color(0xFFEDEAFA),
            filterChipBackgroundColor = Color(0xFFEDEAFA)
        ),
        modifier = Modifier.fillMaxSize()
    )
    ```
  </Tab>
</Tabs>

To view all available style attributes, visit the [attributes file](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_search.xml).

### Programmatic Style Properties

In addition to XML theme styles, the component exposes programmatic setters for fine-grained control:

**Search Bar**

| Method                        | Type             | Description                             |
| ----------------------------- | ---------------- | --------------------------------------- |
| `setBackgroundColor`          | `@ColorInt int`  | Background color of the component       |
| `setSearchBarBackgroundColor` | `@ColorInt int`  | Background color of the search bar      |
| `setSearchBarStrokeWidth`     | `@Dimension int` | Stroke width of the search bar border   |
| `setSearchBarStrokeColor`     | `@ColorInt int`  | Stroke color of the search bar border   |
| `setSearchBarCornerRadius`    | `@Dimension int` | Corner radius of the search bar         |
| `setSearchBarTextColor`       | `@ColorInt int`  | Text color of the search bar input      |
| `setSearchBarTextAppearance`  | `@StyleRes int`  | Text appearance of the search bar input |
| `setSearchBarHintTextColor`   | `@ColorInt int`  | Hint text color of the search bar       |
| `setBackIcon`                 | `Drawable`       | Custom back icon drawable               |
| `setBackIconTint`             | `@ColorInt int`  | Tint color for the back icon            |
| `setClearIcon`                | `Drawable`       | Custom clear icon drawable              |
| `setClearIconTint`            | `@ColorInt int`  | Tint color for the clear icon           |
| `setSearchIcon`               | `Drawable`       | Custom search icon drawable             |
| `setSearchIconTint`           | `@ColorInt int`  | Tint color for the search icon          |

**Filter Chips**

| Method                                 | Type             | Description                               |
| -------------------------------------- | ---------------- | ----------------------------------------- |
| `setFilterChipBackgroundColor`         | `@ColorInt int`  | Background color of filter chips          |
| `setFilterChipSelectedBackgroundColor` | `@ColorInt int`  | Background color of selected filter chips |
| `setFilterChipTextColor`               | `@ColorInt int`  | Text color of filter chips                |
| `setFilterChipSelectedTextColor`       | `@ColorInt int`  | Text color of selected filter chips       |
| `setFilterChipTextAppearance`          | `@StyleRes int`  | Text appearance of filter chips           |
| `setFilterChipStrokeColor`             | `@ColorInt int`  | Stroke color of filter chips              |
| `setFilterChipSelectedStrokeColor`     | `@ColorInt int`  | Stroke color of selected filter chips     |
| `setFilterChipStrokeWidth`             | `@Dimension int` | Stroke width of filter chips              |
| `setFilterChipCornerRadius`            | `@Dimension int` | Corner radius of filter chips             |

**Section Headers**

| Method                            | Type            | Description                          |
| --------------------------------- | --------------- | ------------------------------------ |
| `setSectionHeaderTextColor`       | `@ColorInt int` | Text color for section headers       |
| `setSectionHeaderTextAppearance`  | `@StyleRes int` | Text appearance for section headers  |
| `setSectionHeaderBackgroundColor` | `@ColorInt int` | Background color for section headers |

**Conversation Items**

| Method                                   | Type            | Description                                 |
| ---------------------------------------- | --------------- | ------------------------------------------- |
| `setConversationItemBackgroundColor`     | `@ColorInt int` | Background color for conversation items     |
| `setConversationTitleTextColor`          | `@ColorInt int` | Text color for conversation titles          |
| `setConversationTitleTextAppearance`     | `@StyleRes int` | Text appearance for conversation titles     |
| `setConversationSubtitleTextColor`       | `@ColorInt int` | Text color for conversation subtitles       |
| `setConversationSubtitleTextAppearance`  | `@StyleRes int` | Text appearance for conversation subtitles  |
| `setConversationTimestampTextColor`      | `@ColorInt int` | Text color for conversation timestamps      |
| `setConversationTimestampTextAppearance` | `@StyleRes int` | Text appearance for conversation timestamps |

**Message Items**

| Method                              | Type            | Description                            |
| ----------------------------------- | --------------- | -------------------------------------- |
| `setMessageItemBackgroundColor`     | `@ColorInt int` | Background color for message items     |
| `setMessageTitleTextColor`          | `@ColorInt int` | Text color for message titles          |
| `setMessageTitleTextAppearance`     | `@StyleRes int` | Text appearance for message titles     |
| `setMessageSubtitleTextColor`       | `@ColorInt int` | Text color for message subtitles       |
| `setMessageSubtitleTextAppearance`  | `@StyleRes int` | Text appearance for message subtitles  |
| `setMessageTimestampTextColor`      | `@ColorInt int` | Text color for message timestamps      |
| `setMessageTimestampTextAppearance` | `@StyleRes int` | Text appearance for message timestamps |
| `setMessageLinkTextColor`           | `@ColorInt int` | Text color for links in messages       |
| `setMessageLinkTextAppearance`      | `@StyleRes int` | Text appearance for links in messages  |

**Other Style Properties**

| Method                                | Type            | Description                                  |
| ------------------------------------- | --------------- | -------------------------------------------- |
| `setAvatarStyle`                      | `@StyleRes int` | Style for avatars in search results          |
| `setBadgeStyle`                       | `@StyleRes int` | Style for badges in search results           |
| `setSeeMoreTextColor`                 | `@ColorInt int` | Text color for "See more" links              |
| `setSeeMoreTextAppearance`            | `@StyleRes int` | Text appearance for "See more" links         |
| `setDateSeparatorTextColor`           | `@ColorInt int` | Text color for date separators               |
| `setDateSeparatorBackgroundColor`     | `@ColorInt int` | Background color for date separators         |
| `setDateSeparatorTextAppearance`      | `@StyleRes int` | Text appearance for date separators          |
| `setEmptyStateTextColor`              | `@ColorInt int` | Title text color for the empty state         |
| `setEmptyStateTextAppearance`         | `@StyleRes int` | Title text appearance for the empty state    |
| `setEmptyStateSubtitleTextColor`      | `@ColorInt int` | Subtitle text color for the empty state      |
| `setEmptyStateSubtitleTextAppearance` | `@StyleRes int` | Subtitle text appearance for the empty state |
| `setEmptyStateIcon`                   | `Drawable`      | Icon for the empty state                     |
| `setEmptyStateIconTint`               | `@ColorInt int` | Tint for the empty state icon                |
| `setErrorStateTextColor`              | `@ColorInt int` | Title text color for the error state         |
| `setErrorStateTextAppearance`         | `@StyleRes int` | Title text appearance for the error state    |
| `setErrorStateSubtitleTextColor`      | `@ColorInt int` | Subtitle text color for the error state      |
| `setErrorStateSubtitleTextAppearance` | `@StyleRes int` | Subtitle text appearance for the error state |
| `setErrorStateIcon`                   | `Drawable`      | Icon for the error state                     |
| `setErrorStateIconTint`               | `@ColorInt int` | Tint for the error state icon                |

## Customization Matrix

| What to change                        | Where             | Property/API                                                     | Example                                                         |
| ------------------------------------- | ----------------- | ---------------------------------------------------------------- | --------------------------------------------------------------- |
| Override behavior on conversation tap | Activity/Fragment | `setOnConversationClicked`                                       | `setOnConversationClicked { v, pos, conv -> ... }`              |
| Override behavior on message tap      | Activity/Fragment | `setOnMessageClicked`                                            | `setOnMessageClicked { v, pos, msg -> ... }`                    |
| Override back press behavior          | Activity/Fragment | `setOnBackPressListener`                                         | `setOnBackPressListener { ... }`                                |
| Scope search to a user                | Activity/Fragment | `setUid(String)`                                                 | `.setUid("user123")`                                            |
| Scope search to a group               | Activity/Fragment | `setGuid(String)`                                                | `.setGuid("group123")`                                          |
| Hide user online status               | Activity/Fragment | `setHideUserStatus(boolean)`                                     | `.setHideUserStatus(true)`                                      |
| Hide group type icon                  | Activity/Fragment | `setHideGroupType(boolean)`                                      | `.setHideGroupType(true)`                                       |
| Set search filters                    | Activity/Fragment | `setSearchFilters(List)`                                         | `.setSearchFilters(filters)`                                    |
| Set initial active filter             | Activity/Fragment | `setInitialSearchFilter(SearchFilter)`                           | `.setInitialSearchFilter(UIKitConstants.SearchFilter.MESSAGES)` |
| Set search scope                      | Activity/Fragment | `setSearchIn(List<SearchScope>)`                                 | `.setSearchIn(scopes)`                                          |
| Filter conversation results           | Activity/Fragment | `setConversationsRequestBuilder`                                 | See Request Builders code above                                 |
| Filter message results                | Activity/Fragment | `setMessagesRequestBuilder`                                      | See Request Builders code above                                 |
| Custom conversation item view         | Activity/Fragment | `setConversationItemView(ConversationsSearchViewHolderListener)` | See `setConversationItemView` code above                        |
| Custom text message item view         | Activity/Fragment | `setTextMessageItemView(MessagesSearchViewHolderListener)`       | See `setTextMessageItemView` code above                         |
| Custom image message item view        | Activity/Fragment | `setImageMessageItemView(MessagesSearchViewHolderListener)`      | See `setTextMessageItemView` pattern                            |
| Custom video message item view        | Activity/Fragment | `setVideoMessageItemView(MessagesSearchViewHolderListener)`      | See `setTextMessageItemView` pattern                            |
| Custom audio message item view        | Activity/Fragment | `setAudioMessageItemView(MessagesSearchViewHolderListener)`      | See `setTextMessageItemView` pattern                            |
| Custom document message item view     | Activity/Fragment | `setDocumentMessageItemView(MessagesSearchViewHolderListener)`   | See `setTextMessageItemView` pattern                            |
| Custom link message item view         | Activity/Fragment | `setLinkMessageItemView(MessagesSearchViewHolderListener)`       | See `setTextMessageItemView` pattern                            |
| Custom initial view                   | Activity/Fragment | `setInitialView(@LayoutRes int)`                                 | `.setInitialView(R.layout.your_initial_view)`                   |
| Custom loading view                   | Activity/Fragment | `setLoadingView(View)`                                           | `.setLoadingView(loadingView)`                                  |
| Custom empty view                     | Activity/Fragment | `setEmptyView(@LayoutRes int)`                                   | `.setEmptyView(R.layout.your_empty_view)`                       |
| Custom error view                     | Activity/Fragment | `setErrorView(View)`                                             | `.setErrorView(errorView)`                                      |
| Empty state visibility                | Activity/Fragment | `setEmptyStateVisibility(int)`                                   | `.setEmptyStateVisibility(View.GONE)`                           |
| Error state visibility                | Activity/Fragment | `setErrorStateVisibility(int)`                                   | `.setErrorStateVisibility(View.GONE)`                           |
| Change colors, fonts, spacing         | `themes.xml`      | `CometChatSearchStyle`                                           | `<item name="cometchatSearchBackgroundColor">#EDEAFA</item>`    |
| Apply a custom style                  | Activity/Fragment | `setStyle(int styleRes)`                                         | `binding.cometchatSearch.setStyle(R.style.CustomSearchStyle)`   |
| Search bar background                 | Activity/Fragment | `setSearchBarBackgroundColor`                                    | `.setSearchBarBackgroundColor(color)`                           |
| Filter chip colors                    | Activity/Fragment | `setFilterChip*` methods                                         | `.setFilterChipBackgroundColor(color)`                          |
| Section header style                  | Activity/Fragment | `setSectionHeader*` methods                                      | `.setSectionHeaderTextColor(color)`                             |
| Conversation item style               | Activity/Fragment | `setConversation*` methods                                       | `.setConversationTitleTextColor(color)`                         |
| Message item style                    | Activity/Fragment | `setMessage*` methods                                            | `.setMessageTitleTextColor(color)`                              |
| Date/time formatting                  | Activity/Fragment | `setDateTimeFormatter(DateTimeFormatterCallback)`                | See `setDateTimeFormatter` code above                           |
| Text formatters                       | Activity/Fragment | `setTextFormatters(List)`                                        | See Text Formatters section                                     |
| Search bar hint text                  | Activity/Fragment | `setHintText(String)`                                            | `.setHintText("Search...")`                                     |
| Mention-all label                     | Activity/Fragment | `setMentionAllLabelId(String, String)`                           | `.setMentionAllLabelId(id, label)`                              |
| Callback on messages loaded           | Activity/Fragment | `setOnLoadMessages(OnLoad<BaseMessage>)`                         | `.setOnLoadMessages { list -> ... }`                            |
| Callback on conversations loaded      | Activity/Fragment | `setOnLoadConversations(OnLoad<Conversation>)`                   | `.setOnLoadConversations { list -> ... }`                       |

## Next Steps

<CardGroup>
  <Card title="Conversations" icon="comments" href="/ui-kit/android/conversations">
    Browse recent conversations
  </Card>

  <Card title="Users" icon="user" href="/ui-kit/android/users">
    Browse and search available users
  </Card>

  <Card title="Groups" icon="users" href="/ui-kit/android/groups">
    Browse and search available groups
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/android/message-list">
    Display messages in a conversation
  </Card>
</CardGroup>


# ShortCut Formatter
Source: https://www.cometchat.com/docs/ui-kit/android/shortcut-formatter-guide

Add shortcut text expansion to the message composer using CometChatTextFormatter and the message-shortcuts extension.

<Accordion title="AI Integration Quick Reference">
  | Field           | Value                                                                                                          |
  | --------------- | -------------------------------------------------------------------------------------------------------------- |
  | Packages        | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack`                                           |
  | Key class       | `ShortCutFormatter` (extends `CometChatTextFormatter`)                                                         |
  | Required setup  | `CometChatUIKit.init()` then `CometChatUIKit.login("UID")`                                                     |
  | Track character | `!` — triggers shortcut expansion in the message composer                                                      |
  | Extension       | `message-shortcuts` CometChat extension must be enabled                                                        |
  | Sample app      | [GitHub](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin)                       |
  | Related         | [Mentions Formatter](/docs/ui-kit/android/mentions-formatter-guide) \| [All Guides](/docs/ui-kit/android/guide-overview) |
</Accordion>

`ShortCutFormatter` extends `CometChatTextFormatter` to expand shortcodes (like `!hi`) into full text via the Message Shortcuts extension. When a user types a shortcut trigger in the composer, a suggestion appears with the expansion — selecting it inserts the text.

<Frame>
  <img />
</Frame>

***

## Steps

### 1. Create the ShortCutFormatter class

Extend `CometChatTextFormatter` with `'!'` as the tracking character:

```kotlin lines theme={null}
class ShortCutFormatter : CometChatTextFormatter('!') {
    private val messageShortcuts: HashMap<String, String> = HashMap()
    private val shortcuts: MutableList<SuggestionItem> = ArrayList()

    init {
        prepareShortCuts()
    }
}
```

### 2. Fetch shortcuts from the extension

```kotlin lines theme={null}
private fun prepareShortCuts() {
    CometChat.callExtension(
        "message-shortcuts", "GET", "/v1/fetch", null,
        object : CometChat.CallbackListener<JSONObject>() {
            override fun onSuccess(responseObject: JSONObject) {
                try {
                    val shortcutObject = responseObject
                        .getJSONObject("data").getJSONObject("shortcuts")
                    val keysItr = shortcutObject.keys()
                    while (keysItr.hasNext()) {
                        val key = keysItr.next()
                        messageShortcuts[key] = shortcutObject.getString(key)
                    }
                } catch (e: JSONException) { e.printStackTrace() }
            }
            override fun onError(e: CometChatException) {}
        })
}
```

### 3. Override the search method

Match user input against stored shortcuts and update the suggestion list:

```kotlin lines theme={null}
override fun search(context: Context, queryString: String?) {
    val query = trackingCharacter.toString() + queryString
    shortcuts.clear()
    if (messageShortcuts.containsKey(query)) {
        val suggestionItem = SuggestionItem(
            "", "$query  =>  ${messageShortcuts[query]}",
            null, null, messageShortcuts[query], null, null
        )
        suggestionItem.isHideLeadingIcon = true
        shortcuts.add(suggestionItem)
    }
    setSuggestionItemList(shortcuts)
}
```

### 4. Override onScrollToBottom

```kotlin theme={null}
override fun onScrollToBottom() {
    // No pagination needed for shortcuts
}
```

### 5. Integrate with MessageComposer

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add the XML element to your layout:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
        android:id="@+id/composer"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    Then add the formatter to the composer:

    ```kotlin lines theme={null}
    import com.cometchat.uikit.core.CometChatUIKit

    val cometChatMessageComposer: CometChatMessageComposer = findViewById(R.id.composer)

    val cometChatTextFormatters = CometChatUIKit.getDataSource().getTextFormatters(this, cometChatMessageComposer.additionParameter)
    cometChatTextFormatters.add(ShortCutFormatter())
    cometChatMessageComposer.setTextFormatters(cometChatTextFormatters)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    import com.cometchat.uikit.core.CometChatUIKit

    // In your composable or ViewModel setup
    val textFormatters = CometChatUIKit.getDataSource().getTextFormatters(context, additionParameter)
    textFormatters.add(ShortCutFormatter())

    CometChatMessageComposer(
        user = user,
        textFormatters = textFormatters
    )
    ```
  </Tab>
</Tabs>

Typing `!` followed by a valid shortcut key (e.g., `!hi`) displays a suggestion with the expanded text. Selecting it inserts the expansion into the composer.

***

## Next Steps

<CardGroup>
  <Card title="Message Composer" icon="keyboard" href="/ui-kit/android/message-composer">
    Configure the composer where ShortCutFormatter is integrated
  </Card>

  <Card title="Mentions Formatter" icon="at" href="/ui-kit/android/mentions-formatter-guide">
    Format @mentions with styled tokens and click handling
  </Card>

  <Card title="All Guides" icon="book" href="/ui-kit/android/guide-overview">
    Browse all feature and formatter guides
  </Card>

  <Card title="Sample App" icon="github" href="https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin">
    Full working sample application on GitHub
  </Card>
</CardGroup>


# Sound Manager
Source: https://www.cometchat.com/docs/ui-kit/android/sound-manager

Play, pause, and customize audio cues for calls and messages using CometChatSoundManager.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                   |
  | ------------ | ------------------------------------------------------------------------------------------------------- |
  | Import       | `com.cometchat.uikit.core.resources.soundmanager.CometChatSoundManager`                                 |
  | Play sound   | `CometChatSoundManager(context).play(Sound.INCOMING_CALL)`                                              |
  | Custom sound | `CometChatSoundManager(context).play(Sound.INCOMING_CALL, R.raw.my_sound)`                              |
  | Pause        | `pause()` (with disconnect tone) or `pauseSilently()` (silent)                                          |
  | Sound events | `INCOMING_CALL`, `OUTGOING_CALL`, `INCOMING_MESSAGE`, `OUTGOING_MESSAGE`, `INCOMING_MESSAGE_FROM_OTHER` |
  | Related      | [Localize](/docs/ui-kit/android/localize)                                                                    |
</Accordion>

`CometChatSoundManager` handles audio playback for calls and messages. It lives in `chatuikit-core` and is shared by both the Kotlin XML Views and Jetpack Compose modules.

***

## Sound Events

| Sound                               | When it plays                                  |
| ----------------------------------- | ---------------------------------------------- |
| `Sound.INCOMING_CALL`               | Incoming call received (with vibration)        |
| `Sound.OUTGOING_CALL`               | Outgoing call initiated                        |
| `Sound.INCOMING_MESSAGE`            | Message received in the active conversation    |
| `Sound.OUTGOING_MESSAGE`            | Message sent                                   |
| `Sound.INCOMING_MESSAGE_FROM_OTHER` | Message received from a different conversation |

***

## Usage

The API is identical for both Kotlin XML Views and Jetpack Compose since `CometChatSoundManager` is a plain Kotlin class from `chatuikit-core`.

```kotlin lines theme={null}
import com.cometchat.uikit.core.resources.soundmanager.CometChatSoundManager
import com.cometchat.uikit.core.resources.soundmanager.Sound

val soundManager = CometChatSoundManager(context)

// Play default sounds
soundManager.play(Sound.INCOMING_CALL)
soundManager.play(Sound.OUTGOING_CALL)
soundManager.play(Sound.INCOMING_MESSAGE)
soundManager.play(Sound.OUTGOING_MESSAGE)
soundManager.play(Sound.INCOMING_MESSAGE_FROM_OTHER)

// Play custom sounds from res/raw
soundManager.play(Sound.INCOMING_CALL, R.raw.my_incoming_call)
soundManager.play(Sound.OUTGOING_MESSAGE, R.raw.my_sent_sound)

// Pause with disconnect tone
soundManager.pause()

// Pause silently (no disconnect tone)
soundManager.pauseSilently()

// Release resources when done
soundManager.release()
```

***

## Disable Sounds on Components

Both UI Kit modules let you disable sounds on individual components.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    val conversations = findViewById<CometChatConversations>(R.id.conversations)
    conversations.setDisableSoundForMessages(true)

    val messageList = findViewById<CometChatMessageList>(R.id.message_list)
    messageList.setDisableSoundForMessages(true)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatConversations(
        disableSoundForMessages = true
    )

    CometChatMessageList(
        disableSoundForMessages = true
    )
    ```
  </Tab>
</Tabs>

***

## API Reference

| Method                             | Description                                                              |
| ---------------------------------- | ------------------------------------------------------------------------ |
| `play(sound: Sound)`               | Plays the default sound for the given event                              |
| `play(sound: Sound, rawFile: Int)` | Plays a custom `res/raw` resource for the event. Pass `0` to use default |
| `pause()`                          | Stops playback and plays a disconnect tone                               |
| `pauseSilently()`                  | Stops playback silently without any tone                                 |
| `release()`                        | Releases all resources. Call when the sound manager is no longer needed  |


# Building A Tab-Based Messaging UI
Source: https://www.cometchat.com/docs/ui-kit/android/tab-based-chat

Create a tab-based messaging UI with bottom navigation for Chats, Calls, Users, and Groups.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                                                                                           |
  | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Components   | `CometChatConversations`, `CometChatCallLogs`, `CometChatUsers`, `CometChatGroups`                                                                              |
  | Layout       | Tabbed bottom navigation (Chats, Calls, Users, Groups)                                                                                                          |
  | Prerequisite | Complete [Kotlin Integration](/docs/ui-kit/android/getting-started-kotlin) or [Jetpack Compose Integration](/docs/ui-kit/android/getting-started-jetpack) Steps 1–3 first |
  | Pattern      | Full-featured messaging app with multiple sections                                                                                                              |
</Accordion>

This guide builds a tabbed messaging UI — Chats, Calls, Users, and Groups tabs via bottom navigation, with each tab loading its CometChat component.

This assumes you've already completed the integration guide for your chosen UI toolkit (project created, dependencies installed, init + login working).

***

## What You're Building

<Frame>
  <img />
</Frame>

Two sections working together:

1. **Bottom navigation bar** — switches between Chats, Calls, Users, and Groups
2. **Content area** — renders the CometChat component for the active tab

<Tabs>
  <Tab title="Kotlin (XML Views)">
    This uses Android's `BottomNavigationView` with Fragments: `TabbedActivity` hosts the navigation and fragment container, user taps a tab, the corresponding Fragment loads.
  </Tab>

  <Tab title="Jetpack Compose">
    This uses Material 3 `NavigationBar` with Compose state: a single composable manages the selected tab and renders the corresponding CometChat component.
  </Tab>
</Tabs>

***

## Step 1: Set Up the Tabbed Screen

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Create a new Activity called `TabbedActivity` with `BottomNavigationView`.

    **Layout** — `activity_tabbed.xml`:

    ```xml activity_tabbed.xml lines theme={null}
    <?xml version="1.0" encoding="utf-8"?>
    <LinearLayout
        xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:app="http://schemas.android.com/apk/res-auto"
        android:id="@+id/main"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:orientation="vertical">

        <FrameLayout
            android:id="@+id/fragmentContainer"
            android:layout_width="match_parent"
            android:layout_height="0dp"
            android:layout_weight="1"/>

        <com.google.android.material.bottomnavigation.BottomNavigationView
            android:id="@+id/bottomNavigationView"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            app:menu="@menu/bottom_nav_menu"/>

    </LinearLayout>
    ```

    **Menu** — `res/menu/bottom_nav_menu.xml`:

    ```xml bottom_nav_menu.xml lines theme={null}
    <?xml version="1.0" encoding="utf-8"?>
    <menu xmlns:android="http://schemas.android.com/apk/res/android">
        <item android:id="@+id/nav_chats" android:icon="@drawable/ic_chats" android:title="Chats"/>
        <item android:id="@+id/nav_call_logs" android:icon="@drawable/ic_calls" android:title="Calls"/>
        <item android:id="@+id/nav_users" android:icon="@drawable/ic_user" android:title="Users"/>
        <item android:id="@+id/nav_groups" android:icon="@drawable/ic_group" android:title="Groups"/>
    </menu>
    ```

    **Activity** — `TabbedActivity.kt`:

    ```kotlin TabbedActivity.kt lines theme={null}
    import android.os.Bundle
    import androidx.activity.enableEdgeToEdge
    import androidx.appcompat.app.AppCompatActivity
    import androidx.core.view.ViewCompat
    import androidx.core.view.WindowInsetsCompat
    import androidx.fragment.app.Fragment
    import com.google.android.material.bottomnavigation.BottomNavigationView

    class TabbedActivity : AppCompatActivity() {

        private lateinit var bottomNav: BottomNavigationView

        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            enableEdgeToEdge()
            setContentView(R.layout.activity_tabbed)

            ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
                val bars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
                v.setPadding(bars.left, bars.top, bars.right, bars.bottom)
                insets
            }

            bottomNav = findViewById(R.id.bottomNavigationView)

            bottomNav.setOnItemSelectedListener { item ->
                replaceFragment(
                    when (item.itemId) {
                        R.id.nav_chats -> ChatsFragment()
                        R.id.nav_call_logs -> CallLogsFragment()
                        R.id.nav_users -> UsersFragment()
                        R.id.nav_groups -> GroupsFragment()
                        else -> ChatsFragment()
                    }
                )
                true
            }

            if (savedInstanceState == null) {
                replaceFragment(ChatsFragment())
            }
        }

        private fun replaceFragment(fragment: Fragment) {
            supportFragmentManager.beginTransaction()
                .replace(R.id.fragmentContainer, fragment)
                .commit()
        }
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Create a `TabbedScreen` composable with `NavigationBar`:

    ```kotlin TabbedScreen.kt lines theme={null}
    import androidx.compose.foundation.layout.Box
    import androidx.compose.foundation.layout.fillMaxSize
    import androidx.compose.foundation.layout.size
    import androidx.compose.material3.Icon
    import androidx.compose.material3.NavigationBar
    import androidx.compose.material3.NavigationBarItem
    import androidx.compose.material3.Scaffold
    import androidx.compose.material3.Text
    import androidx.compose.runtime.Composable
    import androidx.compose.runtime.getValue
    import androidx.compose.runtime.mutableStateOf
    import androidx.compose.runtime.saveable.rememberSaveable
    import androidx.compose.runtime.setValue
    import androidx.compose.ui.Modifier
    import androidx.compose.ui.res.painterResource
    import androidx.compose.ui.unit.dp
    import com.cometchat.chat.models.Group
    import com.cometchat.chat.models.User
    import com.cometchat.uikit.compose.presentation.calllogs.ui.CometChatCallLogs
    import com.cometchat.uikit.compose.presentation.conversations.ui.CometChatConversations
    import com.cometchat.uikit.compose.presentation.groups.ui.CometChatGroups
    import com.cometchat.uikit.compose.presentation.users.ui.CometChatUsers

    enum class Tab(val label: String, val iconRes: Int) {
        Chats("Chats", R.drawable.ic_chats),
        Calls("Calls", R.drawable.ic_calls),
        Users("Users", R.drawable.ic_users),
        Groups("Groups", R.drawable.ic_groups)
    }

    @Composable
    fun TabbedScreen(
        onUserClick: (User) -> Unit = {},
        onGroupClick: (Group) -> Unit = {}
    ) {
        var selectedTab by rememberSaveable { mutableStateOf(Tab.Chats) }

        Scaffold(
            bottomBar = {
                NavigationBar {
                    Tab.entries.forEach { tab ->
                        NavigationBarItem(
                            selected = selectedTab == tab,
                            onClick = { selectedTab = tab },
                            icon = {
                                Icon(
                                    painter = painterResource(tab.iconRes),
                                    contentDescription = tab.label,
                                    modifier = Modifier.size(32.dp)
                                )
                            },
                            label = { Text(tab.label) }
                        )
                    }
                }
            }
        ) { paddingValues ->
            Box(
                modifier = Modifier
                    .fillMaxSize()
                    .padding(paddingValues)
            ) {
                when (selectedTab) {
                    Tab.Chats -> CometChatConversations(
                        modifier = Modifier.fillMaxSize(),
                        title = "Chats",
                        onItemClick = { conversation ->
                            when (val entity = conversation.conversationWith) {
                                is User -> onUserClick(entity)
                                is Group -> onGroupClick(entity)
                            }
                        }
                    )
                    Tab.Calls -> CometChatCallLogs(
                        modifier = Modifier.fillMaxSize()
                    )
                    Tab.Users -> CometChatUsers(
                        modifier = Modifier.fillMaxSize(),
                        onItemClick = { user -> onUserClick(user) }
                    )
                    Tab.Groups -> CometChatGroups(
                        modifier = Modifier.fillMaxSize(),
                        onItemClick = { group -> onGroupClick(group) }
                    )
                }
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Step 2: Create Tab Content

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Create a Fragment for each tab. Each Fragment inflates a layout containing the corresponding CometChat component.

    **ChatsFragment:**

    ```kotlin ChatsFragment.kt lines theme={null}
    import android.os.Bundle
    import android.view.LayoutInflater
    import android.view.View
    import android.view.ViewGroup
    import androidx.fragment.app.Fragment

    class ChatsFragment : Fragment() {
        override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View? {
            return inflater.inflate(R.layout.fragment_chats, container, false)
        }
    }
    ```

    ```xml fragment_chats.xml lines theme={null}
    <?xml version="1.0" encoding="utf-8"?>
    <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="match_parent">

        <com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations
            android:id="@+id/conversations"
            android:layout_width="match_parent"
            android:layout_height="match_parent" />

    </FrameLayout>
    ```

    **CallLogsFragment:**

    ```kotlin CallLogsFragment.kt lines theme={null}
    import android.os.Bundle
    import android.view.LayoutInflater
    import android.view.View
    import android.view.ViewGroup
    import androidx.fragment.app.Fragment

    class CallLogsFragment : Fragment() {
        override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View? {
            return inflater.inflate(R.layout.fragment_call_logs, container, false)
        }
    }
    ```

    ```xml fragment_call_logs.xml lines theme={null}
    <?xml version="1.0" encoding="utf-8"?>
    <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="match_parent">

        <com.cometchat.uikit.kotlin.presentation.calllogs.ui.CometChatCallLogs
            android:id="@+id/call_logs"
            android:layout_width="match_parent"
            android:layout_height="match_parent" />

    </FrameLayout>
    ```

    **UsersFragment:**

    ```kotlin UsersFragment.kt lines theme={null}
    import android.os.Bundle
    import android.view.LayoutInflater
    import android.view.View
    import android.view.ViewGroup
    import androidx.fragment.app.Fragment

    class UsersFragment : Fragment() {
        override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View? {
            return inflater.inflate(R.layout.fragment_users, container, false)
        }
    }
    ```

    ```xml fragment_users.xml lines theme={null}
    <?xml version="1.0" encoding="utf-8"?>
    <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="match_parent">

        <com.cometchat.uikit.kotlin.presentation.users.ui.CometChatUsers
            android:id="@+id/users"
            android:layout_width="match_parent"
            android:layout_height="match_parent" />

    </FrameLayout>
    ```

    **GroupsFragment:**

    ```kotlin GroupsFragment.kt lines theme={null}
    import android.os.Bundle
    import android.view.LayoutInflater
    import android.view.View
    import android.view.ViewGroup
    import androidx.fragment.app.Fragment

    class GroupsFragment : Fragment() {
        override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View? {
            return inflater.inflate(R.layout.fragment_groups, container, false)
        }
    }
    ```

    ```xml fragment_groups.xml lines theme={null}
    <?xml version="1.0" encoding="utf-8"?>
    <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="match_parent">

        <com.cometchat.uikit.kotlin.presentation.groups.ui.CometChatGroups
            android:id="@+id/groups"
            android:layout_width="match_parent"
            android:layout_height="match_parent" />

    </FrameLayout>
    ```

    <Info>
      Download the navigation icons from the [CometChat UI Kit repository](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-java/src/main/res/drawable) and place them in your `res/drawable/` directory.
    </Info>
  </Tab>

  <Tab title="Jetpack Compose">
    No separate files needed — the tab content is already defined inline in the `TabbedScreen` composable above. Each `when` branch renders the corresponding CometChat component directly.
  </Tab>
</Tabs>

***

## Step 3: Launch the Tabbed Screen

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Launch `TabbedActivity` from your `MainActivity` after successful login:

    ```kotlin MainActivity.kt lines theme={null}
    private fun loginUser() {
        CometChatUIKit.login("cometchat-uid-1", object : CometChat.CallbackListener<User>() {
            override fun onSuccess(user: User) {
                Log.d(TAG, "Login successful: ${user.uid}")

                // Launch Tab-Based Chat Experience
                startActivity(Intent(this@MainActivity, TabbedActivity::class.java))
            }

            override fun onError(e: CometChatException) {
                Log.e(TAG, "Login failed: ${e.message}")
            }
        })
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Render `TabbedScreen` from your `MainActivity` after successful login:

    ```kotlin MainActivity.kt lines theme={null}
    setContent {
        when {
            error != null -> {
                Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                    Text(error ?: "Unknown error")
                }
            }
            !isReady -> {
                Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                    CircularProgressIndicator()
                }
            }
            else -> {
                TabbedScreen(
                    onUserClick = { user ->
                        // Navigate to message screen with user
                    },
                    onGroupClick = { group ->
                        // Navigate to message screen with group
                    }
                )
            }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Step 4: Register Activity & Permissions

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add the activity to your `AndroidManifest.xml`:

    ```xml AndroidManifest.xml lines theme={null}
    <application ...>
        <activity android:name=".TabbedActivity" />
    </application>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    No additional activities needed — everything runs inside your existing `MainActivity`.
  </Tab>
</Tabs>

Ensure you've added the required permissions in your `AndroidManifest.xml`:

```xml AndroidManifest.xml lines theme={null}
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

For call features, also add:

```xml AndroidManifest.xml lines theme={null}
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
```

***

## Next Steps

<CardGroup>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/android/components-overview">
    Explore all available UI Kit components and their customization options
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/android/theme-introduction">
    Customize colors, fonts, and styles to match your brand
  </Card>

  <Card title="Integration" icon="rocket" href="/ui-kit/android/getting-started">
    Back to the main integration guide
  </Card>

  <Card title="Feature Guides" icon="book" href="/ui-kit/android/guide-overview">
    Add capabilities like threaded messages, blocking, and group management
  </Card>
</CardGroup>


# Introduction
Source: https://www.cometchat.com/docs/ui-kit/android/theme-introduction

Create and apply a global CometChat UI Kit theme to match your brand across light and dark modes.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                                         |
  | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
  | Kotlin XML Views | Override XML theme attributes in `themes.xml` extending `CometChatTheme.DayNight`, or use `CometChatTheme.setPrimaryColor()` programmatically |
  | Jetpack Compose  | Wrap content in `CometChatTheme {}` composable, customize via `CometChatColorScheme`, `CometChatTypography`, and `Shapes`                     |
  | Key color tokens | `primary`, `backgroundColor1`, `backgroundColor2`, `textColorPrimary`, `textColorSecondary`, `strokeColorDefault`                             |
  | Dark mode        | Kotlin: `values-night/themes.xml` overrides. Compose: provide a different `CometChatColorScheme` based on `isSystemInDarkTheme()`             |
</Accordion>

Create and apply a global CometChat UI Kit theme that matches your brand across light and dark modes.

## When to use this

* You want a single UI Kit theme that matches your app branding.
* You need light and dark mode support with consistent colors.
* You want to customize primary, background, or text colors across all UI Kit components.

## Prerequisites

* CometChat UI Kit is installed and initialized.
* You've completed the [Kotlin Integration](/docs/ui-kit/android/getting-started-kotlin) or [Jetpack Compose Integration](/docs/ui-kit/android/getting-started-jetpack).

***

## Core Concepts

<Tabs>
  <Tab title="Kotlin (XML Views)">
    The Kotlin XML UI Kit uses Android's theme attribute system. All components read colors, typography, and fonts from XML theme attributes prefixed with `cometchat`.

    * `CometChatTheme.DayNight` — base theme built on `Theme.MaterialComponents.DayNight.NoActionBar`
    * Theme attributes like `cometchatPrimaryColor`, `cometchatBackgroundColor1`, etc. are defined in your `themes.xml`
    * Programmatic access via `CometChatTheme.getPrimaryColor(context)` and `CometChatTheme.setPrimaryColor(color)`
    * Dark mode via `values-night/themes.xml` overrides

    **Precedence:**

    1. Programmatic overrides via `CometChatTheme.set*()` (highest)
    2. Activity-level theme
    3. Application-level theme
    4. `CometChatTheme.DayNight` defaults (lowest)
  </Tab>

  <Tab title="Jetpack Compose">
    The Compose UI Kit uses a `CometChatTheme` composable that provides colors, typography, and shapes via `CompositionLocalProvider`.

    * `CometChatTheme {}` — wraps your content and provides theme values
    * `CometChatTheme.colorScheme` — access colors like `CometChatTheme.colorScheme.primary`
    * `CometChatTheme.typography` — access text styles like `CometChatTheme.typography.titleMedium`
    * `CometChatTheme.shapes` — access shape definitions
    * Dark mode by providing a different `CometChatColorScheme` based on system theme
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    <Steps>
      <Step title="Create your theme">
        In `app/src/main/res/values/themes.xml`, extend `CometChatTheme.DayNight`:

        ```xml themes.xml lines theme={null}
        <resources>
            <style name="AppTheme" parent="CometChatTheme.DayNight">
                <!-- Your customizations go here -->
            </style>
        </resources>
        ```
      </Step>

      <Step title="Apply the theme">
        In `AndroidManifest.xml`, set the theme on your application:

        ```xml AndroidManifest.xml lines theme={null}
        <application
            android:theme="@style/AppTheme"
            ...>
        </application>
        ```
      </Step>

      <Step title="Build and verify">
        Run the app and confirm UI Kit screens use your theme in both light and dark mode.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Jetpack Compose">
    <Steps>
      <Step title="Wrap your content">
        Wrap your composable content with `CometChatTheme`:

        ```kotlin lines theme={null}
        import com.cometchat.uikit.compose.theme.CometChatTheme

        CometChatTheme {
            // Your CometChat UI Kit composables here
            CometChatConversations(...)
        }
        ```
      </Step>

      <Step title="Build and verify">
        Run the app and confirm UI Kit screens render with the default CometChat theme.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Change the Primary Color

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Override `cometchatPrimaryColor` in your theme:

    ```xml themes.xml lines theme={null}
    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatPrimaryColor">#F76808</item>
    </style>
    ```

    Or set it programmatically:

    ```kotlin lines theme={null}
    CometChatTheme.setPrimaryColor(Color.parseColor("#F76808"))
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Provide a custom `CometChatColorScheme`:

    ```kotlin lines theme={null}
    val customColors = CometChatColorScheme.light().copy(
        primary = Color(0xFFF76808)
    )

    CometChatTheme(colorScheme = customColors) {
        // Your content
    }
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

***

## Customize Common Theme Attributes

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml themes.xml lines theme={null}
    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <!-- Primary brand color -->
        <item name="cometchatPrimaryColor">#6851D6</item>

        <!-- Background colors -->
        <item name="cometchatBackgroundColor1">#FFFFFF</item>
        <item name="cometchatBackgroundColor2">#F5F5F5</item>

        <!-- Text colors -->
        <item name="cometchatTextColorPrimary">#000000</item>
        <item name="cometchatTextColorSecondary">#666666</item>

        <!-- Border and divider colors -->
        <item name="cometchatStrokeColorDefault">#E0E0E0</item>
    </style>
    ```

    Or programmatically:

    ```kotlin lines theme={null}
    CometChatTheme.setPrimaryColor(Color.parseColor("#6851D6"))
    CometChatTheme.setBackgroundColor1(Color.parseColor("#FFFFFF"))
    CometChatTheme.setBackgroundColor2(Color.parseColor("#F5F5F5"))
    CometChatTheme.setTextColorPrimary(Color.parseColor("#000000"))
    CometChatTheme.setTextColorSecondary(Color.parseColor("#666666"))
    CometChatTheme.setStrokeColorDefault(Color.parseColor("#E0E0E0"))
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    val customColors = CometChatColorScheme.light().copy(
        primary = Color(0xFF6851D6),
        backgroundColor1 = Color(0xFFFFFFFF),
        backgroundColor2 = Color(0xFFF5F5F5),
        textColorPrimary = Color(0xFF000000),
        textColorSecondary = Color(0xFF666666),
        strokeColorDefault = Color(0xFFE0E0E0)
    )

    CometChatTheme(colorScheme = customColors) {
        // Your content
    }
    ```
  </Tab>
</Tabs>

***

## Add Dark Mode Support

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Create `app/src/main/res/values-night/themes.xml` and override attributes for dark mode:

    ```xml values-night/themes.xml lines theme={null}
    <resources>
        <style name="AppTheme" parent="CometChatTheme.DayNight">
            <item name="cometchatPrimaryColor">#8B7FFF</item>
            <item name="cometchatBackgroundColor1">#1A1A1A</item>
            <item name="cometchatTextColorPrimary">#FFFFFF</item>
        </style>
    </resources>
    ```

    Android automatically applies `values-night` overrides when the system uses dark mode.
  </Tab>

  <Tab title="Jetpack Compose">
    Provide different color schemes based on system theme:

    ```kotlin lines theme={null}
    val isDark = isSystemInDarkTheme()

    val colorScheme = if (isDark) {
        CometChatColorScheme.dark().copy(
            primary = Color(0xFF8B7FFF),
            backgroundColor1 = Color(0xFF1A1A1A),
            textColorPrimary = Color(0xFFFFFFFF)
        )
    } else {
        CometChatColorScheme.light().copy(
            primary = Color(0xFF6851D6)
        )
    }

    CometChatTheme(colorScheme = colorScheme) {
        // Your content
    }
    ```
  </Tab>
</Tabs>

***

## Apply a Theme to a Specific Activity

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Set `android:theme` on a specific `<activity>` in `AndroidManifest.xml`:

    ```xml AndroidManifest.xml lines theme={null}
    <application android:theme="@style/AppTheme" ...>
        <activity
            android:name=".ChatActivity"
            android:theme="@style/ChatTheme" />
    </application>
    ```

    Activity-level themes override the application-level theme.
  </Tab>

  <Tab title="Jetpack Compose">
    Wrap a specific screen with a different `CometChatTheme`:

    ```kotlin lines theme={null}
    // Default theme for most screens
    CometChatTheme {
        MainScreen()
    }

    // Custom theme for a specific screen
    CometChatTheme(colorScheme = chatScreenColors) {
        MessageScreen(user = user, onBack = { })
    }
    ```
  </Tab>
</Tabs>

***

## Color Token Reference

| Token                | Description                               |
| -------------------- | ----------------------------------------- |
| `primary`            | Buttons, highlights, interactive elements |
| `backgroundColor1`   | Main surface/panel background             |
| `backgroundColor2`   | Secondary surface background              |
| `backgroundColor3`   | Tertiary surface background               |
| `backgroundColor4`   | Quaternary surface background             |
| `textColorPrimary`   | Primary text                              |
| `textColorSecondary` | Secondary/subtitle text                   |
| `textColorTertiary`  | Tertiary/hint text                        |
| `textColorHighlight` | Highlighted/linked text                   |
| `strokeColorDefault` | Default borders and dividers              |
| `strokeColorLight`   | Light borders                             |
| `strokeColorDark`    | Dark borders                              |
| `successColor`       | Success indicators                        |
| `errorColor`         | Error indicators                          |
| `warningColor`       | Warning indicators                        |
| `infoColor`          | Info indicators                           |

<Frame>
  <img />
</Frame>


# Threaded Messages Header
Source: https://www.cometchat.com/docs/ui-kit/android/threaded-messages-header

Displays the parent message bubble and reply count for a threaded conversation.

`CometChatThreadHeader` renders the parent message bubble and reply count for a threaded conversation. It requires a parent message to display.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatThreadHeader` is a header component for threaded message views. Wire it above a `CometChatMessageList` and `CometChatMessageComposer` to build a complete threaded conversation layout.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_thread.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.threadheader.ui.CometChatThreadHeader
        android:id="@+id/thread_header"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />
    ```

    ```kotlin lines theme={null}
    val threadHeader = findViewById<CometChatThreadHeader>(R.id.thread_header)
    threadHeader.setParentMessage(parentMessage)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatThreadHeader(
        parentMessage = parentMessage
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add to your layout XML:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.threadheader.ui.CometChatThreadHeader
        android:id="@+id/thread_header"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />
    ```

    Set the parent message — this is required:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_thread)

        val threadHeader = findViewById<CometChatThreadHeader>(R.id.thread_header)
        threadHeader.setParentMessage(baseMessage)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    @Composable
    fun ThreadScreen() {
        CometChatThreadHeader(
            parentMessage = baseMessage
        )
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

***

## Actions and Events

### Callback Methods

`CometChatThreadHeader` is a display-only header. It does not expose component-specific callbacks like `setOnItemClick` or `setOnError`.

### SDK Events (Real-Time, Automatic)

The component listens to SDK events internally via its ViewModel. No manual setup needed.

| SDK Listener        | Internal behavior                 |
| ------------------- | --------------------------------- |
| Message edited      | Updates the parent message bubble |
| Message deleted     | Updates the parent message bubble |
| Reply count changed | Updates the reply count indicator |

***

## Functionality

| Method (Kotlin XML)                  | Compose Parameter         | Description                       |
| ------------------------------------ | ------------------------- | --------------------------------- |
| `setParentMessage(message)`          | `parentMessage = message` | Set the parent message (required) |
| `setUser(user)`                      | `user = user`             | Set the user context              |
| `setGroup(group)`                    | `group = group`           | Set the group context             |
| `setReactionVisibility(View.GONE)`   | `hideReactions = true`    | Toggle reactions on parent bubble |
| `setAvatarVisibility(View.GONE)`     | `hideAvatar = true`       | Toggle avatar visibility          |
| `setReceiptsVisibility(View.GONE)`   | `hideReceipts = true`     | Toggle read receipts              |
| `setReplyCountVisibility(View.GONE)` | `hideReplyCount = true`   | Toggle reply count text           |

***

## Style

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Define a custom style in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="CustomOutgoingMessageBubbleStyle" parent="CometChatOutgoingMessageBubbleStyle">
        <item name="cometchatMessageBubbleBackgroundColor">#F76808</item>
    </style>

    <style name="CustomIncomingMessageBubbleStyle" parent="CometChatIncomingMessageBubbleStyle">
        <item name="cometchatMessageBubbleBackgroundColor">#F76808</item>
    </style>

    <style name="CustomThreadHeaderStyle" parent="CometChatThreadHeaderStyle">
        <item name="cometchatThreadHeaderOutgoingMessageBubbleStyle">@style/CustomOutgoingMessageBubbleStyle</item>
        <item name="cometchatThreadHeaderIncomingMessageBubbleStyle">@style/CustomIncomingMessageBubbleStyle</item>
        <item name="cometchatThreadHeaderBackgroundColor">#FEEDE1</item>
        <item name="cometchatThreadHeaderReplyCountTextColor">#F76808</item>
        <item name="cometchatThreadHeaderReplyCountBackgroundColor">#FEEDE1</item>
    </style>
    ```

    ```kotlin lines theme={null}
    threadHeader.setStyle(R.style.CustomThreadHeaderStyle)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatThreadHeader(
        parentMessage = baseMessage,
        style = CometChatThreadHeaderStyle.default().copy(
            backgroundColor = Color(0xFFFEEDE1),
            replyCountTextColor = Color(0xFFF76808),
            replyCountBackgroundColor = Color(0xFFFEEDE1)
        )
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

See [Component Styling](/docs/ui-kit/android/component-styling) for the full reference.

***

## ViewModel

```kotlin lines theme={null}
val viewModel = ViewModelProvider(this)
    .get(CometChatThreadHeaderViewModel::class.java)
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    threadHeader.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatThreadHeader(
        parentMessage = baseMessage,
        threadHeaderViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

See [ViewModel & Data](/docs/ui-kit/android/customization-viewmodel-data) for state observation and custom repositories.

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="messages" href="/ui-kit/android/message-list">
    Display messages in a conversation
  </Card>

  <Card title="Message Header" icon="heading" href="/ui-kit/android/message-header">
    Display user/group info in the toolbar
  </Card>

  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/android/message-composer">
    Rich input for sending messages
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/android/conversations">
    Browse recent conversations
  </Card>
</CardGroup>


# Troubleshooting
Source: https://www.cometchat.com/docs/ui-kit/android/troubleshooting

Common failure modes and fixes for the CometChat Android V6 UI Kit.

<Accordion title="AI Integration Quick Reference">
  | Field             | Value                                                                                                                                                                 |
  | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Page type         | Troubleshooting reference                                                                                                                                             |
  | Packages          | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack`                                                                                                  |
  | Scope             | All CometChat Android UI Kit v6 issues — initialization, theming, components, calling, extensions, AI features, localization, sound, events, methods, text formatters |
  | When to reference | When a component fails to render, data is missing, styling doesn't apply, or a feature doesn't appear                                                                 |
</Accordion>

## Initialization and Login

| Symptom                                | Cause                                                     | Fix                                                                                                                                             |
| -------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `CometChatUIKit.init()` fails silently | Invalid App ID, Region, or Auth Key                       | Double-check credentials from the [CometChat Dashboard](https://app.cometchat.com/)                                                             |
| Blank screen after login               | Component rendered before `init()` or `login()` completes | Ensure `init()` → `login()` order completes before rendering any UI Kit component. See [Methods](/docs/ui-kit/android/methods)                       |
| Component renders but shows no data    | User not logged in                                        | Call `CometChatUIKit.login("UID", callback)` after init resolves                                                                                |
| Login fails with "UID not found"       | UID doesn't exist in your CometChat app                   | Create the user via Dashboard, SDK, or REST API first                                                                                           |
| `getLoggedInUser()` returns null       | User not logged in or session expired                     | Call `login()` or `loginWithAuthToken()` first                                                                                                  |
| Auth Key exposed in production         | Using Auth Key instead of Auth Token                      | Switch to [`loginWithAuthToken()`](/docs/ui-kit/android/methods#login-using-auth-token) for production. Generate tokens server-side via the REST API |
| `init()` callback never fires          | Network blocked or incorrect region                       | Verify internet permission in `AndroidManifest.xml` and confirm the region matches your Dashboard (`us`, `eu`, `in`)                            |
| `minSdk` build error                   | Project `minSdk` is below 28                              | Set `minSdk` to 28 or higher in your app-level `build.gradle` — the UI Kit requires Android 9.0 (API 28)+                                       |
| Dependency resolution failure          | Missing CometChat Maven repository                        | Add `maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")` to `settings.gradle` repositories block                               |
| Wrong import for `CometChatUIKit`      | Using old package path                                    | Use `import com.cometchat.uikit.core.CometChatUIKit` for both `chatuikit-kotlin` and `chatuikit-jetpack` modules                                |

***

## Theming and Styling

| Symptom                                          | Cause                                               | Fix                                                                                                                                                                                                 |
| ------------------------------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Theme not applied / crash on launch              | App theme does not extend `CometChatTheme.DayNight` | Set `parent="CometChatTheme.DayNight"` in your `themes.xml` style and apply it in `AndroidManifest.xml`                                                                                             |
| Dark mode not working                            | System dark mode not propagated to CometChat theme  | Ensure your app theme parent is `CometChatTheme.DayNight` — it inherits `Theme.MaterialComponents.DayNight.NoActionBar` and responds to system dark mode automatically                              |
| Custom colors not applying                       | Overriding wrong theme attributes                   | Check the [Color Resources](/docs/ui-kit/android/color-resources) page for the correct attribute names                                                                                                   |
| Font not changing                                | Custom font set on wrong theme attribute            | Override `cometchatFontFamily` in your theme to apply a custom font globally                                                                                                                        |
| Styles leak into host app                        | CometChat theme attributes conflict with app theme  | Scope CometChat theme overrides to the Activity hosting CometChat components rather than the application-level theme                                                                                |
| Styles apply to some screens but not others      | Activity uses a different theme                     | Verify the Activity hosting CometChat components has `android:theme` set to your custom theme in `AndroidManifest.xml`                                                                              |
| Changes apply in light mode but not dark mode    | Only `values/themes.xml` updated                    | Update both `values/themes.xml` and `values-night/themes.xml` with your overrides                                                                                                                   |
| Drawable changes not visible                     | Stale build cache                                   | Rebuild the app after adding or replacing drawable files                                                                                                                                            |
| Bubble style not applying                        | Custom style linked to wrong hub                    | Confirm the style is linked inside the correct hub (`CustomIncomingMessageBubbleStyle` or `CustomOutgoingMessageBubbleStyle`). See [Message Bubble Styling](/docs/ui-kit/android/message-bubble-styling) |
| Only incoming or outgoing bubble changes         | Separate styles required per direction              | Define separate styles for incoming and outgoing bubbles — changing one does not affect the other                                                                                                   |
| Component style attribute not recognized         | Wrong attribute name                                | Confirm the exact attribute name in the linked attribute reference file on the component page                                                                                                       |
| Compose theme not applying (`chatuikit-jetpack`) | Not wrapping in `CometChatTheme` composable         | In `chatuikit-jetpack`, wrap your CometChat composables inside `CometChatTheme { }` to apply theming                                                                                                |

***

## Components

| Symptom                                                | Cause                                      | Fix                                                                                                                                                                           |
| ------------------------------------------------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Component not rendering                                | `init()` or `login()` not complete         | Ensure both `init()` and `login()` resolve before inflating any CometChat view. Use a callback or state flag to gate rendering                                                |
| List is empty despite having data                      | User not logged in                         | Verify a user is logged in with `CometChatUIKit.login()` before displaying the component. Components fetch data for the logged-in user only                                   |
| Callback not firing                                    | Wrong listener method or signature         | Check the Actions section on the component page for the exact method name and parameter types                                                                                 |
| `setOnItemClick` not firing                            | Selection mode set to `MULTIPLE`           | Item clicks may be consumed by selection logic. Set `setSelectionMode(NONE)` if you need standard click behavior                                                              |
| Messages not loading                                   | Invalid `User` or `Group` object passed    | Fetch the user or group via the SDK before passing it to the component                                                                                                        |
| View not appearing in XML layout (`chatuikit-kotlin`)  | Missing fully qualified class name         | Use the full XML element name, e.g. `<com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations />`                                                     |
| Custom view not rendering                              | `createView` returns `null`                | If `createView` returns `null`, the default view is used. Return a valid inflated `View` to replace the default                                                               |
| `ActivityResultLauncher` not initialized               | MessageComposer created outside `onCreate` | Create `CometChatMessageComposer` in the `onCreate` state of an Activity. In a Fragment, ensure the Fragment is loaded during the Activity's `onCreate`                       |
| Sticker button disappears after setting auxiliary view | Auxiliary button overridden                | Retrieve default auxiliary buttons via `CometChatUIKit.getDataSource().getAuxiliaryOption()` and include them in your custom layout before calling `setAuxiliaryButtonView()` |
| Typing indicator not showing                           | Custom subtitle view overrides it          | The typing indicator renders in the default subtitle area. When you provide a custom `setSubtitleView`, it replaces the entire subtitle layout including the typing indicator |
| `disableSoundForMessages(true)` has no effect          | Called after component starts loading      | Call `disableSoundForMessages(true)` before the component starts loading                                                                                                      |
| Filters not applied                                    | Builder not set on component               | Ensure you call the appropriate `set*RequestBuilder(builder)` method on the component instance after creating and configuring the builder                                     |
| ProGuard/R8 strips CometChat classes                   | Missing keep rules for CometChat           | Add `-keep class com.cometchat.** { *; }` to your `proguard-rules.pro` file                                                                                                   |
| Jetifier errors during build                           | `android.enableJetifier=true` not set      | Add `android.enableJetifier=true` to `gradle.properties`                                                                                                                      |
| `CometChatConversationList` not found                  | Component renamed in v6                    | Use `CometChatConversations` instead of `CometChatConversationList`                                                                                                           |
| `CometChatThreadedMessagesHeader` not found            | Component renamed in v5                    | Use `CometChatThreadHeader` instead                                                                                                                                           |

***

## Calling

| Symptom                                      | Cause                                             | Fix                                                                                                                                                                        |
| -------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Call buttons not appearing                   | `com.cometchat:calls-sdk-android` not installed   | Add the calls SDK dependency to your `build.gradle` — the UI Kit auto-detects it. See [Integration](/docs/ui-kit/android/getting-started)                                       |
| Incoming call screen not showing             | `CometChatIncomingCall` not added to the Activity | Render `CometChatIncomingCall` at the root of your Activity layout so it can listen for incoming calls                                                                     |
| Incoming calls not detected                  | Call events not observed                          | Ensure you collect from `CometChatEvents.onIncomingCall` SharedFlow in your Application class or relevant scope                                                            |
| Call connects but no audio/video             | Missing runtime permissions                       | Request `CAMERA`, `RECORD_AUDIO`, and `INTERNET` permissions at runtime before initiating calls                                                                            |
| Call fails immediately                       | Calls SDK version mismatch                        | Ensure `com.cometchat:calls-sdk-android` version is compatible with your UI Kit version. Check the [Integration](/docs/ui-kit/android/getting-started) page for version pairing |
| Sound still plays after disabling            | `disableSoundForCalls(true)` called too late      | Call `disableSoundForCalls(true)` before the component starts the call. If called after the call is initiated, it may not take effect                                      |
| Custom call sound not playing                | Audio file missing or wrong path                  | Verify the sound file exists in `res/raw` and pass the correct `@RawRes int` resource ID to `setCustomSoundForCalls`                                                       |
| Call events not received                     | Not collecting from SharedFlow                    | Use `CometChatEvents` singleton and collect from the appropriate SharedFlow (e.g., `onCallEnded`, `onIncomingCall`) in a coroutine scope                                   |
| Call events still firing after screen closed | Coroutine scope not cancelled                     | Cancel the coroutine scope collecting from `CometChatEvents` SharedFlows in `onDestroy()` or `onDestroyView()`                                                             |

***

## Extensions

| Symptom                                | Cause                                          | Fix                                                                                    |
| -------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------- |
| Extension feature not appearing        | Extension not activated in CometChat Dashboard | Enable the specific extension from your [Dashboard](/docs/fundamentals/extensions-overview) |
| Stickers not showing in composer       | Sticker extension not enabled                  | Activate [Sticker Extension](/docs/fundamentals/stickers) in Dashboard                      |
| Polls option missing from action sheet | Polls extension not enabled                    | Activate [Polls Extension](/docs/fundamentals/polls) in Dashboard                           |
| Link preview not rendering in messages | Link Preview extension not enabled             | Activate [Link Preview Extension](/docs/fundamentals/link-preview) in Dashboard             |

***

## AI Features

| Symptom                                 | Cause                                          | Fix                                                                                                         |
| --------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| AI features not appearing               | Feature not activated in CometChat Dashboard   | Enable the specific AI feature from your [Dashboard](/docs/fundamentals/ai-user-copilot/overview)                |
| Conversation Starter not showing        | Feature not enabled or no conversation context | Ensure [Conversation Starter](/docs/fundamentals/ai-user-copilot/conversation-starter) is activated in Dashboard |
| Smart Replies not appearing in composer | Feature not enabled in Dashboard               | Ensure [Smart Replies](/docs/fundamentals/ai-user-copilot/smart-replies) is activated in Dashboard               |

***

## Localization

| Symptom                                         | Cause                               | Fix                                                                                                                                                                  |
| ----------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UI text not translated                          | Wrong language code                 | Use a `Language.Code` constant from the supported languages list in [Localize](/docs/ui-kit/android/localize)                                                             |
| `setLocale` called after UI Kit screens render  | Locale applied too late             | Call `CometChatLocalize.setLocale(...)` before launching any UI Kit screen                                                                                           |
| String overrides not appearing                  | Key name mismatch in `strings.xml`  | Verify the key name matches exactly (e.g., `cometchat_chats`). See [Localize](/docs/ui-kit/android/localize)                                                              |
| Changes not visible after editing `strings.xml` | Stale build cache                   | Clean and rebuild the project after editing string resources                                                                                                         |
| Date/time labels unchanged                      | `DateTimeFormatterCallback` not set | Add `setDateTimeFormatterCallback(...)` to the same `UIKitSettings` instance passed to `CometChatUIKit.init()`. See [Methods](/docs/ui-kit/android/methods#dateformatter) |

***

## Sound

| Symptom                  | Cause                                                  | Fix                                                                                                                              |
| ------------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| No sound plays           | `CometChatSoundManager` created with invalid `Context` | Ensure you pass a valid `Context` when instantiating `CometChatSoundManager`. See [Sound Manager](/docs/ui-kit/android/sound-manager) |
| Custom sound not playing | Audio file missing or wrong format                     | Place audio files in `res/raw` and reference them as `R.raw.<file>`. Ensure the format is supported by Android (WAV/MP3/OGG)     |
| Sound plays only once    | Creating a new `CometChatSoundManager` per event       | Reuse the same `CometChatSoundManager` instance instead of creating one per event                                                |
| Silent on device         | Device volume or ringer mode                           | Check device volume and ringer mode settings                                                                                     |

***

## Events

| Symptom                           | Cause                                                        | Fix                                                                                                                                           |
| --------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Event not received                | Not collecting from the correct `CometChatEvents` SharedFlow | Check the [Events](/docs/ui-kit/android/events) page for exact SharedFlow names and collect in a coroutine scope                                   |
| Duplicate event triggers          | Multiple coroutine collectors active                         | Cancel previous collection scopes when re-subscribing, or use `lifecycleScope` to auto-cancel                                                 |
| Event fires but UI doesn't update | Callback not running on main thread                          | Collect SharedFlows using `Dispatchers.Main` or `lifecycleScope.launch { }` to ensure UI updates run on the main thread                       |
| Missed events after rotation      | Collection scope not re-created after Activity recreation    | Collect from `CometChatEvents` SharedFlows in `onCreate()` or `onViewCreated()` using `lifecycleScope`                                        |
| Not all event types received      | Only collecting from some SharedFlows                        | Each event type has its own SharedFlow on `CometChatEvents`. Collect from every flow you need (e.g., `onGroupCreated`, `onGroupMemberJoined`) |

***

## Methods

| Symptom                                        | Cause                                      | Fix                                                                                                                                                                                                                  |
| ---------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UI Kit method fails                            | Called before `init()` completes           | Call `CometChatUIKit.init()` first and wait for the `onSuccess` callback before calling `login()`, `sendTextMessage()`, or any other UI Kit method                                                                   |
| Messages sent but UI not updating              | Using SDK method instead of UI Kit wrapper | Use `CometChatUIKit.sendTextMessage()` instead of `CometChat.sendTextMessage()`. The UI Kit wrapper automatically updates Message List and Conversations components via internal events                              |
| Failures silently ignored                      | `onError` callback left empty              | Every UI Kit method accepts a `CallbackListener` with `onError`. Log the `CometChatException` or display an error message to the user                                                                                |
| Session conflicts after switching users        | Previous user not logged out               | Call `CometChatUIKit.logout()` and wait for `onSuccess` before logging in a different user                                                                                                                           |
| Custom message not appearing in Message List   | No `MessageTemplate` registered            | Custom messages and custom interactive messages require a registered [MessageTemplate](/docs/ui-kit/android/message-template) that defines how to render them                                                             |
| Interactive message missing sender or receiver | `sender` or `receiver` not set             | For `FormMessage`, `CardMessage`, `SchedulerMessage`, and `CustomInteractiveMessage`, set both `sender` (via `CometChatUIKit.getLoggedInUser()`) and `receiver` (the target `User` or `Group` object) before sending |

***

## Text Formatters

| Symptom                                      | Cause                                          | Fix                                                                                                                                                                                             |
| -------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mentions render as plain text                | Formatter not added to component               | Create a `CometChatMentionsFormatter`, add it to a `List<CometChatTextFormatter>`, and pass the list to the component via `setTextFormatters()`                                                 |
| `setTextFormatters()` has no effect          | Called with empty list                         | Add at least one formatter to the list before calling `setTextFormatters()`                                                                                                                     |
| Custom mention style not applied in composer | Style not set on formatter                     | Call `mentionFormatter.setMessageComposerMentionTextStyle(context, R.style.YourStyle)` before passing the formatter to the component                                                            |
| Custom mention style not applied in bubbles  | Only one direction styled                      | Call both `setOutgoingBubbleMentionTextStyle()` and `setIncomingBubbleMentionTextStyle()` — setting only one leaves the other with default style                                                |
| Shortcut suggestions not appearing           | Formatter not registered or extension disabled | Confirm the `ShortCutFormatter` is added to the formatters list via `setTextFormatters()`, and that the `message-shortcuts` extension is enabled in the [Dashboard](https://app.cometchat.com/) |
| `setOnMentionClick` callback not firing      | Formatter not passed to component              | Ensure the formatter is passed to the component via `setTextFormatters()` after calling `setOnMentionClick()`                                                                                   |


# Upgrading from V5 to V6
Source: https://www.cometchat.com/docs/ui-kit/android/upgrading-from-v5

Migrate your Android app from CometChat UI Kit V5 to V6 with updated dependencies, architecture, and API changes.

## Introduction

The **CometChat V5 Android UI Kit** was a single Java module (`com.cometchat:chatuikit-kotlin-android`) that shipped all UI components, ViewModels, and resources in one artifact under the `com.cometchat.chatuikit` package.

**V6** splits the UI Kit into three modules built entirely in Kotlin:

| Module                 | Artifact                                  | Description                                                                         |
| :--------------------- | :---------------------------------------- | :---------------------------------------------------------------------------------- |
| **Core**               | `com.cometchat:chatuikit-core`            | Shared ViewModels, Repositories, DataSources, and events — used by both UI modules. |
| **Kotlin (XML Views)** | `com.cometchat:chatuikit-kotlin-android`  | Traditional XML-based Views for Activities and Fragments.                           |
| **Jetpack Compose**    | `com.cometchat:chatuikit-compose-android` | Declarative Compose components.                                                     |

Choose the UI module that fits your project — both depend on `chatuikit-core` automatically.

<Frame>
  <img />
</Frame>

## Key Migration Changes

The following table summarizes the most impactful changes when migrating from V5 to V6:

| Area                      | V5                                                                    | V6                                                                                                                              |
| :------------------------ | :-------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| **Language**              | Java                                                                  | Kotlin                                                                                                                          |
| **Modules**               | Single `com.cometchat:chatuikit-kotlin-android`                       | `com.cometchat:chatuikit-kotlin-android` (XML) or `com.cometchat:chatuikit-compose-android` (Compose) + shared `chatuikit-core` |
| **Import path**           | `com.cometchat.chatuikit.*`                                           | `com.cometchat.uikit.kotlin.presentation.*` or `com.cometchat.uikit.compose.presentation.*`                                     |
| **CometChatUIKit import** | `com.cometchat.chatuikit.shared.cometchatuikit.CometChatUIKit`        | `com.cometchat.uikit.core.CometChatUIKit`                                                                                       |
| **UIKitSettings import**  | `com.cometchat.chatuikit.shared.cometchatuikit.UIKitSettings`         | `com.cometchat.uikit.core.UIKitSettings`                                                                                        |
| **State management**      | `LiveData`                                                            | `StateFlow` / Kotlin coroutines                                                                                                 |
| **Architecture**          | View + ViewModel + Adapter (2-layer)                                  | View → ViewModel → Repository → DataSource (4-layer Clean Architecture)                                                         |
| **Conversation list**     | `CometChatConversations`                                              | `CometChatConversations`                                                                                                        |
| **Thread header**         | `CometChatThreadedMessagesHeader`                                     | `CometChatThreadHeader`                                                                                                         |
| **Events**                | `CometChat*Events.addListener()` / `removeListener()`                 | `CometChatEvents` singleton with `SharedFlow` — collect in a coroutine scope                                                    |
| **Theming**               | `Palette` + `Typography` objects                                      | XML theme attributes extending `CometChatTheme.DayNight` (Kotlin XML) or `CometChatTheme {}` composable (Compose)               |
| **Styling**               | `setStyle(ComponentStyle)` methods with style objects                 | XML `@StyleRes` theme attributes (Kotlin XML) or style data classes with `.default().copy()` (Compose)                          |
| **View slots**            | `ConversationsViewHolderListener` with `createView`/`bindView` (Java) | Same pattern in Kotlin XML or `@Composable` lambdas in Compose                                                                  |
| **ViewModel access**      | `getViewModel()` returns Java ViewModel with `LiveData`               | `getViewModel()` / `setViewModel()` with Kotlin ViewModel using `StateFlow`                                                     |
| **List operations**       | Direct list manipulation via adapter                                  | `ListOperations<T>` interface with `addItem`, `removeItem`, `updateItem`, `moveItemToTop`, `batch {}`                           |
| **Repository**            | Not exposed                                                           | Swappable via Factory pattern — implement interface, inject via `*ViewModelFactory`                                             |
| **Min SDK**               | 24                                                                    | 28                                                                                                                              |

## Dependency Changes

### V5 (before)

```groovy title="build.gradle" theme={null}
dependencies {
    implementation 'com.cometchat:chatuikit-kotlin-android:5.x.x'
}
```

### V6 — Kotlin XML Views (after)

```groovy title="build.gradle" theme={null}
dependencies {
    implementation 'com.cometchat:chatuikit-kotlin-android:6.x.x'
    // chatuikit-core is pulled in transitively
}
```

### V6 — Jetpack Compose (after)

```groovy title="build.gradle" theme={null}
dependencies {
    implementation 'com.cometchat:chatuikit-compose-android:6.x.x'
    // chatuikit-core is pulled in transitively
}
```

<Note>
  V6 raises the minimum SDK from **24** to **28**. Update `minSdk` in your `build.gradle` accordingly.
</Note>

## Component Renames

Most components keep the same class name but move to a new package. The following were also renamed:

| V5 Name                           | V6 Name                  |
| :-------------------------------- | :----------------------- |
| `CometChatConversations`          | `CometChatConversations` |
| `CometChatThreadedMessagesHeader` | `CometChatThreadHeader`  |

All other components (`CometChatUsers`, `CometChatGroups`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatIncomingCall`, `CometChatOutgoingCall`, `CometChatCallButtons`, `CometChatCallLogs`, `CometChatGroupMembers`) retain their names but live under the new V6 package paths.

## Import Path Changes

### CometChatUIKit & UIKitSettings

```java title="V5 (Java)" theme={null}
import com.cometchat.chatuikit.shared.cometchatuikit.CometChatUIKit;
import com.cometchat.chatuikit.shared.cometchatuikit.UIKitSettings;
```

```kotlin title="V6 (Kotlin)" theme={null}
import com.cometchat.uikit.core.CometChatUIKit
import com.cometchat.uikit.core.UIKitSettings
```

### UI Components

```java title="V5 (Java)" theme={null}
import com.cometchat.chatuikit.conversations.CometChatConversations;
import com.cometchat.chatuikit.users.CometChatUsers;
import com.cometchat.chatuikit.groups.CometChatGroups;
import com.cometchat.chatuikit.messageheader.CometChatMessageHeader;
import com.cometchat.chatuikit.messagelist.CometChatMessageList;
import com.cometchat.chatuikit.messagecomposer.CometChatMessageComposer;
```

```kotlin title="V6 — Kotlin XML" theme={null}
import com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations
import com.cometchat.uikit.kotlin.presentation.users.ui.CometChatUsers
import com.cometchat.uikit.kotlin.presentation.groups.ui.CometChatGroups
import com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader
import com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
import com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
```

```kotlin title="V6 — Jetpack Compose" theme={null}
import com.cometchat.uikit.compose.presentation.conversations.ui.CometChatConversations
import com.cometchat.uikit.compose.presentation.users.ui.CometChatUsers
import com.cometchat.uikit.compose.presentation.groups.ui.CometChatGroups
import com.cometchat.uikit.compose.presentation.messageheader.ui.CometChatMessageHeader
import com.cometchat.uikit.compose.presentation.messagelist.ui.CometChatMessageList
import com.cometchat.uikit.compose.presentation.messagecomposer.ui.CometChatMessageComposer
```

## Events Migration

In **V5**, events used the `addListener` / `removeListener` pattern with unique string IDs:

```java title="V5 (Java)" theme={null}
CometChatMessageEvents.addListener("unique-id", new CometChatMessageEvents() {
    @Override
    public void onMessageSent(BaseMessage message) {
        // Handle message sent
    }
});
// Cleanup
CometChatMessageEvents.removeListener("unique-id");
```

In **V6**, events use the `CometChatEvents` singleton with Kotlin `SharedFlow`. Collect in a coroutine scope:

```kotlin title="V6 (Kotlin)" theme={null}
lifecycleScope.launch {
    CometChatEvents.messageEvents.collect { event ->
        when (event) {
            is MessageEvent.Sent -> { /* Handle message sent */ }
            is MessageEvent.Edited -> { /* Handle message edited */ }
            is MessageEvent.Deleted -> { /* Handle message deleted */ }
        }
    }
}
// No manual cleanup needed — lifecycleScope auto-cancels
```

## State Management Migration

### V5 — LiveData observers (Java)

```java title="V5" theme={null}
conversationsViewModel.getConversationList().observe(this, new Observer<List<Conversation>>() {
    @Override
    public void onChanged(List<Conversation> conversations) {
        // Update UI with conversations
    }
});
```

### V6 — StateFlow collectors (Kotlin)

```kotlin title="V6" theme={null}
lifecycleScope.launch {
    conversationsViewModel.uiState.collect { state ->
        when (state) {
            is UIState.Loading -> { /* Show loading */ }
            is UIState.Success -> { /* Update UI with state.data */ }
            is UIState.Error -> { /* Show error */ }
        }
    }
}
```

## Styling Migration

### V5 — Style objects (Java)

```java title="V5" theme={null}
ConversationsStyle style = new ConversationsStyle();
style.setBackground(Color.WHITE);
style.setTitleColor(Color.BLACK);
style.setBorderWidth(1);
style.setBorderColor(Color.GRAY);
cometChatConversations.setStyle(style);
```

### V6 — Kotlin XML: Theme attributes in `themes.xml`

```xml title="V6 — themes.xml" theme={null}
<resources>
    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatPrimaryColor">#F76808</item>
        <item name="cometchatBackgroundColor">#FFFFFF</item>
        <item name="cometchatTextPrimaryColor">#141414</item>
        <item name="android:fontFamily">@font/your_custom_font</item>
    </style>

    <!-- Override a specific component style -->
    <style name="CustomConversationsStyle" parent="CometChatConversations">
        <item name="cometchatSeparatorColor">#E0E0E0</item>
        <item name="cometchatItemBackgroundColor">#FAFAFA</item>
    </style>
</resources>
```

### V6 — Jetpack Compose: Style data classes

```kotlin title="V6 — Compose" theme={null}
CometChatConversations(
    style = CometChatConversationsStyle.default().copy(
        backgroundColor = Color.White,
        titleColor = Color.Black,
        separatorColor = Color.LightGray
    )
)
```

## Component-by-Component Migration

### Conversations

```java title="V5 — CometChatConversations (Java)" theme={null}
CometChatConversations conversations = findViewById(R.id.conversations);
conversations.setOnItemClick(new OnItemClick<Conversation>() {
    @Override
    public void onItemClick(Conversation conversation, int position) {
        // Handle click
    }
});
```

```kotlin title="V6 — CometChatConversations (Kotlin)" theme={null}
val conversations = findViewById<CometChatConversations>(R.id.conversations)
conversations.setOnItemClick { conversation ->
    // Handle click
}
```

### Users

```java title="V5 — CometChatUsers (Java)" theme={null}
CometChatUsers users = findViewById(R.id.users);
users.setOnItemClick(new OnItemClick<User>() {
    @Override
    public void onItemClick(User user, int position) {
        // Handle click
    }
});
```

```kotlin title="V6 — CometChatUsers (Kotlin)" theme={null}
val users = findViewById<CometChatUsers>(R.id.users)
users.setOnItemClick { user ->
    // Handle click
}
```

### Groups

```java title="V5 — CometChatGroups (Java)" theme={null}
CometChatGroups groups = findViewById(R.id.groups);
groups.setOnItemClick(new OnItemClick<Group>() {
    @Override
    public void onItemClick(Group group, int position) {
        // Handle click
    }
});
```

```kotlin title="V6 — CometChatGroups (Kotlin)" theme={null}
val groups = findViewById<CometChatGroups>(R.id.groups)
groups.setOnItemClick { group ->
    // Handle click
}
```

### Message Header

```java title="V5 — CometChatMessageHeader (Java)" theme={null}
CometChatMessageHeader header = findViewById(R.id.messageHeader);
header.setOnBackButtonPressed(new OnBackPress() {
    @Override
    public void onBack() {
        // Handle back
    }
});
```

```kotlin title="V6 — CometChatMessageHeader (Kotlin)" theme={null}
val header = findViewById<CometChatMessageHeader>(R.id.messageHeader)
header.setOnBackPress {
    // Handle back
}
```

### Message List

```java title="V5 — CometChatMessageList (Java)" theme={null}
CometChatMessageList messageList = findViewById(R.id.messageList);
messageList.setOnThreadRepliesClick(new OnThreadRepliesClick() {
    @Override
    public void onThreadRepliesClick(Context context, BaseMessage message, CometChatMessageTemplate template) {
        // Handle thread click
    }
});
```

```kotlin title="V6 — CometChatMessageList (Kotlin)" theme={null}
val messageList = findViewById<CometChatMessageList>(R.id.messageList)
messageList.setOnThreadRepliesClick { context, message, template ->
    // Handle thread click
}
```

### Message Composer

```java title="V5 — CometChatMessageComposer (Java)" theme={null}
CometChatMessageComposer composer = findViewById(R.id.messageComposer);
composer.setOnSendButtonClick(new OnSendButtonClick() {
    @Override
    public void onSendButtonClick(Context context, BaseMessage message) {
        // Handle send
    }
});
```

```kotlin title="V6 — CometChatMessageComposer (Kotlin)" theme={null}
val composer = findViewById<CometChatMessageComposer>(R.id.messageComposer)
composer.setOnSendButtonClick { context, message ->
    // Handle send
}
```

### Call Components

Call components (`CometChatIncomingCall`, `CometChatOutgoingCall`, `CometChatCallButtons`, `CometChatCallLogs`) keep the same class names in V6. Update the import paths:

```java title="V5 (Java)" theme={null}
import com.cometchat.chatuikit.calls.incoming.CometChatIncomingCall;
import com.cometchat.chatuikit.calls.outgoing.CometChatOutgoingCall;
import com.cometchat.chatuikit.calls.callbuttons.CometChatCallButtons;
import com.cometchat.chatuikit.calls.calllogs.CometChatCallLogs;
```

```kotlin title="V6 — Kotlin XML" theme={null}
import com.cometchat.uikit.kotlin.presentation.incomingcall.CometChatIncomingCall
import com.cometchat.uikit.kotlin.presentation.outgoingcall.CometChatOutgoingCall
import com.cometchat.uikit.kotlin.presentation.callbuttons.CometChatCallButtons
import com.cometchat.uikit.kotlin.presentation.calllogs.ui.CometChatCallLogs
```

## Architecture Changes

V6 introduces a **4-layer Clean Architecture** that replaces V5's 2-layer View + ViewModel pattern:

```
View → ViewModel → Repository → DataSource
```

### ViewModel Access

```java title="V5 (Java)" theme={null}
// V5 — Java ViewModel with LiveData
ConversationsViewModel viewModel = cometChatConversations.getViewModel();
viewModel.getConversationList().observe(this, conversations -> {
    // React to data
});
```

```kotlin title="V6 (Kotlin)" theme={null}
// V6 — Kotlin ViewModel with StateFlow
val viewModel = conversations.getViewModel()
lifecycleScope.launch {
    viewModel.uiState.collect { state ->
        // React to data
    }
}

// You can also inject a custom ViewModel
conversations.setViewModel(myCustomViewModel)
```

### List Operations

V5 required direct adapter manipulation. V6 provides a `ListOperations<T>` interface:

```kotlin title="V6 — ListOperations" theme={null}
val viewModel = conversations.getViewModel()

// Single operations
viewModel.addItem(conversation)
viewModel.removeItem(conversation)
viewModel.updateItem(conversation)
viewModel.moveItemToTop(conversation)

// Batch operations
viewModel.batch {
    addItem(conversation1)
    updateItem(conversation2)
    removeItem(conversation3)
}
```

### Custom Repository

V6 exposes the repository layer, allowing you to swap data sources:

```kotlin title="V6 — Custom Repository" theme={null}
// Implement the repository interface
class MyConversationRepository : ConversationsRepository {
    override suspend fun fetchConversations(): List<Conversation> {
        // Your custom data source
    }
}

// Inject via ViewModelFactory
val factory = CometChatConversationsViewModelFactory(
    repository = MyConversationRepository()
)
conversations.setViewModelFactory(factory)
```

***

## Property Changes

Below is a detailed reference of new, updated, and removed properties across all UI Kit components in the V5-to-V6 migration.

### Conversations (now CometChatConversations)

#### New Properties

| Name                               | Type                                                                     | Description                                               |
| ---------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
| dateTimeFormatter                  | DateTimeFormatterCallback                                                | Callback for custom date/time formatting in conversations |
| toolbarVisibility                  | int                                                                      | Controls visibility of the toolbar in conversations view  |
| deleteConversationOptionVisibility | int                                                                      | Controls visibility of delete conversation option         |
| backIconVisibility                 | int                                                                      | Controls visibility of back icon in toolbar               |
| userStatusVisibility               | int                                                                      | Controls visibility of user status indicators             |
| groupTypeVisibility                | int                                                                      | Controls visibility of group type indicators              |
| receiptsVisibility                 | int                                                                      | Controls visibility of read receipts                      |
| errorStateVisibility               | int                                                                      | Controls visibility of error state view                   |
| loadingStateVisibility             | int                                                                      | Controls visibility of loading state view                 |
| emptyStateVisibility               | int                                                                      | Controls visibility of empty state view                   |
| separatorHeight                    | @Dimension int                                                           | Height of separator between conversation items            |
| separatorColor                     | @ColorInt int                                                            | Color of separator between conversation items             |
| separatorVisibility                | int                                                                      | Controls visibility of separator                          |
| deleteOptionIcon                   | Drawable                                                                 | Icon for delete option in popup menu                      |
| deleteOptionIconTint               | @ColorInt int                                                            | Tint color for delete option icon                         |
| deleteOptionTextColor              | @ColorInt int                                                            | Text color for delete option                              |
| deleteOptionTextAppearance         | @StyleRes int                                                            | Text appearance for delete option                         |
| discardSelectionIcon               | Drawable                                                                 | Icon for discarding selection                             |
| discardSelectionIconTint           | @ColorInt int                                                            | Tint color for discard selection icon                     |
| submitSelectionIcon                | Drawable                                                                 | Icon for submitting selection                             |
| submitSelectionIconTint            | @ColorInt int                                                            | Tint color for submit selection icon                      |
| checkBoxStrokeWidth                | @Dimension int                                                           | Stroke width for selection checkboxes                     |
| checkBoxCornerRadius               | @Dimension int                                                           | Corner radius for selection checkboxes                    |
| checkBoxStrokeColor                | @ColorInt int                                                            | Stroke color for selection checkboxes                     |
| checkBoxBackgroundColor            | @ColorInt int                                                            | Background color for selection checkboxes                 |
| checkBoxCheckedBackgroundColor     | @ColorInt int                                                            | Background color for checked checkboxes                   |
| checkBoxSelectIcon                 | Drawable                                                                 | Icon for selected checkboxes                              |
| checkBoxSelectIconTint             | @ColorInt int                                                            | Tint color for checkbox select icon                       |
| itemSelectedBackgroundColor        | @ColorInt int                                                            | Background color for selected items                       |
| itemBackgroundColor                | @ColorInt int                                                            | Background color for conversation items                   |
| optionListStyle                    | @StyleRes int                                                            | Style for popup menu options                              |
| mentionsStyle                      | @StyleRes int                                                            | Style for mentions in conversations                       |
| typingIndicatorStyle               | @StyleRes int                                                            | Style for typing indicators                               |
| receiptStyle                       | @StyleRes int                                                            | Style for message receipts                                |
| badgeStyle                         | @StyleRes int                                                            | Style for conversation badges                             |
| dateStyle                          | @StyleRes int                                                            | Style for conversation dates                              |
| statusIndicatorStyle               | @StyleRes int                                                            | Style for status indicators                               |
| avatarStyle                        | @StyleRes int                                                            | Style for conversation avatars                            |
| emptyView                          | @LayoutRes int                                                           | Layout resource for empty state                           |
| errorView                          | @LayoutRes int                                                           | Layout resource for error state                           |
| loadingView                        | @LayoutRes int                                                           | Layout resource for loading state                         |
| additionParameter                  | AdditionParameter                                                        | Additional parameters for conversations                   |
| onBackPress                        | OnBackPress                                                              | Callback for back button press                            |
| addOptions                         | Function2\< Context, Conversation, List\< CometChatPopupMenu.MenuItem >> | Function to add options to popup menu                     |
| options                            | Function2\< Context, Conversation, List\< CometChatPopupMenu.MenuItem >> | Function to replace popup menu options                    |
| overflowMenu                       | View                                                                     | Custom overflow menu view                                 |
| onLoad                             | OnLoad\< Conversation >                                                  | Callback when conversations are loaded                    |
| onEmpty                            | OnEmpty                                                                  | Callback when conversation list is empty                  |
| onSelection                        | OnSelection\< Conversation >                                             | Callback for conversation selection                       |
| onItemClick                        | OnItemClick\< Conversation >                                             | Callback for conversation item clicks                     |
| onItemLongClick                    | OnItemLongClick\< Conversation >                                         | Callback for conversation item long clicks                |

#### Renamed Properties

| V5 Name              | V6 Name              | Type   | Description                                |
| -------------------- | -------------------- | ------ | ------------------------------------------ |
| setItemClickListener | setOnItemClick       | Method | Sets click listener for conversation items |
| setOnSelection       | setOnSelect          | Method | Sets selection listener for conversations  |
| setSubtitle          | setSubtitleView      | Method | Sets custom subtitle view                  |
| setTailView          | setTrailingView      | Method | Sets custom trailing view                  |
| setListItemView      | setItemView          | Method | Sets custom item view                      |
| setDatePattern       | setDateTimeFormatter | Method | Sets date formatting for conversations     |

#### Removed Properties

| Name                         | Type                       | Description                                             |
| ---------------------------- | -------------------------- | ------------------------------------------------------- |
| hideError                    | boolean                    | Flag to hide error messages                             |
| errorText                    | String                     | Custom error message text                               |
| errorStateTextAppearance     | int                        | Text appearance for error state                         |
| errorMessageColor            | int                        | Color for error messages                                |
| palette                      | Palette                    | Color palette instance                                  |
| typography                   | Typography                 | Typography instance                                     |
| swipeHelper                  | RecyclerViewSwipeListener  | Swipe gesture helper                                    |
| progressDialog               | ProgressDialog             | Progress dialog for operations                          |
| conversationTemp             | Conversation               | Temporary conversation reference                        |
| loadingIcon                  | ImageView                  | Loading icon view                                       |
| disableMentions              | boolean                    | Flag to disable mentions                                |
| cometChatMentionsFormatter   | CometChatMentionsFormatter | Mentions formatter instance                             |
| setStyle(ConversationsStyle) | Method                     | Sets conversation style using ConversationsStyle object |
| emptyStateText               | Method                     | Sets empty state text                                   |
| emptyStateTextColor          | Method                     | Sets empty state text color                             |
| emptyStateTextFont           | Method                     | Sets empty state text font                              |
| emptyStateTextAppearance     | Method                     | Sets empty state text appearance                        |
| errorStateTextAppearance     | Method                     | Sets error state text appearance                        |
| errorStateTextColor          | Method                     | Sets error state text color                             |
| errorStateText               | Method                     | Sets error state text                                   |
| setEmptyStateView            | Method                     | Sets empty state view                                   |
| setErrorStateView            | Method                     | Sets error state view                                   |
| setLoadingStateView          | Method                     | Sets loading state view                                 |
| setLoadingIconTintColor      | Method                     | Sets loading icon tint                                  |
| disableUsersPresence         | Method                     | Disables user presence                                  |
| disableReceipt               | Method                     | Disables receipts                                       |
| hideReceipt                  | Method                     | Hides receipts                                          |
| disableTyping                | Method                     | Disables typing indicators                              |
| setProtectedGroupIcon        | Method                     | Sets protected group icon                               |
| setPrivateGroupIcon          | Method                     | Sets private group icon                                 |
| setReadIcon                  | Method                     | Sets read status icon                                   |
| setDeliveredIcon             | Method                     | Sets delivered status icon                              |
| setSentIcon                  | Method                     | Sets sent status icon                                   |
| hideSeparator                | Method                     | Hides item separators                                   |

### Users

#### New Properties

| Name                                 | Type                                                             | Description                                      |
| ------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------ |
| toolbarVisibility                    | int                                                              | Controls visibility of the toolbar in users view |
| loadingStateVisibility               | int                                                              | Controls visibility of loading state view        |
| searchBoxVisibility                  | int                                                              | Controls visibility of search box                |
| backIconVisibility                   | int                                                              | Controls visibility of back icon in toolbar      |
| stickyHeaderVisibility               | int                                                              | Controls visibility of sticky header             |
| emptyStateVisibility                 | int                                                              | Controls visibility of empty state view          |
| errorStateVisibility                 | int                                                              | Controls visibility of error state view          |
| separatorVisibility                  | int                                                              | Controls visibility of separator between items   |
| titleVisibility                      | int                                                              | Controls visibility of title                     |
| userStatusVisibility                 | int                                                              | Controls visibility of user status indicators    |
| showShimmer                          | boolean                                                          | Flag to control shimmer loading animation        |
| isUserListEmpty                      | boolean                                                          | Flag indicating if user list is empty            |
| isFurtherSelectionEnabled            | boolean                                                          | Flag to control further selection capability     |
| searchPlaceholderText                | String                                                           | Placeholder text for search input                |
| customLoadingView                    | View                                                             | Custom view for loading state                    |
| overflowMenu                         | View                                                             | Custom overflow menu view                        |
| onLoad                               | OnLoad\< User >                                                  | Callback when users are loaded                   |
| onEmpty                              | OnEmpty                                                          | Callback when user list is empty                 |
| onBackPress                          | OnBackPress                                                      | Callback for back button press                   |
| backgroundColor                      | @ColorInt int                                                    | Background color for the view                    |
| titleTextColor                       | @ColorInt int                                                    | Text color for title                             |
| titleTextAppearance                  | @StyleRes int                                                    | Text appearance for title                        |
| strokeWidth                          | @Dimension int                                                   | Stroke width for card border                     |
| strokeColor                          | @ColorInt int                                                    | Stroke color for card border                     |
| cornerRadius                         | @Dimension int                                                   | Corner radius for card                           |
| backIcon                             | Drawable                                                         | Back icon drawable                               |
| backIconTint                         | @ColorInt int                                                    | Tint color for back icon                         |
| separatorColor                       | @ColorInt int                                                    | Color of separator between items                 |
| discardSelectionIcon                 | Drawable                                                         | Icon for discarding selection                    |
| discardSelectionIconTint             | @ColorInt int                                                    | Tint color for discard selection icon            |
| submitSelectionIcon                  | Drawable                                                         | Icon for submitting selection                    |
| submitSelectionIconTint              | @ColorInt int                                                    | Tint color for submit selection icon             |
| searchInputEndIcon                   | Drawable                                                         | End icon for search input                        |
| searchInputEndIconTint               | @ColorInt int                                                    | Tint color for search input end icon             |
| searchInputStrokeWidth               | @Dimension int                                                   | Stroke width for search input                    |
| searchInputStrokeColor               | @ColorInt int                                                    | Stroke color for search input                    |
| searchInputCornerRadius              | @Dimension int                                                   | Corner radius for search input                   |
| searchInputBackgroundColor           | @ColorInt int                                                    | Background color for search input                |
| searchInputTextAppearance            | @StyleRes int                                                    | Text appearance for search input                 |
| searchInputTextColor                 | @ColorInt int                                                    | Text color for search input                      |
| searchInputPlaceHolderTextAppearance | @StyleRes int                                                    | Placeholder text appearance for search input     |
| searchInputPlaceHolderTextColor      | @ColorInt int                                                    | Placeholder text color for search input          |
| searchInputIconTint                  | @ColorInt int                                                    | Tint color for search input icon                 |
| searchInputIcon                      | Drawable                                                         | Icon for search input                            |
| stickyTitleColor                     | @ColorInt int                                                    | Color for sticky title                           |
| stickyTitleAppearance                | @StyleRes int                                                    | Text appearance for sticky title                 |
| stickyTitleBackgroundColor           | @ColorInt int                                                    | Background color for sticky title                |
| avatar                               | @StyleRes int                                                    | Style resource for avatar                        |
| itemTitleTextAppearance              | @StyleRes int                                                    | Text appearance for item title                   |
| itemTitleTextColor                   | @ColorInt int                                                    | Text color for item title                        |
| itemBackgroundColor                  | @ColorInt int                                                    | Background color for items                       |
| statusIndicatorStyle                 | @StyleRes int                                                    | Style for status indicators                      |
| itemSelectedBackgroundColor          | @ColorInt int                                                    | Background color for selected items              |
| checkBoxStrokeWidth                  | @Dimension int                                                   | Stroke width for selection checkboxes            |
| checkBoxCornerRadius                 | @Dimension int                                                   | Corner radius for selection checkboxes           |
| checkBoxStrokeColor                  | @ColorInt int                                                    | Stroke color for selection checkboxes            |
| checkBoxBackgroundColor              | @ColorInt int                                                    | Background color for selection checkboxes        |
| checkBoxCheckedBackgroundColor       | @ColorInt int                                                    | Background color for checked checkboxes          |
| checkBoxSelectIconTint               | @ColorInt int                                                    | Tint color for checkbox select icon              |
| checkBoxSelectIcon                   | Drawable                                                         | Icon for selected checkboxes                     |
| emptyStateTextAppearance             | @StyleRes int                                                    | Text appearance for empty state                  |
| emptyStateTextColor                  | @ColorInt int                                                    | Text color for empty state                       |
| emptyStateSubTitleTextAppearance     | @StyleRes int                                                    | Subtitle text appearance for empty state         |
| emptyStateSubtitleTextColor          | @ColorInt int                                                    | Subtitle text color for empty state              |
| errorStateTextAppearance             | @StyleRes int                                                    | Text appearance for error state                  |
| errorStateTextColor                  | @ColorInt int                                                    | Text color for error state                       |
| errorStateSubtitleTextAppearance     | @StyleRes int                                                    | Subtitle text appearance for error state         |
| errorStateSubtitleColor              | @ColorInt int                                                    | Subtitle text color for error state              |
| retryButtonTextColor                 | @ColorInt int                                                    | Text color for retry button                      |
| retryButtonTextAppearance            | @StyleRes int                                                    | Text appearance for retry button                 |
| retryButtonBackgroundColor           | @ColorInt int                                                    | Background color for retry button                |
| retryButtonStrokeColor               | @ColorInt int                                                    | Stroke color for retry button                    |
| retryButtonStrokeWidth               | @Dimension int                                                   | Stroke width for retry button                    |
| retryButtonCornerRadius              | @Dimension int                                                   | Corner radius for retry button                   |
| emptyViewId                          | @LayoutRes int                                                   | Layout resource for empty view                   |
| errorViewId                          | @LayoutRes int                                                   | Layout resource for error view                   |
| loadingViewId                        | @LayoutRes int                                                   | Layout resource for loading view                 |
| submitSelectionIconVisibility        | int                                                              | Controls visibility of submit selection icon     |
| addOptions                           | Function2\< Context, User, List\< CometChatPopupMenu.MenuItem >> | Function to add options to popup menu            |
| options                              | Function2\< Context, User, List\< CometChatPopupMenu.MenuItem >> | Function to replace popup menu options           |
| cometchatPopUpMenu                   | CometChatPopupMenu                                               | Popup menu for user actions                      |

#### Renamed Properties

| V5 Name                 | V6 Name         | Type   | Description                                        |
| ----------------------- | --------------- | ------ | -------------------------------------------------- |
| setItemClickListener    | setOnItemClick  | Method | Sets click listener for user items                 |
| setOnSelection          | setOnSelect     | Method | Sets selection listener for users                  |
| setSubtitle             | setSubtitleView | Method | Sets custom subtitle view                          |
| setTail                 | setTailView     | Method | Sets custom tail view (renamed to setTrailingView) |
| setListItemView         | setItemView     | Method | Sets custom item view                              |
| getConversationsAdapter | getUsersAdapter | Method | Gets the users adapter                             |

#### Removed Properties

| Name                                                | Type                      | Description                                                |
| --------------------------------------------------- | ------------------------- | ---------------------------------------------------------- |
| hideError                                           | boolean                   | Flag to hide error messages                                |
| emptyStateText                                      | TextView                  | TextView for empty state message                           |
| errorStateTextAppearance                            | int                       | Text appearance for error state                            |
| errorMessageColor                                   | int                       | Color for error messages                                   |
| errorText                                           | String                    | Custom error message text                                  |
| palette                                             | Palette                   | Color palette instance                                     |
| typography                                          | Typography                | Typography instance                                        |
| swipeHelper                                         | RecyclerViewSwipeListener | Swipe gesture helper                                       |
| loadingIcon                                         | ImageView                 | Loading icon view                                          |
| submitIcon                                          | @DrawableRes int          | Submit icon resource                                       |
| icon                                                | ImageView                 | Icon view for submit                                       |
| setStyle(UsersStyle)                                | Method                    | Sets users style using UsersStyle object                   |
| emptyStateText(String)                              | Method                    | Sets empty state text                                      |
| emptyStateTextColor(int)                            | Method                    | Sets empty state text color                                |
| emptyStateTextFont(String)                          | Method                    | Sets empty state text font                                 |
| emptyStateTextAppearance(int)                       | Method                    | Sets empty state text appearance                           |
| errorStateTextAppearance(int)                       | Method                    | Sets error state text appearance                           |
| errorStateTextColor(int)                            | Method                    | Sets error state text color                                |
| errorStateText(String)                              | Method                    | Sets error state text                                      |
| setEmptyStateView(@LayoutRes int)                   | Method                    | Sets empty state view layout                               |
| setLoadingIconTintColor(@ColorInt int)              | Method                    | Sets loading icon tint color                               |
| setErrorStateView(@LayoutRes int)                   | Method                    | Sets error state view layout                               |
| setLoadingStateView(@LayoutRes int)                 | Method                    | Sets loading state view layout                             |
| setBackground(int\[], GradientDrawable.Orientation) | Method                    | Sets gradient background                                   |
| disableUsersPresence(boolean)                       | Method                    | Disables user presence indicators                          |
| setSubmitIcon(@DrawableRes int)                     | Method                    | Sets submit icon                                           |
| setSelectionIcon(@DrawableRes int)                  | Method                    | Sets selection icon                                        |
| setFurtherSelectionEnabled(boolean)                 | Method                    | Sets further selection capability                          |
| hideError(boolean)                                  | Method                    | Hides error messages                                       |
| hideSeparator(boolean)                              | Method                    | Hides separators (replaced with setStickyHeaderVisibility) |

### Groups

#### Renamed Properties

| V5 Name              | V6 Name         | Type   | Description                                            |
| -------------------- | --------------- | ------ | ------------------------------------------------------ |
| setItemClickListener | setOnItemClick  | Method | Sets click listener for group items                    |
| setOnSelection       | setOnSelection  | Method | Sets selection listener for groups (signature changed) |
| setSubtitle          | setSubtitleView | Method | Sets custom subtitle view                              |
| setTail              | setTailView     | Method | Sets custom tail view (renamed to setTrailingView)     |
| setListItemView      | setItemView     | Method | Sets custom item view                                  |
| setPasswordGroupIcon | N/A             | Method | Method for password group icon (removed)               |

#### Removed Properties

| Name                   | Type                      | Description                                           |
| ---------------------- | ------------------------- | ----------------------------------------------------- |
| palette                | Palette                   | Color palette instance                                |
| typography             | Typography                | Typography instance                                   |
| swipeHelper            | RecyclerViewSwipeListener | Swipe gesture helper                                  |
| setStyle(GroupsStyle)  | Method                    | Sets groups style using GroupsStyle object            |
| setOverflowMenuOptions | Method                    | Sets overflow menu options (replaced with setOptions) |

### GroupMembers

#### Renamed Properties

| V5 Name              | V6 Name                 | Type   | Description                                |
| -------------------- | ----------------------- | ------ | ------------------------------------------ |
| setItemClickListener | setOnItemClick          | Method | Sets click listener for group member items |
| setTailView          | setTrailingView         | Method | Sets custom trailing view                  |
| setListItemView      | setItemView             | Method | Sets custom item view                      |
| disableUsersPresence | setUserStatusVisibility | Method | Controls user presence visibility          |

#### Removed Properties

| Name                        | Type                      | Description                                             |
| --------------------------- | ------------------------- | ------------------------------------------------------- |
| palette                     | Palette                   | Color palette instance                                  |
| typography                  | Typography                | Typography instance                                     |
| swipeHelper                 | RecyclerViewSwipeListener | Swipe gesture helper                                    |
| setStyle(GroupMembersStyle) | Method                    | Sets group members style using GroupMembersStyle object |

### MessageHeader

#### Renamed Properties

| V5 Name                | V6 Name                 | Type                                     | Description                                  |
| ---------------------- | ----------------------- | ---------------------------------------- | -------------------------------------------- |
| subtitle               | subtitleView            | Function3\< Context, User, Group, View > | Function to create custom subtitle view      |
| menu                   | trailingView            | Function3\< Context, User, Group, View > | Function to create custom menu/trailing view |
| disableUsersPresence   | setUserStatusVisibility | Method                                   | Controls user presence visibility            |
| setOnBackButtonPressed | setOnBackPress          | Method                                   | Sets back button callback                    |

#### Removed Properties

| Name                            | Type       | Description                                       |
| ------------------------------- | ---------- | ------------------------------------------------- |
| palette                         | Palette    | Color palette instance                            |
| typography                      | Typography | Typography instance                               |
| disableTyping                   | boolean    | Flag to disable typing indicator                  |
| setStyle(MessageHeaderStyle)    | Method     | Sets header style using MessageHeaderStyle object |
| setAvatarStyle(AvatarStyle)     | Method     | Sets avatar style using AvatarStyle object        |
| setListItemStyle(ListItemStyle) | Method     | Sets list item style using ListItemStyle object   |

### MessageList

#### Renamed Properties

| V5 Name                 | V6 Name                 | Type   | Description                     |
| ----------------------- | ----------------------- | ------ | ------------------------------- |
| setAlignment            | setMessageAlignment     | Method | Sets alignment of messages      |
| showAvatar              | setAvatarVisibility     | Method | Controls avatar visibility      |
| hideReceipt             | setReceiptsVisibility   | Method | Controls receipt visibility     |
| setDatePattern          | setTimeFormat           | Method | Sets time format for messages   |
| setDateSeparatorPattern | setDateFormat           | Method | Sets date format for separators |
| hideError               | setErrorStateVisibility | Method | Controls error state visibility |

#### Removed Properties

| Name                        | Type                 | Description                                |
| --------------------------- | -------------------- | ------------------------------------------ |
| palette                     | Palette              | Color palette instance                     |
| typography                  | Typography           | Typography instance                        |
| cometChatActionSheet        | CometChatActionSheet | Action sheet component (replaced)          |
| setStyle(MessageListStyle)  | Method               | Sets style using MessageListStyle object   |
| setAvatarStyle(AvatarStyle) | Method               | Sets avatar style using AvatarStyle object |
| disableReactions(boolean)   | Method               | Disables reactions (removed)               |

### MessageComposer

#### Renamed Properties

| V5 Name                          | V6 Name                           | Type   | Description                                     |
| -------------------------------- | --------------------------------- | ------ | ----------------------------------------------- |
| setParentMessageId(int)          | setParentMessageId(long)          | Method | Sets parent message ID (parameter type changed) |
| setText(String)                  | setInitialComposerText(String)    | Method | Sets initial composer text                      |
| setVoiceRecordingVisibility(int) | setVoiceNoteButtonVisibility(int) | Method | Sets voice note button visibility               |

#### Removed Properties

| Name                           | Type             | Description                                  |
| ------------------------------ | ---------------- | -------------------------------------------- |
| cometChatTheme                 | CometChatTheme   | Theme instance                               |
| liveReactionIcon               | @DrawableRes int | Live reaction icon resource                  |
| hideLiveReaction               | boolean          | Flag to hide live reaction                   |
| setStyle(MessageComposerStyle) | Method           | Sets style using MessageComposerStyle object |

### IncomingCall

#### Renamed Properties

| V5 Name             | V6 Name              | Type    | Description                              |
| ------------------- | -------------------- | ------- | ---------------------------------------- |
| onDeclineCallClick  | onRejectClick        | OnClick | Click listener for decline/reject button |
| disableSoundForCall | disableSoundForCalls | boolean | Flag to disable sound for calls          |

#### Removed Properties

| Name                        | Type           | Description                                |
| --------------------------- | -------------- | ------------------------------------------ |
| cometChatTheme              | CometChatTheme | Theme instance                             |
| cometChatCard               | CometChatCard  | Card component for displaying call info    |
| setStyle(IncomingCallStyle) | Method         | Sets style using IncomingCallStyle object  |
| setAvatarStyle(AvatarStyle) | Method         | Sets avatar style using AvatarStyle object |

### OutgoingCall

#### Renamed Properties

| V5 Name            | V6 Name        | Type    | Description                                |
| ------------------ | -------------- | ------- | ------------------------------------------ |
| onDeclineCallClick | onEndCallClick | OnClick | Click listener for decline/end call button |

#### Removed Properties

| Name                        | Type           | Description                                |
| --------------------------- | -------------- | ------------------------------------------ |
| cometChatTheme              | CometChatTheme | Theme instance for styling                 |
| setStyle(OutgoingCallStyle) | Method         | Sets style using OutgoingCallStyle object  |
| setAvatarStyle(AvatarStyle) | Method         | Sets avatar style using AvatarStyle object |

### CallButtons

#### Renamed Properties

| V5 Name                            | V6 Name                           | Type   | Description                                   |
| ---------------------------------- | --------------------------------- | ------ | --------------------------------------------- |
| hideVoiceCall(boolean)             | setVoiceCallButtonVisibility(int) | Method | Controls voice call button visibility         |
| hideVideoCall(boolean)             | setVideoCallButtonVisibility(int) | Method | Controls video call button visibility         |
| setVoiceCallIcon(@DrawableRes int) | setVoiceCallIcon(Drawable)        | Method | Sets voice call icon (parameter type changed) |
| setVideoCallIcon(@DrawableRes int) | setVideoCallIcon(Drawable)        | Method | Sets video call icon (parameter type changed) |

#### Removed Properties

| Name                        | Type           | Description                                |
| --------------------------- | -------------- | ------------------------------------------ |
| theme                       | CometChatTheme | Theme instance for styling                 |
| setStyle(CallButtonsStyle)  | Method         | Sets style using CallButtonsStyle object   |
| setButtonStyle(ButtonStyle) | Method         | Sets button style using ButtonStyle object |

### CallLogs

#### Renamed Properties

| V5 Name                           | V6 Name                      | Type   | Description                   |
| --------------------------------- | ---------------------------- | ------ | ----------------------------- |
| setOnItemClickListener            | setOnItemClick               | Method | Sets item click listener      |
| setOnInfoIconClickListener        | setOnCallIconClickListener   | Method | Sets call icon click listener |
| setEmptyStateView(@LayoutRes int) | setEmptyView(@LayoutRes int) | Method | Sets empty state view         |
| setErrorStateView(@LayoutRes int) | setErrorView(@LayoutRes int) | Method | Sets error state view         |
| setListItemView                   | setItemView                  | Method | Sets item view                |

#### Removed Properties

| Name                        | Type                      | Description                                |
| --------------------------- | ------------------------- | ------------------------------------------ |
| theme                       | CometChatTheme            | Theme instance                             |
| swipeHelper                 | RecyclerViewSwipeListener | Swipe gesture helper                       |
| setStyle(CallLogsStyle)     | Method                    | Sets style using CallLogsStyle object      |
| setAvatarStyle(AvatarStyle) | Method                    | Sets avatar style using AvatarStyle object |

***

## Next Steps

<CardGroup>
  <Card title="Getting Started" href="/ui-kit/android/getting-started">
    Fresh V6 setup guide for Android.
  </Card>

  <Card title="Components Overview" href="/ui-kit/android/components-overview">
    Explore all V6 prebuilt UI components.
  </Card>

  <Card title="Theming" href="/ui-kit/android/theme-introduction">
    XML-based and Compose theming system.
  </Card>

  <Card title="Methods" href="/ui-kit/android/methods">
    Init, login, logout, and other UI Kit methods.
  </Card>
</CardGroup>

***


# Users
Source: https://www.cometchat.com/docs/ui-kit/android/users

Scrollable list of all available users with search, avatars, names, and online/offline status indicators.

`CometChatUsers` renders a scrollable list of all available users with real-time presence updates, search, avatars, and online/offline status indicators.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatUsers` is a list component. It renders all available users and emits the selected `User` via `onItemClick`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a direct messaging layout.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```xml activity_chat.xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.users.ui.CometChatUsers
        android:id="@+id/users"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    ```kotlin lines theme={null}
    val users = findViewById<CometChatUsers>(R.id.users)

    users.setOnItemClick { user ->
        messageHeader.setUser(user)
        messageList.setUser(user)
        messageComposer.setUser(user)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        modifier = Modifier.fillMaxSize(),
        onItemClick = { user ->
            messageHeader.setUser(user)
            messageList.setUser(user)
            messageComposer.setUser(user)
        }
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Add to your layout XML:

    ```xml lines theme={null}
    <com.cometchat.uikit.kotlin.presentation.users.ui.CometChatUsers
        android:id="@+id/users"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```

    Or programmatically:

    ```kotlin lines theme={null}
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(CometChatUsers(this))
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    @Composable
    fun UsersScreen() {
        CometChatUsers(
            modifier = Modifier.fillMaxSize()
        )
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

Or in a Fragment:

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
        return CometChatUsers(requireContext())
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
        return ComposeView(requireContext()).apply {
            setContent { CometChatUsers() }
        }
    }
    ```
  </Tab>
</Tabs>

***

## Filtering Users

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Pass a `UsersRequest.UsersRequestBuilder` to control what loads:

    ```kotlin lines theme={null}
    users.setUsersRequestBuilder(
        UsersRequest.UsersRequestBuilder()
            .friendsOnly(true)
            .setLimit(20)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        usersRequestBuilder = UsersRequest.UsersRequestBuilder()
            .friendsOnly(true)
            .setLimit(20)
    )
    ```
  </Tab>
</Tabs>

### Filter Recipes

| Recipe             | Builder method                                          |
| ------------------ | ------------------------------------------------------- |
| Friends only       | `.friendsOnly(true)`                                    |
| Limit per page     | `.setLimit(10)`                                         |
| Search by keyword  | `.setSearchKeyword("john")`                             |
| Hide blocked users | `.hideBlockedUsers(true)`                               |
| Filter by roles    | `.setRoles(listOf("admin", "moderator"))`               |
| Filter by tags     | `.setTags(listOf("vip"))`                               |
| Online users only  | `.setUserStatus(CometChatConstants.USER_STATUS_ONLINE)` |
| Filter by UIDs     | `.setUIDs(listOf("uid1", "uid2"))`                      |

<Warning>
  Pass the builder object, not the result of `.build()`. The component calls `.build()` internally. Default page size is 30 with infinite scroll.
</Warning>

***

## Actions and Events

### Callback Methods

#### `onItemClick`

Fires when a user row is tapped. Primary navigation hook.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setOnItemClick { user ->
        // Navigate to chat screen
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        onItemClick = { user ->
            // Navigate to chat screen
        }
    )
    ```
  </Tab>
</Tabs>

> Replaces the default item-click behavior. Your custom lambda executes instead of the built-in navigation.

#### `onItemLongClick`

Fires when a user row is long-pressed. Use for additional actions like block or mute.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setOnItemLongClick { user ->
        // Show context menu
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        onItemLongClick = { user ->
            // Show context menu
        }
    )
    ```
  </Tab>
</Tabs>

#### `onBackPress`

Fires when the user presses the back button in the toolbar.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setOnBackPress {
        finish()
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        onBackPress = { /* navigate back */ }
    )
    ```
  </Tab>
</Tabs>

#### `onSearchClick`

Fires when the user taps the search icon in the toolbar.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setOnSearchClick {
        // Open search screen
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        onSearchClick = { /* open search */ }
    )
    ```
  </Tab>
</Tabs>

#### `onSelection`

Fires when users are selected/deselected in multi-select mode.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE)
    users.setOnSelection { selectedUsers ->
        updateToolbar(selectedUsers.size)
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        selectionMode = UIKitConstants.SelectionMode.MULTIPLE,
        onSelection = { selectedUsers ->
            updateToolbar(selectedUsers.size)
        }
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setOnError { exception ->
        Log.e("Users", "Error: ${exception.message}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        onError = { exception ->
            Log.e("Users", "Error: ${exception.message}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched and loaded.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setOnLoad { userList ->
        Log.d("Users", "Loaded ${userList.size}")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        onLoad = { userList ->
            Log.d("Users", "Loaded ${userList.size}")
        }
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setOnEmpty {
        Log.d("Users", "No users found")
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        onEmpty = { /* no users */ }
    )
    ```
  </Tab>
</Tabs>

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

| SDK Listener    | Internal behavior                             |
| --------------- | --------------------------------------------- |
| `onUserOnline`  | Updates online status indicator for the user  |
| `onUserOffline` | Updates offline status indicator for the user |

***

## Functionality

| Method (Kotlin XML)                    | Compose Parameter                   | Description                       |
| -------------------------------------- | ----------------------------------- | --------------------------------- |
| `setBackIconVisibility(View.VISIBLE)`  | `hideBackIcon = false`              | Toggle back button                |
| `setToolbarVisibility(View.GONE)`      | `hideToolbar = true`                | Toggle toolbar                    |
| `setSearchBoxVisibility(View.GONE)`    | `hideSearchBox = true`              | Toggle search box                 |
| `setStickyHeaderVisibility(View.GONE)` | `hideStickyHeader = true`           | Toggle alphabetical sticky header |
| `setUserStatusVisibility(View.GONE)`   | `hideUserStatus = true`             | Toggle online status indicator    |
| `setSeparatorVisibility(View.GONE)`    | `hideSeparator = true`              | Toggle list separators            |
| `setSelectionMode(MULTIPLE)`           | `selectionMode = MULTIPLE`          | Enable selection mode             |
| `setTitle("Contacts")`                 | `title = "Contacts"`                | Custom toolbar title              |
| `setSearchPlaceholderText("Find...")`  | `searchPlaceholderText = "Find..."` | Search placeholder                |

***

## Custom View Slots

### Leading View

Replace the avatar / left section.

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setLeadingView(object : UsersViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return ImageView(context).apply {
                layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp)
            }
        }

        override fun bindView(
            context: Context, createdView: View, user: User,
            holder: RecyclerView.ViewHolder, userList: List<User>, position: Int
        ) {
            val imageView = createdView as ImageView
            // Load avatar image
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        leadingView = { user ->
            CometChatAvatar(
                imageUrl = user.avatar,
                name = user.name
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Title View

Replace the name / title text.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setTitleView(object : UsersViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return TextView(context)
        }

        override fun bindView(
            context: Context, createdView: View, user: User,
            holder: RecyclerView.ViewHolder, userList: List<User>, position: Int
        ) {
            (createdView as TextView).text = user.name ?: ""
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        titleView = { user ->
            Text(
                text = user.name ?: "",
                style = CometChatTheme.typography.heading4Medium
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

Replace the subtitle text below the user's name.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setSubtitleView(object : UsersViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return TextView(context)
        }

        override fun bindView(
            context: Context, createdView: View, user: User,
            holder: RecyclerView.ViewHolder, userList: List<User>, position: Int
        ) {
            val tvSubtitle = createdView as TextView
            tvSubtitle.text = "Last Active: " + SimpleDateFormat("dd/MM/yyyy, HH:mm:ss").format(user.lastActiveAt * 1000)
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        subtitleView = { user ->
            Text(
                text = "Last Active: ${SimpleDateFormat("dd/MM/yyyy").format(user.lastActiveAt * 1000)}",
                maxLines = 1,
                overflow = TextOverflow.Ellipsis
            )
        }
    )
    ```
  </Tab>
</Tabs>

### Trailing View

Replace the right section of each user item.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setTrailingView(object : UsersViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return TextView(context)
        }

        override fun bindView(
            context: Context, createdView: View, user: User,
            holder: RecyclerView.ViewHolder, userList: List<User>, position: Int
        ) {
            (createdView as TextView).text = user.role ?: ""
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        trailingView = { user ->
            Text(text = user.role ?: "")
        }
    )
    ```
  </Tab>
</Tabs>

### Item View

Replace the entire list item row.

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setItemView(object : UsersViewHolderListener() {
        override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View {
            return LayoutInflater.from(context).inflate(R.layout.custom_user_item, null)
        }

        override fun bindView(
            context: Context, createdView: View, user: User,
            holder: RecyclerView.ViewHolder, userList: List<User>, position: Int
        ) {
            val avatar = createdView.findViewById<CometChatAvatar>(R.id.custom_avatar)
            val title = createdView.findViewById<TextView>(R.id.tvName)
            title.text = user.name
            avatar.setAvatar(user.name, user.avatar)
        }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        itemView = { user ->
            Row(
                modifier = Modifier.fillMaxWidth().padding(12.dp),
                verticalAlignment = Alignment.CenterVertically
            ) {
                CometChatAvatar(imageUrl = user.avatar, name = user.name)
                Spacer(Modifier.width(12.dp))
                Text(user.name ?: "", style = CometChatTheme.typography.heading4Medium)
            }
        }
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setEmptyView(R.layout.custom_empty_view)
    users.setErrorView(R.layout.custom_error_view)
    users.setLoadingView(R.layout.custom_loading_view)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        emptyView = { Text("No users found") },
        errorView = { onRetry -> Button(onClick = onRetry) { Text("Retry") } },
        loadingView = { CircularProgressIndicator() }
    )
    ```
  </Tab>
</Tabs>

### Overflow Menu

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setOverflowMenu(ImageButton(context).apply {
        setImageResource(R.drawable.ic_filter)
        setOnClickListener { /* show filter */ }
    })
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        overflowMenu = {
            IconButton(onClick = { /* show filter */ }) {
                Icon(painterResource(R.drawable.ic_filter), "Filter")
            }
        }
    )
    ```
  </Tab>
</Tabs>

***

## Menu Options

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Replace all options
    users.setOptions { context, user ->
        listOf(
            CometChatPopupMenu.MenuItem(id = "block", name = "Block", onClick = { /* ... */ }),
            CometChatPopupMenu.MenuItem(id = "mute", name = "Mute", onClick = { /* ... */ })
        )
    }

    // Append to defaults
    users.setAddOptions { context, user ->
        listOf(
            CometChatPopupMenu.MenuItem(id = "pin", name = "Pin", onClick = { /* ... */ })
        )
    }
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        options = { context, user ->
            listOf(
                MenuItem(id = "block", name = "Block", onClick = { /* ... */ }),
                MenuItem(id = "mute", name = "Mute", onClick = { /* ... */ })
            )
        },
        addOptions = { context, user ->
            listOf(MenuItem(id = "pin", name = "Pin", onClick = { /* ... */ }))
        }
    )
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Minimal list — hide all chrome

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setToolbarVisibility(View.GONE)
    users.setSearchBoxVisibility(View.GONE)
    users.setStickyHeaderVisibility(View.GONE)
    users.setUserStatusVisibility(View.GONE)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        hideToolbar = true,
        hideSearchBox = true,
        hideStickyHeader = true,
        hideUserStatus = true
    )
    ```
  </Tab>
</Tabs>

### Friends-only list

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setUsersRequestBuilder(
        UsersRequest.UsersRequestBuilder()
            .friendsOnly(true)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        usersRequestBuilder = UsersRequest.UsersRequestBuilder()
            .friendsOnly(true)
    )
    ```
  </Tab>
</Tabs>

### Online users only

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setUsersRequestBuilder(
        UsersRequest.UsersRequestBuilder()
            .setUserStatus(CometChatConstants.USER_STATUS_ONLINE)
    )
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        usersRequestBuilder = UsersRequest.UsersRequestBuilder()
            .setUserStatus(CometChatConstants.USER_STATUS_ONLINE)
    )
    ```
  </Tab>
</Tabs>

***

## Advanced Methods

### Programmatic Selection

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    // Enable selection
    users.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE)

    // Select a user
    users.selectUser(user, UIKitConstants.SelectionMode.MULTIPLE)

    // Get selected
    val selected = users.getSelectedUsers()

    // Clear
    users.clearSelection()
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    Selection is managed via the `selectionMode` and `onSelection` parameters. The component handles selection state internally.
  </Tab>
</Tabs>

### ViewModel Access

```kotlin lines theme={null}
val factory = CometChatUsersViewModelFactory()
val viewModel = ViewModelProvider(this, factory)
    .get(CometChatUsersViewModel::class.java)
```

<Tabs>
  <Tab title="Kotlin (XML Views)">
    ```kotlin lines theme={null}
    users.setViewModel(viewModel)
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        usersViewModel = viewModel
    )
    ```
  </Tab>
</Tabs>

See [ViewModel & Data](/docs/ui-kit/android/customization-viewmodel-data) for ListOperations, state observation, and custom repositories.

***

## Style

<Frame>
  <img />
</Frame>

<Tabs>
  <Tab title="Kotlin (XML Views)">
    Define a custom style in `themes.xml`:

    ```xml themes.xml lines theme={null}
    <style name="CustomAvatarStyle" parent="CometChatAvatarStyle">
        <item name="cometchatAvatarStrokeRadius">8dp</item>
        <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
    </style>

    <style name="CustomUsersStyle" parent="CometChatUsersStyle">
        <item name="cometchatUsersAvatarStyle">@style/CustomAvatarStyle</item>
        <item name="cometchatUsersSeparatorColor">#F76808</item>
        <item name="cometchatUsersTitleTextColor">#F76808</item>
    </style>

    <style name="AppTheme" parent="CometChatTheme.DayNight">
        <item name="cometchatUsersStyle">@style/CustomUsersStyle</item>
    </style>
    ```
  </Tab>

  <Tab title="Jetpack Compose">
    ```kotlin lines theme={null}
    CometChatUsers(
        style = CometChatUsersStyle.default().copy(
            backgroundColor = Color(0xFFF5F5F5),
            titleTextColor = Color(0xFF141414),
            itemStyle = CometChatUsersItemStyle.default().copy(
                backgroundColor = Color.White,
                titleTextColor = Color(0xFF141414),
                subtitleTextColor = Color(0xFF727272),
                avatarStyle = CometChatAvatarStyle.default().copy(cornerRadius = 12.dp),
                statusIndicatorStyle = CometChatStatusIndicatorStyle.default().copy()
            )
        )
    )
    ```
  </Tab>
</Tabs>

### Style Properties

| Property                            | Description              |
| ----------------------------------- | ------------------------ |
| `backgroundColor`                   | List background color    |
| `titleTextColor`                    | Toolbar title color      |
| `searchBoxStyle`                    | Search box appearance    |
| `itemStyle.backgroundColor`         | Row background           |
| `itemStyle.selectedBackgroundColor` | Selected row background  |
| `itemStyle.titleTextColor`          | User name color          |
| `itemStyle.subtitleTextColor`       | Subtitle text color      |
| `itemStyle.separatorColor`          | Row separator color      |
| `itemStyle.avatarStyle`             | Avatar appearance        |
| `itemStyle.statusIndicatorStyle`    | Online/offline indicator |

See [Component Styling](/docs/ui-kit/android/component-styling) for the full reference.

***

## Next Steps

<CardGroup>
  <Card title="Conversations" icon="comments" href="/ui-kit/android/conversations">
    Browse recent conversations
  </Card>

  <Card title="Groups" icon="users" href="/ui-kit/android/groups">
    Browse and search available groups
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/android/component-styling">
    Detailed styling reference with screenshots
  </Card>

  <Card title="ViewModel & Data" icon="database" href="/ui-kit/android/customization-viewmodel-data">
    Custom ViewModels, repositories, and ListOperations
  </Card>
</CardGroup>


# Changelog
Source: https://www.cometchat.com/docs/ui-kit/ios/link/changelog

Navigate to Changelog documentation.



# Call Buttons
Source: https://www.cometchat.com/docs/ui-kit/flutter/call-buttons

Add CometChat Flutter UI Kit call buttons for voice and video calling, call settings, and call-related user actions.

## Overview

The `CometChatCallButtons` widget provides users with the ability to make calls, access call-related functionalities, and control call settings.

## Usage

### Integration

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart';
    import 'package:flutter/material.dart';

    class CallButtonsExample extends StatefulWidget {
      const CallButtonsExample({super.key});

      @override
      State<CallButtonsExample> createState() => _CallButtonsExampleState();
    }

    class _CallButtonsExampleState extends State<CallButtonsExample> {
      @override
      Widget build(BuildContext context) {
        return Scaffold(
          body: SafeArea(
            child: Center(child: CometChatCallButtons()),
          ),
        );
      }
    }
    ```
  </Tab>
</Tabs>

***

### Actions

##### onError

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallButtons(
      onError: (e) {
        // Handle error
      },
    )
    ```
  </Tab>
</Tabs>

***

### Events

| Event          | Description                                 |
| -------------- | ------------------------------------------- |
| ccCallAccepted | Triggers when the outgoing call is accepted |
| ccCallRejected | Triggers when the outgoing call is rejected |

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class _YourScreenState extends State<YourScreen> with CometChatCallEventListener {
      @override
      void initState() {
        super.initState();
        CometChatCallEvents.addCallEventsListener("unique_listener_ID", this);
      }

      @override
      void dispose() {
        super.dispose();
        CometChatCallEvents.removeCallEventsListener("unique_listener_ID");
      }

      @override
      void ccCallAccepted(Call call) {
        // Handle call accepted
      }

      @override
      void ccCallRejected(Call call) {
        // Handle call rejected
      }
    }
    ```
  </Tab>
</Tabs>

***

## Customization

### Style

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallButtons(
      callButtonsStyle: CometChatCallButtonsStyle(
        voiceCallIconColor: Color(0xFF6852D6),
        videoCallIconColor: Color(0xFF6852D6),
        voiceCallButtonColor: Color(0xFFEDEAFA),
        videoCallButtonColor: Color(0xFFEDEAFA),
        voiceCallButtonBorderRadius: BorderRadius.circular(12.5),
        videoCallButtonBorderRadius: BorderRadius.circular(12.5),
      ),
    )
    ```
  </Tab>
</Tabs>

### Functionality

| Property                    | Description             | Code                                                             |
| --------------------------- | ----------------------- | ---------------------------------------------------------------- |
| User                        | Set User object         | `user: User?`                                                    |
| Group                       | Set Group object        | `group: Group?`                                                  |
| CallSettingsBuilder         | Configure call settings | `callSettingsBuilder: CallSettingsBuilder?`                      |
| Hide Video Call             | Hide video call button  | `hideVideoCallButton: bool?`                                     |
| Hide Voice Call             | Hide voice call button  | `hideVoiceCallButton: bool?`                                     |
| Video Call Icon             | Custom video call icon  | `videoCallIcon: Icon?`                                           |
| Voice Call Icon             | Custom voice call icon  | `voiceCallIcon: Icon?`                                           |
| Outgoing Call Configuration | Configure outgoing call | `outgoingCallConfiguration: CometChatOutgoingCallConfiguration?` |


# Call
Source: https://www.cometchat.com/docs/ui-kit/flutter/call-features

Integrate CometChat Flutter UI Kit calling with one-on-one and group audio/video calls, setup, initialization, and call events.

## Overview

CometChat's Calls feature allows you to integrate one-on-one and group audio/video calling capabilities into your application. In V6, calling is built into the `cometchat_chat_uikit` package — no separate calls dependency needed.

## Integration

### Step 1: Add Dependency

Add the dependency to your `pubspec.yaml`:

```yaml pubspec.yaml theme={null}
dependencies:
  cometchat_chat_uikit: ^6.0.5
```

***

### Step 2: Update build.gradle

Set `minSdkVersion` to at least 24 in `android/app/build.gradle`:

<Tabs>
  <Tab title="Groovy">
    ```gradle theme={null}
    defaultConfig {
        minSdkVersion 24
        targetSdkVersion flutter.targetSdkVersion
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }
    ```
  </Tab>
</Tabs>

***

### Step 3: Update iOS Podfile

In `ios/Podfile`, set the minimum iOS version to 12:

```
platform :ios, '12.0'
```

***

### Step 4: Modify UIKitSettings

Activate calling features by setting `enableCalls` to `true` in UIKitSettings:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    UIKitSettings uiKitSettings = (UIKitSettingsBuilder()
      ..subscriptionType = CometChatSubscriptionType.allUsers
      ..autoEstablishSocketConnection = true
      ..region = "REGION"
      ..appId = "APP_ID"
      ..authKey = "AUTH_KEY"
      ..enableCalls = true
      ..callingConfiguration = CallingConfiguration()
    ).build();

    CometChatUIKit.init(uiKitSettings: uiKitSettings,
      onSuccess: (successMessage) {},
      onError: (e) {},
    );
    ```
  </Tab>
</Tabs>

To allow launching the Incoming Call screen from any widget, provide the navigator key:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    MaterialApp(
      navigatorKey: CallNavigationContext.navigatorKey,
      home: YourHomeScreen(),
    )
    ```
  </Tab>
</Tabs>

### Listeners

Register call listeners for top-level widgets:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class _YourClassNameState extends State<YourClassName> with CallListener {
      @override
      void initState() {
        super.initState();
        CometChat.addCallListener(listenerId, this);
      }

      @override
      void dispose() {
        super.dispose();
        CometChat.removeCallListener(listenerId);
      }

      @override
      void onIncomingCallReceived(Call call) {
        debugPrint("onIncomingCallReceived");
      }

      @override
      void onOutgoingCallAccepted(Call call) {
        debugPrint("onOutgoingCallAccepted");
      }

      @override
      void onOutgoingCallRejected(Call call) {
        debugPrint("onOutgoingCallRejected");
      }

      @override
      void onIncomingCallCancelled(Call call) {
        debugPrint("onIncomingCallCancelled");
      }

      @override
      void onCallEndedMessageReceived(Call call) {
        debugPrint("onCallEndedMessageReceived");
      }

      @override
      Widget build(BuildContext context) {
        return const Placeholder();
      }
    }
    ```
  </Tab>
</Tabs>

***

## Features

### Incoming Call

The Incoming Call widget lets users receive real-time audio and video calls. When a call is received, it displays caller information with accept/reject options.

### Outgoing Call

The Outgoing Call widget manages the outgoing call process. It displays recipient information and call status, and automatically transitions to the ongoing call screen when accepted.

### Call Logs

The [Call Logs](/docs/ui-kit/flutter/call-logs) widget displays records of call events including caller, time, and duration.


# Call Logs
Source: https://www.cometchat.com/docs/ui-kit/flutter/call-logs

Show CometChat Flutter UI Kit call logs with audio/video status, missed calls, timestamps, pagination, and call actions.

`CometChatCallLogs` renders a scrollable list of call history with call type indicators (audio/video), call status (incoming/outgoing/missed), timestamps, and pagination support.

<Frame>
  <img />
</Frame>

The `CometChatCallLogs` widget is composed of the following base widgets:

| Widget            | Description                                                           |
| ----------------- | --------------------------------------------------------------------- |
| CometChatListBase | Container widget with title, background options, and list integration |
| CometChatListItem | Displays call log data on a card with title and subtitle              |

***

## Where It Fits

`CometChatCallLogs` is a list component. It renders call history and emits the selected `CallLog` via `onItemClick`. Wire it to a detail screen or use `onCallLogIconClicked` to initiate a call directly from the log.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      onItemClick: (callLog) {
        // Navigate to call log details or open chat
        Navigator.push(
          context,
          MaterialPageRoute(
            builder: (context) => CometChatCallLogDetails(callLog: callLog),
          ),
        );
      },
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

Using Navigator:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    Navigator.push(context, MaterialPageRoute(builder: (context) => const CometChatCallLogs()));
    ```
  </Tab>
</Tabs>

Embedding as a widget:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart';
    import 'package:flutter/material.dart';

    class CallLogsExample extends StatefulWidget {
      const CallLogsExample({super.key});

      @override
      State<CallLogsExample> createState() => _CallLogsExampleState();
    }

    class _CallLogsExampleState extends State<CallLogsExample> {
      @override
      Widget build(BuildContext context) {
        return const Scaffold(
          body: SafeArea(child: CometChatCallLogs()),
        );
      }
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the Calls UIKit dependency added. See [Call Features](/docs/ui-kit/flutter/call-features) for setup.

***

## Filtering Call Logs

Pass a `CallLogRequestBuilder` to control what loads:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      callLogsRequestBuilder: CallLogRequestBuilder()
        ..limit = 10
        ..hasRecording = true,
    )
    ```
  </Tab>
</Tabs>

### Filter Recipes

| Recipe                    | Builder property               |
| ------------------------- | ------------------------------ |
| Limit per page            | `..limit = 10`                 |
| Audio calls only          | `..callType = "audio"`         |
| Video calls only          | `..callType = "video"`         |
| Missed calls only         | `..callStatus = "missed"`      |
| Incoming calls only       | `..callDirection = "incoming"` |
| Outgoing calls only       | `..callDirection = "outgoing"` |
| Calls with recording      | `..hasRecording = true`        |
| Calls for specific user   | `..uid = "user_uid"`           |
| Calls for specific group  | `..guid = "group_guid"`        |
| Call category (call/meet) | `..callCategory = "call"`      |

### Filter Properties

| Property        | Type      | Description                                                                                                      |
| --------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `authToken`     | `String?` | Authentication token                                                                                             |
| `callCategory`  | `String?` | Category: `"call"` or `"meet"`                                                                                   |
| `callDirection` | `String?` | Direction: `"incoming"` or `"outgoing"`                                                                          |
| `callStatus`    | `String?` | Status: `"ongoing"`, `"busy"`, `"rejected"`, `"cancelled"`, `"ended"`, `"missed"`, `"initiated"`, `"unanswered"` |
| `callType`      | `String?` | Type: `"audio"`, `"video"`, or `"audio/video"`                                                                   |
| `guid`          | `String?` | Group ID filter                                                                                                  |
| `hasRecording`  | `bool`    | Filter calls with recordings                                                                                     |
| `limit`         | `int`     | Max results per request                                                                                          |
| `uid`           | `String?` | User ID filter                                                                                                   |

***

## Actions and Events

### Callback Methods

#### `onItemClick`

Fires when a call log item is tapped. Primary navigation hook.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      onItemClick: (callLog) {
        // Navigate to call details or chat
      },
    )
    ```
  </Tab>
</Tabs>

#### `onItemLongPress`

Fires when a call log item is long-pressed, allowing additional actions.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      onItemLongPress: (CallLog callLog) {
        // Show context menu
      },
    )
    ```
  </Tab>
</Tabs>

#### `onBack`

Fires when the user presses the back button in the app bar.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      onBack: () {
        Navigator.pop(context);
      },
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      onError: (e) {
        debugPrint("Error: ${e.message}");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched and loaded.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      onLoad: (list) {
        debugPrint("Loaded ${list.length} call logs");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      onEmpty: () {
        debugPrint("No call logs found");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onCallLogIconClicked`

Fires when the call icon on a call log item is tapped, typically used to initiate a call back.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      onCallLogIconClicked: (CallLog callLog) {
        // Initiate call back to this contact
      },
    )
    ```
  </Tab>
</Tabs>

### Events

The `CometChatCallLogs` widget does not emit global events.

***

## Functionality

| Property                | Type      | Default | Description                          |
| ----------------------- | --------- | ------- | ------------------------------------ |
| `showBackButton`        | `bool?`   | `true`  | Toggle back button visibility        |
| `hideAppbar`            | `bool?`   | `false` | Toggle app bar visibility            |
| `backButton`            | `Widget?` | `null`  | Custom back button widget            |
| `datePattern`           | `String?` | `null`  | Format pattern for date display      |
| `dateSeparatorPattern`  | `String?` | `null`  | Format pattern for date separator    |
| `hideSeparator`         | `bool`    | `false` | Hide separator between items         |
| `emptyStateText`        | `String?` | `null`  | Text for empty state                 |
| `errorStateText`        | `String?` | `null`  | Text for error state                 |
| `incomingAudioCallIcon` | `Icon?`   | `null`  | Custom icon for incoming audio calls |
| `incomingVideoCallIcon` | `Icon?`   | `null`  | Custom icon for incoming video calls |
| `outgoingAudioCallIcon` | `Icon?`   | `null`  | Custom icon for outgoing audio calls |
| `outgoingVideoCallIcon` | `Icon?`   | `null`  | Custom icon for outgoing video calls |
| `missedAudioCallIcon`   | `Icon?`   | `null`  | Custom icon for missed audio calls   |
| `missedVideoCallIcon`   | `Icon?`   | `null`  | Custom icon for missed video calls   |
| `infoIconUrl`           | `String?` | `null`  | URL for the info icon                |
| `loadingIconUrl`        | `String?` | `null`  | URL for the loading icon             |

**Example — custom back button:**

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      backButton: Icon(Icons.arrow_back_ios, color: Color(0xFF6851D6)),
    )
    ```
  </Tab>
</Tabs>

<img alt="Image" />

<img alt="Image" />

***

## Custom View Slots

### List Item View

Replace the entire list item row with a custom widget.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      listItemView: (callLog, context) {
        final status = getCallStatus(context, callLog, CometChatUIKit.loggedInUser);
        IconData icon = Icons.call;
        Color? color;
        Color? textColor;

        if (status == "Incoming Call") {
          icon = Icons.phone_callback_rounded;
          color = Color(0xFF6852D6);
        } else if (status == "Outgoing Call") {
          icon = Icons.phone_forwarded;
          color = Color(0xFF6852D6);
        } else if (status == "Missed Call") {
          icon = Icons.phone_missed;
          color = Colors.red;
          textColor = Colors.red;
        }

        String name = _getCallLogName(callLog);
        String formattedDate = DateFormat('d MMM, hh:mm a').format(
          DateTime.fromMillisecondsSinceEpoch((callLog.initiatedAt ?? 0) * 1000),
        );

        return ListTile(
          leading: CircleAvatar(
            backgroundColor: Color(0xFFEDEAFA),
            child: Icon(icon, color: color, size: 24),
          ),
          title: Text(name, style: TextStyle(
            fontSize: 16, fontWeight: FontWeight.w500,
            color: textColor ?? Color(0xFF141414),
          )),
          subtitle: Text(status, style: TextStyle(
            color: Color(0xFF727272), fontSize: 14,
          )),
          trailing: Text(formattedDate, style: TextStyle(
            color: Color(0xFF727272), fontSize: 14,
          )),
        );
      },
    )
    ```
  </Tab>

  <Tab title="Helper: getCallStatus">
    ```dart theme={null}
    static String getCallStatus(BuildContext context, CallLog callLog, User? loggedInUser) {
      String callMessageText = "";
      if (callLog.receiverType == ReceiverTypeConstants.user) {
        CallUser initiator = callLog.initiator as CallUser;
        bool isMe = initiator.uid == loggedInUser?.uid;

        switch (callLog.status) {
          case CallStatusConstants.initiated:
            callMessageText = isMe ? "Outgoing Call" : "Incoming Call";
            break;
          case CallStatusConstants.ongoing:
            callMessageText = "Call Accepted";
            break;
          case CallStatusConstants.ended:
            callMessageText = "Call Ended";
            break;
          case CallStatusConstants.unanswered:
          case CallStatusConstants.cancelled:
          case CallStatusConstants.rejected:
          case CallStatusConstants.busy:
            callMessageText = isMe ? "Call ${callLog.status}" : "Missed Call";
            break;
        }
      }
      return callMessageText;
    }
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

### Title View

Replace the caller name / title text.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      titleView: (callLog, context) {
        return Text(
          _getCallLogName(callLog),
          style: TextStyle(fontWeight: FontWeight.bold, fontSize: 16),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Leading View

Replace the avatar / left section.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      leadingView: (callLog, context) {
        return CircleAvatar(
          backgroundColor: Color(0xFFEDEAFA),
          child: Icon(Icons.call, color: Color(0xFF6852D6)),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

Replace the call status text below the name.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      subTitleView: (callLog, context) {
        return Row(
          children: [
            _getCallIcon(callLog, CometChatUIKit.loggedInUser),
            SizedBox(width: 4),
            Text(
              getCallStatus(context, callLog, CometChatUIKit.loggedInUser),
              style: TextStyle(color: Color(0xFF727272), fontSize: 14),
            ),
          ],
        );
      },
    )
    ```
  </Tab>

  <Tab title="Helper: _getCallIcon">
    ```dart theme={null}
    static Widget _getCallIcon(CallLog callLog, User? loggedInUser) {
      bool isMe = (callLog.initiator as CallUser?)?.uid == loggedInUser?.uid;

      Widget incoming = Icon(Icons.call_received_outlined, color: Colors.red, size: 16);
      Widget outgoing = Icon(Icons.call_made_outlined, color: Color(0xFF09C26F), size: 16);
      Widget missed = Icon(Icons.call_received_outlined, color: Colors.red, size: 16);

      switch (callLog.status) {
        case CallStatusConstants.initiated:
        case CallStatusConstants.ongoing:
        case CallStatusConstants.ended:
          return isMe ? outgoing : incoming;
        case CallStatusConstants.unanswered:
        case CallStatusConstants.cancelled:
        case CallStatusConstants.rejected:
        case CallStatusConstants.busy:
          return isMe ? outgoing : missed;
        default:
          return const SizedBox();
      }
    }
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

### Trailing View

Replace the timestamp / right section.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      trailingView: (context, callLog) {
        String formattedDate = DateFormat('d MMM, hh:mm a').format(
          DateTime.fromMillisecondsSinceEpoch((callLog.initiatedAt ?? 0) * 1000),
        );
        return Text(
          formattedDate,
          style: TextStyle(color: Color(0xFF727272), fontSize: 14),
        );
      },
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

### State Views

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      emptyStateView: (context) => Center(child: Text("No call logs yet")),
      errorStateView: (context) => Center(child: Text("Something went wrong")),
      loadingStateView: (context) => Center(child: CircularProgressIndicator()),
    )
    ```
  </Tab>
</Tabs>

***

## Menu Options

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // Replace all options
    CometChatCallLogs(
      setOptions: (callLog, controller, context) {
        return [
          CometChatOption(
            id: "callback",
            iconWidget: Icon(Icons.call),
            title: "Call Back",
            onClick: () {
              // Initiate call back
            },
          ),
        ];
      },
    )

    // Append to defaults
    CometChatCallLogs(
      addOptions: (callLog, controller, context) {
        return [
          CometChatOption(
            id: "block",
            iconWidget: Icon(Icons.block),
            title: "Block Number",
            onClick: () {
              // Block this contact
            },
          ),
        ];
      },
    )
    ```
  </Tab>
</Tabs>

***

## Style

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      callLogsStyle: CometChatCallLogsStyle(
        titleTextColor: Color(0xFFF76808),
        separatorColor: Color(0xFFF76808),
        avatarStyle: CometChatAvatarStyle(
          borderRadius: BorderRadius.circular(8),
          backgroundColor: Color(0xFFFBAA75),
        ),
      ),
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

***

## Configurations

### Outgoing Call

Customize the outgoing call component that appears when a call is initiated from a call log:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatCallLogs(
      outgoingCallConfiguration: OutgoingCallConfiguration(
        subtitle: "Outgoing Call",
        outgoingCallStyle: OutgoingCallStyle(
          background: Color(0xFFE4EBF5),
        ),
      ),
    )
    ```
  </Tab>
</Tabs>

<img alt="Image" />

<img alt="Image" />

All exposed properties of `OutgoingCallConfiguration` can be found under [Outgoing Call](/docs/ui-kit/flutter/outgoing-call).

***

## Next Steps

<CardGroup>
  <Card title="Call Log Details Guide" icon="circle-info" href="/ui-kit/flutter/guide-call-log-details">
    Build a call log details screen
  </Card>

  <Card title="Call Buttons" icon="phone" href="/ui-kit/flutter/call-buttons">
    Add voice and video call buttons
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/flutter/component-styling">
    Detailed styling reference
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/flutter/conversations">
    Browse recent conversations
  </Card>
</CardGroup>


# Campaigns
Source: https://www.cometchat.com/docs/ui-kit/flutter/campaigns

Deliver targeted, rich notifications to users via an in-app notification feed powered by the CometChat Cards renderer.

CometChat Campaigns enables you to send rich, interactive notifications to users through an in-app notification feed. Each notification is rendered as a native card using the **CometChat Cards** library — supporting images, text, buttons, layouts, and interactive actions.

<Tip>
  **Design cards visually with [Card Builder](/docs/card-builder/overview).** Build your card layouts in the CometChat Dashboard and export the Card Schema JSON these notifications render — instead of writing it by hand.
</Tip>

<Note>
  Before proceeding, ensure you have completed the [UI Kit integration](/docs/ui-kit/flutter/getting-started) and the [Dashboard Setup](/docs/campaigns#setup-flow) for Campaigns.
</Note>

<Frame>
  <img />
</Frame>

***

## Overview

Campaigns delivers notifications as **Card Schema JSON** — a structured format that defines the visual layout of each notification card. The system consists of three layers:

1. **CometChat Chat SDK** — Fetches feed items, manages read/delivered state, provides real-time listeners, handles push notification tracking
2. **CometChat Cards Library** — Renders Card Schema JSON into native Flutter widgets
3. **CometChat UI Kit** — Provides the ready-to-use `CometChatNotificationFeed` component that wires everything together

### Architecture Flow

```
Dashboard / API → Campaign Created → Push + WebSocket Delivery
                                            ↓
                                     SDK: NotificationFeedRequest.fetchNext()
                                            ↓
                                     NotificationFeedItem.content → Card Schema JSON
                                            ↓
                                     Cards Library: CometChatCardView
                                            ↓
                                     Native Rendered Card (images, text, buttons, layouts)
                                            ↓
                                     User taps button → ActionCallback → Your code handles it
```

***

## How Cards Work

Each `NotificationFeedItem` from the SDK contains a `content` field — a `Map<String, dynamic>` holding the Card Schema JSON. This JSON is passed directly to the CometChat Cards renderer which produces a native Flutter widget.

The Cards library is a **pure renderer**:

* **Input**: Card Schema JSON string + theme mode + optional action callback
* **Output**: Flutter widget tree

It does not execute actions, manage message state, or call any SDK methods. When users tap interactive elements (buttons, links), the library emits the action to your callback. You decide what happens — open a URL, navigate to a chat, make an API call, etc.

### Card Schema JSON Example

```json theme={null}
{
  "version": "1.0",
  "body": [
    {
      "type": "column",
      "backgroundColor": {
        "light": "transparent",
        "dark": "transparent"
      },
      "gap": 5,
      "items": [
        {
          "type": "text",
          "content": "📢 Announcement",
          "variant": "heading2",
          "id": "txt_99323141-2459-4e33-88d3-ca39c5fd2f50"
        },
        {
          "type": "text",
          "content": "Your announcement message here.",
          "variant": "body",
          "id": "txt_61a417bc-5e4a-4ba2-bfe7-b7bc64dbaf35"
        },
        {
          "type": "divider",
          "id": "div_80f5c7fb-fd10-41d1-8c2f-51498f0f62d0"
        },
        {
          "type": "button",
          "label": "Learn More",
          "backgroundColor": {
            "light": "transparent",
            "dark": "transparent"
          },
          "textColor": {
            "light": "#6C5CE7",
            "dark": "#6C5CE7"
          },
          "size": 40,
          "fontSize": 13,
          "borderRadius": 6,
          "padding": {
            "top": 0,
            "right": 16,
            "bottom": 0,
            "left": 16
          },
          "action": {
            "type": "openUrl",
            "url": ""
          },
          "id": "btn_9b87a3f1-b0c6-45b9-a4c2-e22ea590f17f"
        }
      ],
      "id": "col_98fed9bd-1a95-4cee-aa81-84a9016e41f2"
    }
  ],
  "fallbackText": "",
  "style": {
    "background": {
      "light": "#E8E8E8",
      "dark": "#E8E8E8"
    },
    "borderRadius": 16,
    "borderColor": {
      "light": "#DFE6E9",
      "dark": "#DFE6E9"
    },
    "padding": 12
  }
}
```

The schema supports **20 element types** (text, image, icon, avatar, badge, divider, spacer, chip, progressBar, codeBlock, markdown, row, column, grid, accordion, tabs, button, iconButton, link, table) and **9 action types** (openUrl, chatWithUser, chatWithGroup, sendMessage, copyToClipboard, downloadFile, initiateCall, apiCall, customCallback).

Here's how the above JSON renders as a native card:

<Frame>
  <img />
</Frame>

***

## How Cards Work in the UI Kit

The `CometChatNotificationFeed` component uses the **CometChat Cards** library internally to render each notification. Here's what happens under the hood:

1. The component fetches `NotificationFeedItem` objects from the SDK
2. For each item, it extracts the `content` field (Card Schema JSON)
3. It passes the JSON to `CometChatCardView` from the Cards library
4. The Cards renderer produces native Flutter widgets — text, images, buttons, layouts — directly from the JSON
5. When users tap buttons/links inside a card, the action is emitted back to the component which handles navigation (open URL, navigate to chat, etc.)

You don't need to interact with the Cards library directly when using `CometChatNotificationFeed` — it's all wired up. But if you want to render cards outside the feed (e.g., a standalone card in a dialog), you can use the Cards library directly. See the [SDK Campaigns documentation](/docs/sdk/flutter/campaigns#rendering-cards) for standalone usage.

***

## Handling Push Notifications for Campaigns

When a campaign push notification arrives via FCM/APNs, you should:

1. **Report delivery** — Call `CometChat.markPushNotificationDelivered()` in your push notification handler
2. **Report click** — Call `CometChat.markPushNotificationClicked()` when the user taps the notification
3. **Deep link** — Use the announcement ID from the push payload to fetch the full item via `CometChat.getNotificationFeedItem(id)` and display it

```dart theme={null}
// When push notification is received
final pushNotification = PushNotification(
  id: payload['announcementId'],
  announcementId: payload['announcementId'],
  campaignId: payload['campaignId'],
  source: "campaign",
);
CometChat.markPushNotificationDelivered(pushNotification, onSuccess: (_) {}, onError: (_) {});

// When user taps the notification
CometChat.markPushNotificationClicked(pushNotification, onSuccess: (_) {}, onError: (_) {});

// Navigate to feed or show specific item
CometChat.getNotificationFeedItem(
  pushNotification.id,
  onSuccess: (item) { /* render card */ },
  onError: (e) { /* handle error */ },
);
```

See the [SDK Campaigns documentation](/docs/sdk/flutter/campaigns) for the complete push notification tracking API.

***

## Sending Campaigns

Before integrating the frontend, you need to set up channels, categories, templates, and campaigns in the CometChat Dashboard. Follow the [Dashboard Setup Guide](/docs/campaigns#setup-flow) for step-by-step instructions with screenshots.

***

## Using the UI Kit Component

The easiest way to add a notification feed to your app is the `CometChatNotificationFeed` component. It handles fetching, rendering, pagination, filtering, real-time updates, and engagement reporting out of the box.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    class NotificationsScreen extends StatelessWidget {
      const NotificationsScreen({super.key});

      @override
      Widget build(BuildContext context) {
        return CometChatNotificationFeed(
          onItemClick: (NotificationFeedItem item) {
            // Handle item tap
          },
          onBackPress: () => Navigator.of(context).pop(),
        );
      }
    }
    ```
  </Tab>
</Tabs>

See the full [CometChatNotificationFeed component documentation](/docs/ui-kit/flutter/notification-feed) for all configuration options, styling, and customization.

***

## Next Steps

<CardGroup>
  <Card title="SDK Campaigns API" icon="code" href="/sdk/flutter/campaigns">
    Full API reference for feed items, categories, engagement, and push tracking
  </Card>

  <Card title="CometChatNotificationFeed" icon="bell" href="/ui-kit/flutter/notification-feed">
    Ready-to-use component with filtering, real-time updates, and styling
  </Card>
</CardGroup>


# Color Resources
Source: https://www.cometchat.com/docs/ui-kit/flutter/color-resources

Customize the CometChat Flutter UI Kit theme with palettes for light mode, dark mode, backgrounds, text, borders, icons, and buttons.

## Introducing CometChatColorPalette

The `CometChatColorPalette` class allows you to customize the colors used throughout your app. It works the same way in V6 as in V5 — you assign it to the `extensions` property of your `ThemeData`.

Here's what you can customize:

* Primary Colors — Main color scheme of your app
* Neutral Colors — Balanced base for visuals
* Alert Colors — Informative, warning, success, and error messages
* Background Colors — Background shades for different areas
* Text Colors — Text element colors for readability
* Border Colors — Borders for buttons and cards
* Icon Colors — App icon colors
* Button Colors — Button background and text colors
* Shimmer Colors — Loading animation colors

### Light Mode

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatColorPalette(
          textSecondary: Color(0xFF727272),
          background1: Color(0xFFFFFFFF),
          textPrimary: Color(0xFF141414),
          borderLight: Color(0xFFF5F5F5),
          borderDark: Color(0xFFDCDCDC),
          iconSecondary: Color(0xFFA1A1A1),
          success: Color(0xFF09C26F),
          iconHighlight: Color(0xFF6852D6),
          extendedPrimary500: Color(0xFFAA9EE8),
          warning: Color(0xFFFAAB00),
          messageSeen: Color(0xFF56E8A7),
          neutral900: Color(0xFF141414),
          neutral600: Color(0xFF727272),
          neutral300: Color(0xFFE8E8E8),
          primary: Color(0xFF6852D6),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Dark Mode

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatColorPalette(
          textSecondary: Color(0xFF989898),
          background1: Color(0xFF1A1A1A),
          textPrimary: Color(0xFFFFFFFF),
          borderLight: Color(0xFF272727),
          iconSecondary: Color(0xFF858585),
          success: Color(0xFF0B9F5D),
          iconHighlight: Color(0xFF6852D6),
          extendedPrimary500: Color(0xFF3E3180),
          warning: Color(0xFFD08D04),
          messageSeen: Color(0xFF56E8A7),
          neutral900: Color(0xFFFFFFFF),
          neutral600: Color(0xFF989898),
          neutral300: Color(0xFF383838),
          primary: Color(0xFF6852D6),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Custom Colors

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatColorPalette(
          textSecondary: Color(0xFF727272),
          background1: Color(0xFFFFFFFF),
          textPrimary: Color(0xFF141414),
          borderLight: Color(0xFFF5F5F5),
          borderDark: Color(0xFFDCDCDC),
          iconSecondary: Color(0xFFA1A1A1),
          success: Color(0xFF09C26F),
          iconHighlight: Color(0xFFF76808),
          extendedPrimary500: Color(0xFFFBAA75),
          warning: Color(0xFFFAAB00),
          messageSeen: Color(0xFF56E8A7),
          neutral900: Color(0xFF141414),
          neutral600: Color(0xFF727272),
          neutral300: Color(0xFFE8E8E8),
          primary: Color(0xFFF76808),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>


# Component Styling
Source: https://www.cometchat.com/docs/ui-kit/flutter/component-styling

Style CometChat Flutter UI Kit components with ThemeData extensions, component-level style objects, message bubbles, and call UI.

The Flutter UI Kit uses `ThemeExtension` for styling. You can apply styles globally via `ThemeData` or pass style objects directly to components.

## Two Approaches

### 1. Global Theming via ThemeData

Apply styles across your entire app by adding `ThemeExtension` objects to your `MaterialApp` theme:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    MaterialApp(
      theme: ThemeData(
        extensions: [
          CometChatOutgoingMessageBubbleStyle(
            backgroundColor: Color(0xFFF76808),
          ),
          CometChatIncomingMessageBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
          ),
          CometChatActionBubbleStyle(
            textStyle: TextStyle(color: Color(0xFFF76808)),
            backgroundColor: Color(0xFFFEEDE1),
          ),
        ],
      ),
      home: YourApp(),
    )
    ```
  </Tab>
</Tabs>

### 2. Component-Level Styles

Pass style objects directly to a component. These override global theme values:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      style: CometChatMessageListStyle(
        backgroundColor: Color(0xFFFEEDE1),
        outgoingMessageBubbleStyle: CometChatOutgoingMessageBubbleStyle(
          backgroundColor: Color(0xFFF76808),
        ),
        incomingMessageBubbleStyle: CometChatIncomingMessageBubbleStyle(
          backgroundColor: Colors.white,
        ),
      ),
    )
    ```
  </Tab>
</Tabs>

## Style Precedence

```
Component style prop > ThemeData extension > Default theme
```

***

## Style Classes by Component

| Component                  | Style Class                     |
| -------------------------- | ------------------------------- |
| `CometChatConversations`   | `CometChatConversationsStyle`   |
| `CometChatUsers`           | `CometChatUsersStyle`           |
| `CometChatGroups`          | `CometChatGroupsStyle`          |
| `CometChatGroupMembers`    | `CometChatGroupMembersStyle`    |
| `CometChatMessageList`     | `CometChatMessageListStyle`     |
| `CometChatMessageComposer` | `CometChatMessageComposerStyle` |
| `CometChatMessageHeader`   | `CometChatMessageHeaderStyle`   |

## Message Bubble Styles

The message list style contains nested styles for incoming and outgoing bubbles:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageListStyle(
      outgoingMessageBubbleStyle: CometChatOutgoingMessageBubbleStyle(
        textBubbleStyle: CometChatTextBubbleStyle(...),
        imageBubbleStyle: CometChatImageBubbleStyle(...),
        videoBubbleStyle: CometChatVideoBubbleStyle(...),
        audioBubbleStyle: CometChatAudioBubbleStyle(...),
        fileBubbleStyle: CometChatFileBubbleStyle(...),
        deletedBubbleStyle: CometChatDeletedBubbleStyle(...),
        pollsBubbleStyle: CometChatPollsBubbleStyle(...),
        stickerBubbleStyle: CometChatStickerBubbleStyle(...),
        collaborativeWhiteboardBubbleStyle: CometChatCollaborativeBubbleStyle(...),
        collaborativeDocumentBubbleStyle: CometChatCollaborativeBubbleStyle(...),
        linkPreviewBubbleStyle: CometChatLinkPreviewBubbleStyle(...),
        videoCallBubbleStyle: CometChatCallBubbleStyle(...),
      ),
      incomingMessageBubbleStyle: CometChatIncomingMessageBubbleStyle(
        // Same nested style structure
      ),
    )
    ```
  </Tab>
</Tabs>

See [Message Bubble Styling](/docs/ui-kit/flutter/message-bubble-styling) for per-bubble-type examples.

***

## Component Style Examples

### Conversations

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      fontFamily: 'Times New Roman',
      extensions: [
        CometChatConversationsStyle(
          avatarStyle: CometChatAvatarStyle(
            borderRadius: BorderRadius.circular(8),
            backgroundColor: Color(0xFFFBAA75),
          ),
          badgeStyle: CometChatBadgeStyle(
            backgroundColor: Color(0xFFF76808),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Message List

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatMessageListStyle(
          backgroundColor: Color(0xFFFEEDE1),
          outgoingMessageBubbleStyle: CometChatOutgoingMessageBubbleStyle(
            backgroundColor: Color(0xFFF76808),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Message Composer

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatMessageComposerStyle(
          sendButtonIconBackgroundColor: Color(0xFFF76808),
          secondaryButtonIconColor: Color(0xFFF76808),
          auxiliaryButtonIconColor: Color(0xFFF76808),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Message Header

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatMessageHeaderStyle(
          avatarStyle: CometChatAvatarStyle(
            backgroundColor: Color(0xFFFBAA75),
            borderRadius: BorderRadius.circular(6.67),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Users

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatUsersStyle(
          avatarStyle: CometChatAvatarStyle(
            borderRadius: BorderRadius.circular(8),
            backgroundColor: Color(0xFFFBAA75),
          ),
          titleTextColor: Color(0xFFF76808),
          separatorColor: Color(0xFFF76808),
          backgroundColor: Color(0xFFFFF9F5),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Groups

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatGroupsStyle(
          avatarStyle: CometChatAvatarStyle(
            borderRadius: BorderRadius.circular(8),
            backgroundColor: Color(0xFFFBAA75),
          ),
          titleTextColor: Color(0xFFF76808),
          separatorColor: Color(0xFFF76808),
          backgroundColor: Color(0xFFFFF9F5),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Group Members

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatGroupMembersStyle(
          avatarStyle: CometChatAvatarStyle(
            borderRadius: BorderRadius.circular(8),
            backgroundColor: Color(0xFFFBAA75),
          ),
          titleStyle: TextStyle(color: Color(0xFFF76808)),
          separatorColor: Color(0xFFF76808),
          ownerMemberScopeBackgroundColor: Color(0xFFF76808),
          adminMemberScopeBackgroundColor: Color(0xFFFEEDE1),
          adminMemberScopeBorder: Border.all(color: Color(0xFFF76808)),
          adminMemberScopeTextColor: Color(0xFFF76808),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### AI Assistant Chat History

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    final ccColor = CometChatThemeHelper.getColorPalette(context);
    CometChatAIAssistantChatHistory(
      user: user,
      style: CometChatAIAssistantChatHistoryStyle(
        backgroundColor: const Color(0xFFFFFAF6),
        headerBackgroundColor: const Color(0xFFFFFAF6),
        headerTitleTextColor: ccColor.textPrimary,
      ),
    )
    ```
  </Tab>
</Tabs>

***

## Base Component Styles

### Avatar

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatAvatarStyle(
          borderRadius: BorderRadius.circular(8),
          backgroundColor: Color(0xFFFBAA75),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Status Indicator

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatStatusIndicatorStyle(
          backgroundColor: Color(0xFFFFAB00),
          borderRadius: BorderRadius.circular(2),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Badge

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatBadgeStyle(
          borderRadius: BorderRadius.circular(4),
          backgroundColor: Color(0xFFF44649),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Receipts

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatMessageReceiptStyle(
          readIconColor: Color(0xFFFFAB00),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Media Recorder

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatMediaRecorderStyle(
          recordIndicatorBackgroundColor: Color(0xFFF44649),
          recordIndicatorBorderRadius: BorderRadius.circular(20),
          pauseButtonBorderRadius: BorderRadius.circular(8),
          deleteButtonBorderRadius: BorderRadius.circular(8),
          stopButtonBorderRadius: BorderRadius.circular(8),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Reactions

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatReactionsStyle(
          borderRadius: BorderRadius.circular(8),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Reaction List

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatReactionListStyle(
          activeTabTextColor: Color(0xFFF76808),
          activeTabIndicatorColor: Color(0xFFF76808),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Conversation Starter

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatAIConversationStarterStyle(
          backgroundColor: Color(0xFFFEEDE1),
          border: Border.all(color: Color(0xFFFBBB90)),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Conversation Summary

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatAIConversationSummaryStyle(
          backgroundColor: Color(0xFFFEEDE1),
          titleStyle: TextStyle(color: Color(0xFFF76808)),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Smart Replies

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatAISmartRepliesStyle(
          backgroundColor: Color(0xFFFEEDE1),
          titleStyle: TextStyle(color: Color(0xFFF76808)),
          itemBackgroundColor: Color(0xFFFFF9F5),
          itemBorder: Border.all(color: Color(0xFFFBBB90)),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Message Information

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      fontFamily: "Times New Roman",
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          backgroundColor: Color(0xFFF76808),
        ),
        CometChatMessageInformationStyle(
          backgroundHighLightColor: Color(0xFFFEEDE1),
          messageReceiptStyle: CometChatMessageReceiptStyle(
            readIconColor: Color(0xFFF76808),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Message Option Sheet

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatMessageOptionSheetStyle(
          backgroundColor: Color(0xFFFEEDE1),
          iconColor: Color(0xFFF76808),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Attachment Option Sheet

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatAttachmentOptionSheetStyle(
          backgroundColor: Color(0xFFFEEDE1),
          iconColor: Color(0xFFF76808),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### AI Option Sheet

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatAiOptionSheetStyle(
          backgroundColor: Color(0xFFFFF9F5),
          iconColor: Color(0xFFF76808),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Mentions

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatMentionsStyle(
          mentionSelfTextBackgroundColor: Color(0xFFF76808),
          mentionTextBackgroundColor: Colors.white,
          mentionTextColor: Colors.black,
          mentionSelfTextColor: Colors.white,
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

***

## Related

* [Message Bubble Styling](/docs/ui-kit/flutter/message-bubble-styling) — Per-bubble-type style examples.
* [Color Resources](/docs/ui-kit/flutter/color-resources) — Color palette customization.
* [Theme Introduction](/docs/ui-kit/flutter/theme-introduction) — Theme system overview (ColorPalette, Typography, Spacing).
* [Customization Overview](/docs/ui-kit/flutter/customization-overview) — All customization categories.


# Overview
Source: https://www.cometchat.com/docs/ui-kit/flutter/components-overview

Explore CometChat Flutter UI Kit V6 widgets, base widgets, component architecture, actions, filters, styles, and customization.

CometChat's **UI Kit V6** is a set of pre-built UI Widgets that allows you to easily craft an in-app chat with all the essential messaging features, built on clean architecture with BLoC state management.

## Type of Widget

UI Widgets based on behaviour and functionality can be categorized into two types: Base Widget and Widget.

### Base Widget

Base Widgets form the building blocks of your app's user interface (UI). They focus solely on presenting visual elements based on input data, without handling any business logic. These Widgets provide the foundational appearance and behavior for your UI.

### Widget

Widgets build upon Base Widgets by incorporating business logic via BLoC pattern. They not only render UI elements but also manage data loading through use cases and repositories, execute specific actions, and respond to events. This combination of visual presentation and functional capabilities makes Widgets essential for creating dynamic and interactive UIs.

> **V6 Note:** V6 does not have Composite Widgets like `CometChatMessages` or `CometChatConversationsWithMessages`. Instead, you compose the UI yourself using individual Widgets (`CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageHeader`). This gives you full control over layout and behavior.

## Architecture

Each Widget in V6 follows clean architecture internally:

| Layer      | Purpose                                     | Example                                                         |
| ---------- | ------------------------------------------- | --------------------------------------------------------------- |
| `bloc/`    | State management (events, states, BLoC)     | `ConversationsBloc`, `ConversationsEvent`, `ConversationsState` |
| `data/`    | Data sources and repository implementations | `ConversationsRemoteDatasource`, `ConversationsRepositoryImpl`  |
| `domain/`  | Use cases and repository interfaces         | `GetConversationsUseCase`, `ConversationsRepository`            |
| `di/`      | Dependency injection                        | `ConversationsServiceLocator`                                   |
| `widgets/` | Decomposed sub-widgets                      | `ConversationsList`, `ConversationsEmptyView`                   |

## Actions

Actions direct the operational behavior of a component. They are split into two categories: Predefined Actions and User-Defined Actions.

### Predefined Actions

These are actions inherently programmed into a UI component. They execute automatically in response to user interaction, without needing any additional user input.

### User-Defined Actions

These are actions that must be explicitly specified by the user. They provide adaptability and allow for the creation of custom behaviors that align with the individual needs of the application.

To customize the behavior of a component, actions must be overridden by the user. This provides the user with control over how the component responds to specific events or interactions.

## Events

Events allow for a decoupled, flexible architecture where different parts of the application can interact without having to directly reference each other. This makes it easier to create complex, interactive experiences, as well as to extend and customize the functionality provided by the CometChat UI Kit.

Widgets have the ability to emit events. These events are dispatched in response to certain changes or user interactions within the component. By emitting events, these Widgets allow other parts of the application to react to changes or interactions, thus enabling dynamic and interactive behavior within the application.

## Configurations

Configurations offer the ability to customize the properties of each individual component. Each Widget has its own set of properties that can be configured, allowing for fine-tuned customization to tailor behavior and appearance to match specific requirements in a granular manner.


# Conversations
Source: https://www.cometchat.com/docs/ui-kit/flutter/conversations

Display CometChat Flutter UI Kit conversations with real-time updates for messages, typing indicators, read receipts, and presence.

`CometChatConversations` renders a scrollable list of recent conversations with real-time updates for new messages, typing indicators, read receipts, and user presence.

***

## Where It Fits

`CometChatConversations` is a list component. It renders recent conversations and emits the selected `Conversation` via `onItemTap`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a standard chat layout.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      onItemTap: (conversation) {
        final entity = conversation.conversationWith;
        if (entity is User) {
          navigateToUserChat(entity);
        } else if (entity is Group) {
          navigateToGroupChat(entity);
        }
      },
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

Using Navigator:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    Navigator.push(context, MaterialPageRoute(builder: (context) => const CometChatConversations()));
    ```
  </Tab>
</Tabs>

Embedding as a widget:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    @override
    Widget build(BuildContext context) {
      return Scaffold(
        body: SafeArea(
          child: CometChatConversations(),
        ),
      );
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

***

## Filtering Conversations

Pass a `ConversationsRequestBuilder` to control what loads:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      conversationsRequestBuilder: ConversationsRequestBuilder()
        ..conversationType = "user"
        ..limit = 10,
    )
    ```
  </Tab>
</Tabs>

### Filter Recipes

| Recipe                   | Builder property                           |
| ------------------------ | ------------------------------------------ |
| Only user conversations  | `..conversationType = "user"`              |
| Only group conversations | `..conversationType = "group"`             |
| Limit per page           | `..limit = 10`                             |
| With tags                | `..tags = ["vip"]` and `..withTags = true` |
| With user and group tags | `..withUserAndGroupTags = true`            |

***

## Actions and Events

### Callback Methods

#### `onItemTap`

Fires when a conversation row is tapped. Primary navigation hook.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      onItemTap: (conversation) {
        // Navigate to chat screen
      },
    )
    ```
  </Tab>
</Tabs>

#### `onItemLongPress`

Fires when a conversation row is long-pressed. By default shows a delete overlay (when `deleteConversationOptionVisibility` is true).

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      onItemLongPress: (conversation) {
        // Custom long press behavior
      },
    )
    ```
  </Tab>
</Tabs>

#### `onBack`

Fires when the user presses the back button in the app bar.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      onBack: () {
        Navigator.pop(context);
      },
    )
    ```
  </Tab>
</Tabs>

#### `onSelection`

Fires when conversations are selected/deselected in multi-select mode.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      selectionMode: SelectionMode.multiple,
      onSelection: (selectedConversations) {
        // Handle selected conversations
      },
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      onError: (e) {
        debugPrint("Error: ${e.message}");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched and loaded.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      onLoad: (conversations) {
        debugPrint("Loaded ${conversations.length}");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      onEmpty: () {
        debugPrint("No conversations");
      },
    )
    ```
  </Tab>
</Tabs>

### Global Events

The component emits events via `CometChatConversationEvents` that can be subscribed to from anywhere:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class _YourScreenState extends State<YourScreen> with CometChatConversationEventListener {

      @override
      void initState() {
        super.initState();
        CometChatConversationEvents.addConversationListListener("listenerId", this);
      }

      @override
      void dispose() {
        CometChatConversationEvents.removeConversationListListener("listenerId");
        super.dispose();
      }

      @override
      void ccConversationDeleted(Conversation conversation) {
        // Handle conversation deleted
      }
    }
    ```
  </Tab>
</Tabs>

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

| SDK Listener                                                                                | Internal behavior                                                |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived`              | Moves conversation to top, updates last message and unread count |
| `onTypingStarted` / `onTypingEnded`                                                         | Shows/hides typing indicator in subtitle                         |
| `onMessagesDelivered` / `onMessagesRead`                                                    | Updates receipt indicators                                       |
| `onUserOnline` / `onUserOffline`                                                            | Updates presence status dot                                      |
| `onGroupMemberJoined` / `onGroupMemberLeft` / `onGroupMemberKicked` / `onGroupMemberBanned` | Updates group conversation metadata                              |
| Connection reconnected                                                                      | Triggers silent refresh to sync missed messages                  |

***

## Functionality

| Property                             | Type             | Default | Description                                         |
| ------------------------------------ | ---------------- | ------- | --------------------------------------------------- |
| `title`                              | `String?`        | `null`  | Custom app bar title                                |
| `showBackButton`                     | `bool`           | `false` | Toggle back button                                  |
| `hideAppbar`                         | `bool?`          | `false` | Toggle app bar visibility                           |
| `hideSearch`                         | `bool?`          | `null`  | Toggle search bar                                   |
| `searchReadOnly`                     | `bool`           | `false` | Make search bar read-only (tap opens custom search) |
| `deleteConversationOptionVisibility` | `bool?`          | `true`  | Show delete option on long press                    |
| `groupTypeVisibility`                | `bool?`          | `true`  | Show group type icon on avatar                      |
| `usersStatusVisibility`              | `bool?`          | `true`  | Show online/offline status indicator                |
| `receiptsVisibility`                 | `bool?`          | `true`  | Show message receipts                               |
| `disableSoundForMessages`            | `bool`           | `false` | Disable message sounds                              |
| `customSoundForMessages`             | `String?`        | `null`  | Custom notification sound asset path                |
| `selectionMode`                      | `SelectionMode?` | `null`  | Enable selection mode (`single` or `multiple`)      |

***

## Custom View Slots

### Leading View

Replace the avatar / left section.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      leadingView: (context, conversation) {
        return CircleAvatar(
          child: Text(conversation.conversationWith?.name?[0] ?? ""),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Title View

Replace the name / title text.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      titleView: (context, conversation) {
        return Text(
          conversation.conversationWith?.name ?? "",
          style: TextStyle(fontWeight: FontWeight.bold),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

Replace the last message preview.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      subtitleView: (context, conversation) {
        final msg = conversation.lastMessage;
        if (msg is TextMessage) {
          return Text(msg.text, maxLines: 1, overflow: TextOverflow.ellipsis);
        }
        return Text("New conversation");
      },
    )
    ```
  </Tab>
</Tabs>

### Trailing View

Replace the timestamp / badge / right section.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      trailingView: (conversation) {
        if (conversation.unreadMessageCount > 0) {
          return Badge(label: Text("${conversation.unreadMessageCount}"));
        }
        return null;
      },
    )
    ```
  </Tab>
</Tabs>

### List Item View

Replace the entire list item row.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      listItemView: (conversation) {
        return ListTile(
          leading: CircleAvatar(child: Text(conversation.conversationWith?.name?[0] ?? "")),
          title: Text(conversation.conversationWith?.name ?? ""),
          subtitle: Text("Custom item"),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      emptyStateView: (context) => Center(child: Text("No conversations yet")),
      errorStateView: (context) => Center(child: Text("Something went wrong")),
      loadingStateView: (context) => Center(child: CircularProgressIndicator()),
    )
    ```
  </Tab>
</Tabs>

***

## Menu Options

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // Replace all options
    CometChatConversations(
      setOptions: (conversation, bloc, context) {
        return [
          CometChatOption(
            id: "delete",
            icon: AssetConstants.delete,
            title: "Delete",
            onClick: () {
              bloc.add(DeleteConversation(conversation.conversationId!));
            },
          ),
        ];
      },
    )

    // Append to defaults
    CometChatConversations(
      addOptions: (conversation, bloc, context) {
        return [
          CometChatOption(
            id: "archive",
            iconWidget: Icon(Icons.archive_outlined),
            title: "Archive",
            onClick: () {
              // Archive conversation
            },
          ),
        ];
      },
    )
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Minimal list — hide all chrome

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      hideAppbar: true,
      hideSearch: true,
    )
    ```
  </Tab>
</Tabs>

### Users-only conversations

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      conversationsRequestBuilder: ConversationsRequestBuilder()
        ..conversationType = "user",
    )
    ```
  </Tab>
</Tabs>

### Custom date formatting

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      datePattern: (conversation) {
        final timestamp = conversation.updatedAt;
        return DateFormat('MMM d').format(DateTime.fromMillisecondsSinceEpoch(timestamp! * 1000));
      },
    )
    ```
  </Tab>
</Tabs>

***

## Advanced

### BLoC Access

Provide a custom `ConversationsBloc` to override behavior:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      conversationsBloc: CustomConversationsBloc(),
    )
    ```
  </Tab>
</Tabs>

### Extending ConversationsBloc

`ConversationsBloc` uses the `ListBase<Conversation>` mixin with override hooks for custom list behavior:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class CustomConversationsBloc extends ConversationsBloc {
      @override
      void onItemAdded(Conversation item, List<Conversation> updatedList) {
        // Custom sorting — pinned conversations first
        final sorted = _sortWithPinnedFirst(updatedList);
        super.onItemAdded(item, sorted);
      }

      @override
      void onListReplaced(List<Conversation> previousList, List<Conversation> newList) {
        // Filter out blocked users on every list refresh
        final filtered = newList.where((c) => !isBlocked(c)).toList();
        super.onListReplaced(previousList, filtered);
      }
    }
    ```
  </Tab>
</Tabs>

For `ListBase` override hooks (`onItemAdded`, `onItemRemoved`, `onItemUpdated`, `onListCleared`, `onListReplaced`), see [BLoC & Data — ListBase Hooks](/docs/ui-kit/flutter/customization-bloc-data#listbase-hooks).

### Public BLoC Events

| Event                                                     | Description                                                                            |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `LoadConversations({silent})`                             | Load initial conversations. `silent: true` keeps existing list visible during refresh. |
| `LoadMoreConversations()`                                 | Load next page (pagination)                                                            |
| `RefreshConversations()`                                  | Refresh the list                                                                       |
| `DeleteConversation(conversationId)`                      | Delete via SDK and remove from list                                                    |
| `RemoveConversation(conversationId)`                      | Remove from list without SDK call                                                      |
| `SetActiveConversation(conversationId)`                   | Mark as active (suppresses unread count)                                               |
| `UpdateConversation(conversationId, updatedConversation)` | Update with modified data                                                              |
| `ResetUnreadCount(conversationId)`                        | Reset unread count to 0                                                                |

### Public BLoC Methods

| Method                                | Returns                                | Description                                            |
| ------------------------------------- | -------------------------------------- | ------------------------------------------------------ |
| `getTypingNotifier(conversationId)`   | `ValueNotifier<List<TypingIndicator>>` | Per-conversation typing notifier for isolated rebuilds |
| `getTypingIndicators(conversationId)` | `List<TypingIndicator>`                | Current typing indicators for a conversation           |

### Route Observer

Pass a `RouteObserver` to freeze rebuilds when another screen is pushed on top (prevents expensive rebuilds during keyboard animation):

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // In your app
    final RouteObserver<ModalRoute<void>> routeObserver = RouteObserver<ModalRoute<void>>();

    MaterialApp(
      navigatorObservers: [routeObserver],
    )

    // Pass to conversations
    CometChatConversations(
      routeObserver: routeObserver,
    )
    ```
  </Tab>
</Tabs>

***

## Style

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      conversationsStyle: CometChatConversationsStyle(
        backgroundColor: Colors.white,
        avatarStyle: CometChatAvatarStyle(
          borderRadius: BorderRadius.circular(8),
          backgroundColor: Color(0xFFFBAA75),
        ),
        badgeStyle: CometChatBadgeStyle(
          backgroundColor: Color(0xFFF76808),
        ),
        receiptStyle: CometChatMessageReceiptStyle(),
        typingIndicatorStyle: CometChatTypingIndicatorStyle(),
        dateStyle: CometChatDateStyle(),
        mentionsStyle: CometChatMentionsStyle(),
        deleteConversationDialogStyle: CometChatConfirmDialogStyle(),
      ),
    )
    ```
  </Tab>
</Tabs>

### Style Properties

| Property                        | Description                |
| ------------------------------- | -------------------------- |
| `backgroundColor`               | List background color      |
| `avatarStyle`                   | Avatar appearance          |
| `badgeStyle`                    | Unread badge appearance    |
| `receiptStyle`                  | Read receipt icons         |
| `typingIndicatorStyle`          | Typing indicator text      |
| `dateStyle`                     | Timestamp appearance       |
| `mentionsStyle`                 | Mention highlight style    |
| `deleteConversationDialogStyle` | Delete confirmation dialog |

See [Component Styling](/docs/ui-kit/flutter/component-styling) for the full reference.

***

## Next Steps

<CardGroup>
  <Card title="Users" icon="user" href="/ui-kit/flutter/users">
    Browse and search available users
  </Card>

  <Card title="Message List" icon="comments" href="/ui-kit/flutter/message-list">
    Display messages for a conversation
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/flutter/component-styling">
    Detailed styling reference
  </Card>

  <Card title="Message Template" icon="puzzle-piece" href="/ui-kit/flutter/message-template">
    Customize message bubble structure
  </Card>
</CardGroup>


# Core Features
Source: https://www.cometchat.com/docs/ui-kit/flutter/core-features

Review CometChat Flutter UI Kit core features for messaging, media sharing, receipts, presence, reactions, threads, and calls.

## Overview

The UI Kit comprises a variety of widgets, each designed to work seamlessly with one another to deliver a comprehensive and intuitive chat experience. Here's how different UI Kit widgets work together to achieve CometChat's Core features:

## Instant Messaging

At the heart of CometChat's functionality is the ability to support real-time text messaging. Users can send and receive instant messages, fostering quick and efficient communication.

| Widgets         | Functionality                                                                                                                                  |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| MessageComposer | Enables users to write and send a variety of messages. In V6, powered by `MessageComposerBloc` with rich text formatting support.              |
| MessageList     | Renders a list of messages sent and received using TextBubble. In V6, powered by `MessageListBloc` with `diffutil_dart` for efficient updates. |

## Media Sharing

Beyond text, CometChat allows users to share various media types within their conversations — images, videos, audio files, and documents.

| Widgets         | Functionality                                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| MessageComposer | Has ActionSheet for sharing media files. V6 adds inline audio recorder and multi-attachment support (in progress). |
| MessageList     | Renders different Media Message bubbles like Image Bubble, File Bubble, Audio Bubble, Video Bubble.                |

## Read Receipts

CometChat's Read Receipts feature provides visibility into the message status, letting users know when a message has been delivered and read.

| Widgets            | Functionality                                                   |
| ------------------ | --------------------------------------------------------------- |
| Conversations      | Displays the delivery status of the last message.               |
| MessageList        | Read receipt status is an integral part of all message bubbles. |
| MessageInformation | Provides transparency into the status of each sent message.     |

## Mark As Unread

Mark as Unread feature allows users to manually mark messages as unread, helping them keep track of important conversations they want to revisit later.

| Widgets       | Functionality                                                                                                |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| Message List  | Provides the "Mark as unread" option in message actions and supports starting from the first unread message. |
| Conversations | Reflects the updated unread count in real-time.                                                              |

## Typing Indicator

The Typing Indicator feature shows when a user is typing a response in real-time.

| Widgets        | Functionality                                                   |
| -------------- | --------------------------------------------------------------- |
| Conversations  | Shows real-time typing status indicators in conversation items. |
| Message Header | Dynamically updates to display a 'typing…' status in real-time. |

## User Presence

CometChat's User Presence feature allows users to see whether their contacts are online or offline.

| Widgets        | Functionality                                          |
| -------------- | ------------------------------------------------------ |
| Conversations  | Shows user presence information in conversation items. |
| Message Header | Handles user Presence information in the toolbar.      |
| Users          | Renders users Presence information in the user list.   |
| Group Members  | Handles user Presence information in the member list.  |

## Reactions

CometChat's Reactions feature allows users to react to messages with emojis.

| Widgets     | Functionality                                                                                                                 |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| MessageList | Reactions are an integral part of all message bubbles. Width-aware display shows visible reactions + "+N" overflow indicator. |

## Mentions

Mentions enhances interactivity by allowing users to directly address specific individuals in a conversation. Supports `@all` for group mentions.

| Widgets         | Functionality                                                   |
| --------------- | --------------------------------------------------------------- |
| Conversations   | Shows where users have been specifically mentioned.             |
| MessageComposer | Allows users to use the Mentions feature for direct addressing. |
| MessageList     | Supports the rendering of Mentions in messages.                 |

## Quoted Reply

Quoted Reply enables users to quickly reply to specific messages by selecting the "Reply" option from a message's action menu.

| Widgets         | Functionality                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| MessageList     | Supports replying to messages via the "Reply" option.                                                                     |
| MessageComposer | Shows the quoted reply above the input field using `CometChatMessagePreview` (renamed from `CometChatEditPreview` in V5). |

## Threaded Conversations

The Threaded Conversations feature enables users to respond directly to a specific message in a chat.

| Widgets           | Functionality                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------ |
| Threaded Messages | Displays all replies made to a particular message. In V6, powered by `ThreadedHeaderBloc`. |

## Conversation and Advanced Search

Enables users to quickly find conversations, messages, and media across chats in real time.

| Widgets        | Functionality                                                                                                   |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| Search         | Allows users to search across conversations and messages. In V6, powered by a single consolidated `SearchBloc`. |
| Message Header | Shows the search button in the chat header.                                                                     |
| MessageList    | Shows the selected message when clicked from search results.                                                    |

## Moderation

CometChat's Message Moderation feature helps maintain a safe and respectful chat environment by automatically filtering and managing inappropriate content.

| Widgets      | Functionality                                                                       |
| ------------ | ----------------------------------------------------------------------------------- |
| Message List | Automatically handles moderated messages, displaying blocked content appropriately. |

## Report Message

The Report Message feature allows users to report inappropriate or harmful messages within the chat.

| Widgets     | Functionality                                                     |
| ----------- | ----------------------------------------------------------------- |
| MessageList | Provides the "Report Message" option in the message actions menu. |

## Group Chat

CometChat facilitates Group Chats, allowing users to have conversations with multiple participants simultaneously.

For a comprehensive guide on implementing Groups, refer to our detailed [Groups guide](/docs/ui-kit/flutter/guide-group-chat).


# BLoC & Data
Source: https://www.cometchat.com/docs/ui-kit/flutter/customization-bloc-data

Configure data fetching with RequestBuilders, provide custom BLoC instances, and listen to state changes.

Each component's BLoC manages data fetching, state transitions, and business logic. You can configure it via RequestBuilders, provide a custom BLoC instance, or extend the default one.

## Configuring Data Fetching with RequestBuilders

Use request builders to control what data the component fetches. Pass the builder instance — not the result of `.build()`.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      messagesRequestBuilder: MessagesRequestBuilder()
        ..uid = user.uid
        ..searchKeyword = 'hello'
        ..limit = 30,
    )
    ```
  </Tab>
</Tabs>

<Warning>
  The following parameters in `MessagesRequestBuilder` will always be altered inside the message list: UID, GUID, types, categories.
</Warning>

### Request Builder by Component

| Component                | Builder Property              | Builder Type                  |
| ------------------------ | ----------------------------- | ----------------------------- |
| `CometChatConversations` | `conversationsRequestBuilder` | `ConversationsRequestBuilder` |
| `CometChatUsers`         | `usersRequestBuilder`         | `UsersRequestBuilder`         |
| `CometChatGroups`        | `groupsRequestBuilder`        | `GroupsRequestBuilder`        |
| `CometChatGroupMembers`  | `groupMembersRequestBuilder`  | `GroupMembersRequestBuilder`  |
| `CometChatMessageList`   | `messagesRequestBuilder`      | `MessagesRequestBuilder`      |

## Providing a Custom BLoC

Each component accepts an optional BLoC parameter. Provide your own instance to override default behavior:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    final myBloc = MessageListBloc(
      user: user,
      parentMessageId: null,
      types: MessageTemplateUtils.getAllMessageTypes(),
      categories: MessageTemplateUtils.getAllMessageCategories(),
    );

    CometChatMessageList(
      user: user,
      messageListBloc: myBloc,
    )
    ```
  </Tab>
</Tabs>

### BLoC Parameters by Component

| Component                  | BLoC Property         | BLoC Type             |
| -------------------------- | --------------------- | --------------------- |
| `CometChatConversations`   | `conversationsBloc`   | `ConversationsBloc`   |
| `CometChatMessageList`     | `messageListBloc`     | `MessageListBloc`     |
| `CometChatMessageComposer` | `messageComposerBloc` | `MessageComposerBloc` |

## Extending the Default BLoC

Extend the default BLoC class and override hooks to add custom behavior:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class CustomMessageListBloc extends MessageListBloc {
      CustomMessageListBloc({required User user})
          : super(user: user);

      @override
      void onItemAdded(BaseMessage item, List<BaseMessage> updatedList) {
        // Custom logic when a message is added
        debugPrint('Message added: ${item.id}');
        super.onItemAdded(item, updatedList);
      }

      @override
      void onItemRemoved(BaseMessage item, List<BaseMessage> updatedList) {
        // Custom logic when a message is removed
        super.onItemRemoved(item, updatedList);
      }

      @override
      void onItemUpdated(BaseMessage oldItem, BaseMessage newItem, List<BaseMessage> updatedList) {
        // Custom logic when a message is updated
        super.onItemUpdated(oldItem, newItem, updatedList);
      }
    }
    ```
  </Tab>
</Tabs>

### ListBase Hooks

All list-based BLoCs use the `ListBase` mixin with these override hooks:

| Hook                                           | Called When                      |
| ---------------------------------------------- | -------------------------------- |
| `onItemAdded(item, updatedList)`               | An item is added to the list     |
| `onItemRemoved(item, updatedList)`             | An item is removed from the list |
| `onItemUpdated(oldItem, newItem, updatedList)` | An item is updated in the list   |
| `onListCleared(previousList)`                  | The list is cleared              |
| `onListReplaced(previousList, newList)`        | The entire list is replaced      |

## Component-Specific BLoC Events

Each component's BLoC has its own events and methods. See the individual component docs for details:

* [Message List — BLoC Events & Methods](/docs/ui-kit/flutter/message-list#advanced)
* [Conversations — BLoC Events](/docs/ui-kit/flutter/conversations#advanced)
* [Users — BLoC Events](/docs/ui-kit/flutter/users#advanced)
* [Groups — BLoC Events](/docs/ui-kit/flutter/groups#advanced)
* [Group Members — BLoC Events](/docs/ui-kit/flutter/group-members#advanced)

## Lifecycle Callbacks

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      onLoad: (messages) {
        debugPrint('Loaded ${messages.length} messages');
      },
      onEmpty: () {
        debugPrint('No messages found');
      },
      onError: (e) {
        debugPrint('Error: ${e.message}');
      },
    )
    ```
  </Tab>
</Tabs>

## Related

* [Message List](/docs/ui-kit/flutter/message-list) — Full message list component reference.
* [Customization Overview](/docs/ui-kit/flutter/customization-overview) — See all customization categories.

***

## Repository & Datasource Overrides

Both `CometChatConversations` and `CometChatMessageList` follow the same clean architecture stack. There are two override points:

```
Widget → BLoC → UseCase → Repository → DataSource (Remote + Local)
                  ↑               ↑
          override here    or here
```

### 1. Datasource Override

Implement the abstract datasource interfaces to swap the data layer entirely — e.g. a REST API instead of the CometChat SDK, or a persistent cache instead of in-memory.

#### Conversations

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    abstract class ConversationsRemoteDataSource {
      Future<List<Conversation>> getConversations({int limit, String? fromId});
      Future<Conversation> getConversation(String conversationId);
      Future<void> deleteConversation(String conversationWith, String conversationType);
      Future<void> markMessageAsRead(BaseMessage message);
      Future<Conversation> updateConversation(Conversation conversation);
    }

    abstract class ConversationsLocalDataSource {
      Future<void> cacheConversations(List<Conversation> conversations);
      Future<List<Conversation>> getCachedConversations();
      Future<void> cacheConversation(Conversation conversation);
      Future<Conversation?> getCachedConversation(String conversationId);
      Future<void> removeCachedConversation(String conversationId);
      Future<void> clearCache();
      Future<bool> hasCachedData();
    }
    ```
  </Tab>
</Tabs>

#### Message List

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    abstract class MessageListRemoteDataSource {
      Future<GetMessagesResult> getMessages({...});
      Future<List<BaseMessage>> fetchPreviousMessages({required MessagesRequest request});
      Future<List<BaseMessage>> fetchNextMessages({required MessagesRequest request});
      Future<void> markAsRead(BaseMessage message);
      Future<void> markAsDelivered(BaseMessage message);
      Future<User?> getLoggedInUser();
      Future<Conversation> getConversation({...});
      Future<Conversation> markMessageAsUnread(BaseMessage message);
    }

    abstract class MessageListLocalDataSource {
      Future<void> cacheMessages(String conversationId, List<BaseMessage> messages);
      Future<List<BaseMessage>> getCachedMessages(String conversationId);
      // ... cache CRUD methods
    }
    ```
  </Tab>
</Tabs>

***

### 2. Repository Override

The repository interfaces sit above the datasources. Override here to change business logic — caching strategy, error handling, retry logic — without touching the datasource layer.

#### Conversations

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    abstract class ConversationsRepository {
      Future<Result<List<Conversation>>> getConversations({int limit, String? fromId});
      Future<Result<Conversation>> getConversationById(String conversationId);
      Future<Result<void>> deleteConversation(String conversationId);
      Future<Result<Conversation>> updateConversation(Conversation conversation);
      Future<Result<User?>> getLoggedInUser();
      Future<Result<void>> markAsDelivered(BaseMessage message);
      Future<Result<Conversation>> getConversation({...});
    }
    ```
  </Tab>
</Tabs>

#### Message List

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    abstract class MessageListRepository {
      Future<Result<List<BaseMessage>>> getMessages({...});
      Future<Result<List<BaseMessage>>> fetchPreviousMessages({...});
      Future<Result<List<BaseMessage>>> fetchNextMessages({...});
      Future<Result<void>> markAsRead(BaseMessage message);
      Future<Result<void>> markAsDelivered(BaseMessage message);
      Future<Result<User?>> getLoggedInUser();
      Future<Result<Conversation>> getConversation({...});
      Future<Result<Conversation>> markMessageAsUnread(BaseMessage message);
    }
    ```
  </Tab>
</Tabs>

***

### 3. Wiring via the Service Locator

The service locators are the injection point. Both are singletons with a `setup()` method. Call `reset()` first, then `setup()` with your custom implementations before the widget mounts.

#### Datasource-level override (Conversations)

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class MyConversationsRemoteDataSource implements ConversationsRemoteDataSource {
      @override
      Future<List<Conversation>> getConversations({int limit = 30, String? fromId}) async {
        // Your REST API call, mock data, etc.
      }
      // ... implement remaining methods
    }

    // Before mounting CometChatConversations:
    await ConversationsServiceLocator.instance.reset();

    final remote = MyConversationsRemoteDataSource();
    final local = ConversationsLocalDataSourceImpl(); // keep default cache
    final repo = ConversationsRepositoryImpl(
      remoteDataSource: remote,
      localDataSource: local,
    );
    ```
  </Tab>
</Tabs>

#### Repository-level override (Message List)

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class MyMessageListRepository implements MessageListRepository {
      @override
      Future<Result<List<BaseMessage>>> getMessages({...}) async {
        // Custom logic
      }
      // ...
    }

    // Before mounting CometChatMessageList:
    await MessageListServiceLocator.instance.reset();
    // Wire your repo into use cases and pass to the BLoC
    ```
  </Tab>
</Tabs>

***

### Key Points

| Point                                            | Detail                                                                                                                                                                         |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reset()`                                        | Sets `_isInitialized = false` — always call before re-wiring                                                                                                                   |
| `setup()`                                        | Guarded by `_isInitialized` — safe to call multiple times normally                                                                                                             |
| `localDataSource` in `MessageListRepositoryImpl` | Optional — pass `null` to disable caching entirely                                                                                                                             |
| Fallback caching                                 | `ConversationsRepositoryImpl` falls back to local cache when remote fails — your custom remote inherits this if you use `ConversationsRepositoryImpl` with a custom datasource |
| `Result<T>`                                      | All repository methods return `Result<T>` (`Success`/`Failure`) — your implementations must do the same                                                                        |


# MessageTemplateUtils & Data Source
Source: https://www.cometchat.com/docs/ui-kit/flutter/customization-datasource

Customize how messages are rendered, what options appear on bubbles, and what formatters are used — all through the central MessageTemplateUtils registry.

`MessageTemplateUtils` is the central registry that defines how each message type is rendered, what options appear on message bubbles, and what text formatters are applied. It replaces the `DataSource` / `ChatConfigurator` pattern used in the Android UI Kit.

## How It Works

In V6, `MessageTemplateUtils` is a static utility class that provides:

* Message templates (how each message type is rendered as a bubble)
* Message options (long-press actions per message type)
* Text formatters (text processing for mentions, links, etc.)
* Message type/category lists (for request builder filtering)

Components call `MessageTemplateUtils` internally to get defaults. You override behavior by passing custom templates, options, or formatters directly to the component.

## Getting Default Templates

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // Get all default templates
    final templates = MessageTemplateUtils.getAllMessageTemplates();

    // Get a specific template
    final textTemplate = MessageTemplateUtils.getTextMessageTemplate();
    final imageTemplate = MessageTemplateUtils.getImageMessageTemplate();

    // Get template by type and category
    final template = MessageTemplateUtils.getMessageTemplate(
      messageType: MessageTypeConstants.text,
      messageCategory: MessageCategoryConstants.message,
    );
    ```
  </Tab>
</Tabs>

## Available Template Methods

| Method                                             | Returns                                        |
| -------------------------------------------------- | ---------------------------------------------- |
| `getTextMessageTemplate()`                         | Template for text messages                     |
| `getImageMessageTemplate()`                        | Template for image messages                    |
| `getVideoMessageTemplate()`                        | Template for video messages                    |
| `getAudioMessageTemplate()`                        | Template for audio messages                    |
| `getFileMessageTemplate()`                         | Template for file messages                     |
| `getGroupActionTemplate()`                         | Template for group action messages             |
| `getFormMessageTemplate()`                         | Template for form messages                     |
| `getCardMessageTemplate()`                         | Template for card messages                     |
| `getSchedulerMessageTemplate()`                    | Template for scheduler messages                |
| `getPollMessageTemplate()`                         | Template for poll messages                     |
| `getStickerMessageTemplate()`                      | Template for sticker messages                  |
| `getCollaborativeDocumentTemplate()`               | Template for collaborative document messages   |
| `getCollaborativeWhiteboardTemplate()`             | Template for collaborative whiteboard messages |
| `getAllMessageTemplates()`                         | All templates combined                         |
| `getMessageTemplate(messageType, messageCategory)` | Template for a specific type/category          |

## Overriding Templates

### Replace All Templates

Pass a complete list of templates to `CometChatMessageList`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      templates: [
        // Your custom text template
        CometChatMessageTemplate(
          type: MessageTypeConstants.text,
          category: MessageCategoryConstants.message,
          contentView: (message, context, alignment, {additionalConfigurations}) {
            return MyCustomTextBubble(message: message as TextMessage);
          },
          options: MessageTemplateUtils.getMessageOptions,
        ),
        // Keep defaults for other types
        MessageTemplateUtils.getImageMessageTemplate(),
        MessageTemplateUtils.getVideoMessageTemplate(),
        MessageTemplateUtils.getAudioMessageTemplate(),
        MessageTemplateUtils.getFileMessageTemplate(),
        MessageTemplateUtils.getGroupActionTemplate(),
      ],
    )
    ```
  </Tab>
</Tabs>

### Add or Override Specific Templates

Use `addTemplate` to merge custom templates with defaults. Templates are keyed by `category_type` — if your template matches an existing key, it overrides the default:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      addTemplate: [
        // Override text message rendering
        CometChatMessageTemplate(
          type: MessageTypeConstants.text,
          category: MessageCategoryConstants.message,
          contentView: (message, context, alignment, {additionalConfigurations}) {
            return MyCustomTextBubble(message: message as TextMessage);
          },
          options: MessageTemplateUtils.getMessageOptions,
        ),
        // Add a new custom message type
        CometChatMessageTemplate(
          type: 'contact',
          category: MessageCategoryConstants.custom,
          contentView: (message, context, alignment, {additionalConfigurations}) {
            return ContactCardBubble(message: message);
          },
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

## Message Options

### Getting Default Options

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // Get options for a specific message type
    final textOptions = MessageTemplateUtils.getTextMessageOptions(
      loggedInUser, messageObject, context, group, additionalConfigurations,
    );

    // Get options for any message (dispatches by type)
    final options = MessageTemplateUtils.getMessageOptions(
      loggedInUser, messageObject, context, group, additionalConfigurations,
    );

    // Get common options (shared across all types)
    final commonOptions = MessageTemplateUtils.getCommonOptions(
      loggedInUser, messageObject, context, group, additionalConfigurations,
    );
    ```
  </Tab>
</Tabs>

### Option Methods by Message Type

| Method                        | Message Type                                   |
| ----------------------------- | ---------------------------------------------- |
| `getTextMessageOptions(...)`  | Text                                           |
| `getImageMessageOptions(...)` | Image                                          |
| `getVideoMessageOptions(...)` | Video                                          |
| `getAudioMessageOptions(...)` | Audio                                          |
| `getFileMessageOptions(...)`  | File                                           |
| `getCommonOptions(...)`       | Shared across all types                        |
| `getMessageOptions(...)`      | Dispatches to the correct type-specific method |

## Text Formatters

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // Get default formatters
    final formatters = MessageTemplateUtils.getDefaultTextFormatters();
    // Returns: [CometChatMentionsFormatter, CometChatEmailFormatter, CometChatPhoneNumberFormatter]
    ```
  </Tab>
</Tabs>

## Type and Category Lists

Used when building custom `MessagesRequestBuilder` instances:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // All registered message types
    final types = MessageTemplateUtils.getAllMessageTypes();

    // All registered message categories
    final categories = MessageTemplateUtils.getAllMessageCategories();
    ```
  </Tab>
</Tabs>

## Comparison with Android's DataSource

| Android                            | Flutter V6                                               | Notes                                                    |
| ---------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- |
| `ChatConfigurator.getDataSource()` | `MessageTemplateUtils` (static)                          | Flutter uses static methods instead of a decorator chain |
| `DataSourceDecorator` pattern      | Template overrides via `templates` / `addTemplate` props | Flutter overrides at the component level, not globally   |
| `CometChatUIKit.getDataSource()`   | `MessageTemplateUtils`                                   | Same functionality, different access pattern             |
| Global decorator chain             | Per-component template lists                             | Flutter's approach is more explicit but less global      |

<Note>
  Unlike Android's `DataSourceDecorator` which applies globally, Flutter's template overrides are scoped to the component instance. To apply the same customization everywhere, pass the same template list to each `CometChatMessageList` instance.
</Note>

## Related

* [Message Template](/docs/ui-kit/flutter/message-template) — Full template structure and examples.
* [Menu & Options](/docs/ui-kit/flutter/customization-menu-options) — Component-level option customization.
* [Text Formatters](/docs/ui-kit/flutter/customization-text-formatters) — Custom text processing.
* [Customization Overview](/docs/ui-kit/flutter/customization-overview) — See all customization categories.


# Menu & Options
Source: https://www.cometchat.com/docs/ui-kit/flutter/customization-menu-options

Customize CometChat Flutter UI Kit message options, long-press menus, composer attachments, and template-level actions.

Components provide long-press context menus (e.g., on conversations or messages) and the message composer provides attachment options. You can customize all of these at the component level or via message templates.

## Message Bubble Options

### Via Message Templates

Each `CometChatMessageTemplate` has an `options` callback that controls what appears when a message is long-pressed:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageTemplate(
      type: MessageTypeConstants.text,
      category: MessageCategoryConstants.message,
      options: (loggedInUser, messageObject, context, group, additionalConfigurations) {
        // Get the default options
        final defaults = MessageTemplateUtils.getTextMessageOptions(
          loggedInUser, messageObject, context, group, additionalConfigurations,
        );
        // Add a custom option at the beginning
        return [
          CometChatMessageOption(
            id: 'translate',
            title: 'Translate',
            icon: Icon(Icons.translate, size: 24),
            onClick: () => translateMessage(messageObject),
          ),
          ...defaults,
        ];
      },
    )
    ```
  </Tab>
</Tabs>

### Replacing All Options

Return only your custom options to completely replace the defaults:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageTemplate(
      type: MessageTypeConstants.text,
      category: MessageCategoryConstants.message,
      options: (loggedInUser, messageObject, context, group, additionalConfigurations) {
        return [
          CometChatMessageOption(
            id: 'bookmark',
            title: 'Bookmark',
            icon: Icon(Icons.bookmark_border, size: 24),
            onClick: () => bookmarkMessage(messageObject),
          ),
          CometChatMessageOption(
            id: 'share',
            title: 'Share',
            icon: Icon(Icons.share, size: 24),
            onClick: () => shareMessage(messageObject),
          ),
        ];
      },
    )
    ```
  </Tab>
</Tabs>

## Message Option Visibility

The `CometChatMessageList` provides boolean properties to hide specific default options without needing to override templates:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      hideCopyMessageOption: true,
      hideDeleteMessageOption: false,
      hideEditMessageOption: false,
      hideReactionOption: false,
      hideReplyInThreadOption: true,
      hideTranslateMessageOption: true,
      hideShareMessageOption: true,
      hideMessageInfoOption: false,
      hideMessagePrivatelyOption: true,
    )
    ```
  </Tab>
</Tabs>

## Composer Attachment Options

The `CometChatMessageComposer` provides boolean properties to control which attachment options appear:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      hideImageAttachmentOption: false,
      hideVideoAttachmentOption: false,
      hideAudioAttachmentOption: true,
      hideFileAttachmentOption: false,
      hidePollsOption: true,
      hideCollaborativeDocumentOption: true,
      hideCollaborativeWhiteboardOption: true,
      hideTakePhotoOption: false,
      hideStickersButton: false,
      hideAttachmentButton: false,
    )
    ```
  </Tab>
</Tabs>

## Conversation Options

For conversations, use `setOptions` and `addOptions` on the `CometChatConversations` component:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // Add custom options to existing defaults
    CometChatConversations(
      addOptions: (context, conversation) {
        return [
          CometChatPopupMenu.MenuItem(
            id: 'pin',
            title: 'Pin Conversation',
            icon: Icon(Icons.push_pin),
            onTap: () => pinConversation(conversation),
          ),
        ];
      },
    )

    // Replace all options
    CometChatConversations(
      setOptions: (context, conversation) {
        return [
          CometChatPopupMenu.MenuItem(
            id: 'archive',
            title: 'Archive',
            icon: Icon(Icons.archive),
            onTap: () => archiveConversation(conversation),
          ),
        ];
      },
    )
    ```
  </Tab>
</Tabs>

## Related

* [Message Template](/docs/ui-kit/flutter/message-template) — Full template structure including options.
* [Message List](/docs/ui-kit/flutter/message-list) — Option visibility properties.
* [Customization Overview](/docs/ui-kit/flutter/customization-overview) — See all customization categories.


# Customization Overview
Source: https://www.cometchat.com/docs/ui-kit/flutter/customization-overview

Understand the Widget + BLoC + Template architecture and discover all customization entry points in the CometChat Flutter UI Kit.

Every component in the Flutter UI Kit follows a layered architecture built on BLoC for state management and declarative widget composition. Understanding these layers is the key to unlocking deep customization without rebuilding components from scratch.

## Architecture

Each component is composed of collaborating layers:

| Layer     | Role                                                                                          | Example Class              |
| --------- | --------------------------------------------------------------------------------------------- | -------------------------- |
| Widget    | Renders the UI, accepts configuration props, and exposes builder callbacks for customization. | `CometChatConversations`   |
| BLoC      | Manages data fetching, state transitions, and business logic via streams and events.          | `ConversationsBloc`        |
| Templates | Define how each message type is rendered as a bubble (message list only).                     | `CometChatMessageTemplate` |

```
┌─────────────────────────────────┐
│   CometChatConversations        │
│   (Widget Layer)                │
│                                 │
│   ┌───────────────────────┐     │
│   │  ConversationsBloc    │     │
│   │  (State Management)   │     │
│   └───────────────────────┘     │
│                                 │
│   ┌───────────────────────┐     │
│   │  Builder Callbacks    │     │
│   │  (View Customization) │     │
│   └───────────────────────┘     │
└─────────────────────────────────┘
```

## Accessing Internal Layers

Components expose their BLoC via constructor parameters:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // Provide a custom BLoC instance
    CometChatConversations(
      conversationsBloc: myCustomConversationsBloc,
    )

    // Or use the stateCallBack to access the controller
    CometChatMessageList(
      user: user,
      stateCallBack: (controller) {
        // Access the controller for programmatic operations
      },
    )
    ```
  </Tab>
</Tabs>

## Customization Categories

The UI Kit provides seven categories of customization entry points. Each category has a dedicated guide:

<CardGroup>
  <Card title="View Slots" href="/ui-kit/flutter/customization-view-slots">
    Replace specific regions of a component's UI (leading view, title, subtitle, trailing view) using builder callbacks.
  </Card>

  <Card title="Styles" href="/ui-kit/flutter/component-styling">
    Customize visual appearance using ThemeData extensions or component-level style objects.
  </Card>

  <Card title="BLoC & Data" href="/ui-kit/flutter/customization-bloc-data">
    Configure data fetching with RequestBuilders, provide custom BLoC instances, override repositories and datasources.
  </Card>

  <Card title="State Views" href="/ui-kit/flutter/customization-state-views">
    Replace the default empty, error, and loading state views with custom widgets.
  </Card>

  <Card title="Text Formatters" href="/ui-kit/flutter/customization-text-formatters">
    Create custom text processors for hashtags, mentions, links, or any pattern using the CometChatTextFormatter API.
  </Card>

  <Card title="Menu & Options" href="/ui-kit/flutter/customization-menu-options">
    Add, replace, or extend long-press actions and composer attachment options on components.
  </Card>

  <Card title="Message Templates" href="/ui-kit/flutter/customization-datasource">
    Customize how messages are rendered using MessageTemplateUtils — the central registry for message templates, options, and formatters.
  </Card>
</CardGroup>

## What's Next

If you're new to customization, start with [View Slots](/docs/ui-kit/flutter/customization-view-slots) for quick UI changes, or [Styles](/docs/ui-kit/flutter/component-styling) to match your brand. For advanced use cases like custom message types or global behavior changes, head to [Message Templates](/docs/ui-kit/flutter/customization-datasource).


# State Views
Source: https://www.cometchat.com/docs/ui-kit/flutter/customization-state-views

Replace CometChat Flutter UI Kit empty, error, loading, and chat greeting state views with custom Flutter widgets.

Components display state views when the list is empty, an error occurs, or data is loading. You can replace these with custom widgets.

## Replacing State Views

Each state view property accepts a `WidgetBuilder` — a function that takes `BuildContext` and returns a `Widget`.

| Property                | State                                          |
| ----------------------- | ---------------------------------------------- |
| `emptyStateView`        | No data to display                             |
| `errorStateView`        | An error occurred during data fetching         |
| `loadingStateView`      | Data is being fetched                          |
| `emptyChatGreetingView` | Empty chat with a greeting (message list only) |

## Example: Custom Empty State

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      emptyStateView: (context) {
        return Center(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              Icon(Icons.chat_bubble_outline, size: 64, color: Colors.grey),
              SizedBox(height: 16),
              Text(
                'No conversations yet',
                style: TextStyle(fontSize: 18, color: Colors.grey[700]),
              ),
              SizedBox(height: 8),
              Text(
                'Start a new chat to get going',
                style: TextStyle(fontSize: 14, color: Colors.grey),
              ),
            ],
          ),
        );
      },
    )
    ```
  </Tab>
</Tabs>

## Example: Custom Error State

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      errorStateView: (context) {
        return Center(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              Icon(Icons.error_outline, size: 48, color: Colors.red),
              SizedBox(height: 12),
              Text('Something went wrong'),
              SizedBox(height: 16),
              ElevatedButton(
                onPressed: () {
                  // Trigger reload
                },
                child: Text('Try Again'),
              ),
            ],
          ),
        );
      },
    )
    ```
  </Tab>
</Tabs>

## Example: Custom Loading State

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      loadingStateView: (context) {
        return Center(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              CircularProgressIndicator(color: Color(0xFF6851D6)),
              SizedBox(height: 16),
              Text('Loading messages...'),
            ],
          ),
        );
      },
    )
    ```
  </Tab>
</Tabs>

## Example: Empty Chat Greeting

The message list supports a special `emptyChatGreetingView` for new conversations:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      emptyChatGreetingView: (context) {
        return Center(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              Icon(Icons.waving_hand, size: 48, color: Color(0xFF6851D6)),
              SizedBox(height: 16),
              Text('Say hello! 👋', style: TextStyle(fontSize: 18)),
            ],
          ),
        );
      },
    )
    ```
  </Tab>
</Tabs>

## Lifecycle Callbacks

Use lifecycle callbacks to run custom logic when states change:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      onLoad: (messages) {
        debugPrint('Loaded ${messages.length} messages');
      },
      onEmpty: () {
        debugPrint('No messages found');
      },
      onError: (e) {
        debugPrint('Error: ${e.message}');
      },
    )
    ```
  </Tab>
</Tabs>

## Related

* [Customization Overview](/docs/ui-kit/flutter/customization-overview) — See all customization categories.


# Text Formatters
Source: https://www.cometchat.com/docs/ui-kit/flutter/customization-text-formatters

Create custom text processors for hashtags, mentions, links, or any pattern using the CometChatTextFormatter API.

Text formatters let you process message text with tracking characters, suggestion lists, and rich text transformations. Use them to add hashtag detection, custom mentions, link previews, or any text pattern processing.

## CometChatTextFormatter

The `CometChatTextFormatter` abstract class is the base for all formatters. Its constructor takes a `String trackingCharacter` that triggers the formatter when typed in the composer (e.g., `@` for mentions, `#` for hashtags).

### Key Override Methods

| Method                                                               | Purpose                                                                                             |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `search(String query)`                                               | Called when the user types after the tracking character. Use this to fetch and display suggestions. |
| `onScrollToBottom()`                                                 | Called when the user scrolls to the bottom of the suggestion list. Use for pagination.              |
| `buildInputSpan(BuildContext, BaseMessage)`                          | Apply rich text formatting in the message composer.                                                 |
| `buildMessageBubbleSpan(BuildContext, BaseMessage, BubbleAlignment)` | Apply rich text formatting in message bubbles.                                                      |
| `buildConversationSpan(BuildContext, BaseMessage)`                   | Apply formatting in the conversations list last message preview.                                    |
| `handlePreMessageSend(BaseMessage)`                                  | Modify a message before it's sent (attach metadata, transform text).                                |

## Suggestion System

The formatter provides a built-in suggestion dropdown:

| Property/Method                              | Description                                            |
| -------------------------------------------- | ------------------------------------------------------ |
| `setSuggestionItems(List<SuggestionItem>)`   | Set the list of suggestions to display                 |
| `setShowLoadingIndicator(bool)`              | Show/hide a loading spinner in the suggestion dropdown |
| `onItemClick(SuggestionItem, User?, Group?)` | Called when the user selects a suggestion item         |

## Example: Custom Hashtag Formatter

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class HashtagFormatter extends CometChatTextFormatter {
      HashtagFormatter() : super(trackingCharacter: '#');

      @override
      void search(String query) {
        // Fetch hashtag suggestions based on query
        final suggestions = fetchHashtags(query);
        setSuggestionItems(suggestions);
      }

      @override
      void onScrollToBottom() {
        // Load more suggestions
      }

      @override
      InlineSpan? buildMessageBubbleSpan(
        BuildContext context,
        BaseMessage message,
        BubbleAlignment alignment,
      ) {
        // Apply blue color to #hashtags in message bubbles
        return _applyHashtagSpans(message.text);
      }

      @override
      InlineSpan? buildConversationSpan(
        BuildContext context,
        BaseMessage message,
      ) {
        return _applyHashtagSpans(message.text);
      }
    }
    ```
  </Tab>
</Tabs>

## Registering Formatters

Register formatters on a component using `textFormatters`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      textFormatters: [
        CometChatMentionsFormatter(),
        HashtagFormatter(),
      ],
    )
    ```
  </Tab>
</Tabs>

Or on the message composer:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      textFormatters: [
        CometChatMentionsFormatter(),
        HashtagFormatter(),
      ],
    )
    ```
  </Tab>
</Tabs>

## Built-in Formatters

The UI Kit includes several built-in formatters:

| Formatter                       | Tracking Character | Description                                                                |
| ------------------------------- | ------------------ | -------------------------------------------------------------------------- |
| `CometChatMentionsFormatter`    | `@`                | Handles @mention detection, user suggestion lists, and styled highlighting |
| `CometChatEmailFormatter`       | —                  | Detects and links email addresses                                          |
| `CometChatPhoneNumberFormatter` | —                  | Detects and links phone numbers                                            |
| `MarkdownTextFormatter`         | —                  | Renders markdown formatting (bold, italic, code, etc.)                     |

### Default Formatters

`MessageTemplateUtils.getDefaultTextFormatters()` returns the default set of formatters used by all components:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    final defaults = MessageTemplateUtils.getDefaultTextFormatters();
    // Returns: [CometChatMentionsFormatter, CometChatEmailFormatter, CometChatPhoneNumberFormatter]
    ```
  </Tab>
</Tabs>

## Customizing the Mentions Formatter

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    final mentionsFormatter = CometChatMentionsFormatter();

    CometChatMessageList(
      user: user,
      textFormatters: [mentionsFormatter],
    )
    ```
  </Tab>
</Tabs>

See the [Mentions Formatter Guide](/docs/ui-kit/flutter/mentions-formatter-guide) for detailed styling and behavior customization.

## Related

* [Mentions Formatter Guide](/docs/ui-kit/flutter/mentions-formatter-guide) — Built-in mentions formatter reference.
* [Shortcut Formatter Guide](/docs/ui-kit/flutter/shortcut-formatter-guide) — Shortcut text replacement formatter.
* [Customization Overview](/docs/ui-kit/flutter/customization-overview) — See all customization categories.


# View Slots
Source: https://www.cometchat.com/docs/ui-kit/flutter/customization-view-slots

Replace specific regions of a component's UI using builder callbacks without rebuilding the entire component.

View Slots let you swap out specific parts of a component — the avatar area, title, subtitle, trailing section, or the entire row — while keeping the rest of the component's behavior intact.

## The Builder Callback Pattern

Flutter UI Kit components accept nullable builder callbacks for each customizable region. Each callback receives the relevant data model and returns a `Widget?`. Return `null` to fall back to the default view.

```dart theme={null}
Widget? Function(BuildContext context, DataModel model)?
```

## Available View Slots

### List Components (Conversations, Users, Groups, Group Members)

| Property       | Region                           | Signature                               |
| -------------- | -------------------------------- | --------------------------------------- |
| `leadingView`  | Left section (avatar)            | `Widget? Function(BuildContext, Model)` |
| `titleView`    | Title text                       | `Widget? Function(BuildContext, Model)` |
| `subtitleView` | Subtitle text                    | `Widget? Function(BuildContext, Model)` |
| `trailingView` | Right section (timestamp, badge) | `Widget? Function(BuildContext, Model)` |

### Message List

| Property      | Region                                    | Signature                                               |
| ------------- | ----------------------------------------- | ------------------------------------------------------- |
| `headerView`  | Above the message list                    | `Widget? Function(BuildContext, {User?, Group?, int?})` |
| `footerView`  | Below the message list                    | `Widget? Function(BuildContext, {User?, Group?, int?})` |
| `templates`   | All message bubble templates              | `List<CometChatMessageTemplate>`                        |
| `addTemplate` | Additional templates merged with defaults | `List<CometChatMessageTemplate>`                        |

### Message Template Slots

Each `CometChatMessageTemplate` has its own view slots for the bubble structure:

| Property         | Region                                   | Signature                                                                                   |
| ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------- |
| `headerView`     | Above the bubble content                 | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)`                              |
| `contentView`    | Main bubble content                      | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment, {AdditionalConfigurations?})` |
| `footerView`     | Below the bubble                         | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)`                              |
| `bottomView`     | Below the content, inside the bubble     | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)`                              |
| `statusInfoView` | Timestamp and receipts                   | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)`                              |
| `replyView`      | Quoted reply preview                     | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)`                              |
| `threadView`     | Thread reply indicator                   | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)`                              |
| `bubbleView`     | Entire bubble (replaces all other slots) | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)`                              |

## Example: Custom Leading View on Conversations

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      leadingView: (context, conversation) {
        final name = conversation.conversationWith?.name ?? '';
        return CircleAvatar(
          backgroundColor: Color(0xFF6851D6),
          child: Text(
            name.isNotEmpty ? name[0].toUpperCase() : '?',
            style: TextStyle(color: Colors.white, fontSize: 18),
          ),
        );
      },
    )
    ```
  </Tab>
</Tabs>

## Example: Custom Subtitle View on Conversations

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      subtitleView: (context, conversation) {
        final lastMessage = conversation.lastMessage;
        String subtitle;
        if (lastMessage is TextMessage) {
          subtitle = lastMessage.text;
        } else if (lastMessage is MediaMessage) {
          subtitle = '📎 ${lastMessage.attachment?.fileExtension ?? "Media"}';
        } else {
          subtitle = 'New conversation';
        }
        return Text(
          subtitle,
          maxLines: 1,
          overflow: TextOverflow.ellipsis,
        );
      },
    )
    ```
  </Tab>
</Tabs>

## Example: Custom Header View on Message List

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      headerView: (context, {user, group, parentMessageId}) {
        return Container(
          padding: EdgeInsets.symmetric(horizontal: 16, vertical: 8),
          color: Color(0xFFEDEAFA),
          child: Row(
            children: [
              Chip(label: Text('📌 Pinned Messages')),
              SizedBox(width: 8),
              Chip(label: Text('🔗 Saved Links')),
            ],
          ),
        );
      },
    )
    ```
  </Tab>
</Tabs>

## Slot-Level vs Full Replacement

Use individual slot properties (`leadingView`, `titleView`, `subtitleView`, `trailingView`) when you want to customize one region while keeping the default layout for everything else. Use `bubbleView` on a `CometChatMessageTemplate` when you need complete control over the entire message bubble.

<Warning>
  When you set `bubbleView` on a template, all other template slots (`headerView`, `contentView`, `footerView`, etc.) are ignored since the entire bubble is replaced.
</Warning>

## Related

* [Message Template](/docs/ui-kit/flutter/message-template) — Full template structure for message bubbles.
* [Customization Overview](/docs/ui-kit/flutter/customization-overview) — See all customization categories.


# Events
Source: https://www.cometchat.com/docs/ui-kit/flutter/events

Handle CometChat Flutter UI Kit events for users, groups, messages, conversations, calls, and UI-level interactions.

## Overview

Events allow for a decoupled, flexible architecture where different parts of the application can interact without having to directly reference each other. This makes it easier to create complex, interactive experiences, as well as to extend and customize the functionality provided by the CometChat UI Kit.

> The event system is identical between V5 and V6. All event classes, listeners, and APIs work the same way.

### User Events

`CometChatUserEvents` emit events when the logged-in user executes actions on another user.

1. `ccUserBlocked`: Triggered when the logged-in user blocks another user.
2. `ccUserUnblocked`: Triggered when the logged-in user unblocks another user.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    class _YourScreenState extends State<YourScreen> with CometChatUserEventListener {
      @override
      void initState() {
        super.initState();
        CometChatUserEvents.addUsersListener("listenerId", this);
      }

      @override
      void dispose() {
        super.dispose();
        CometChatUserEvents.removeUsersListener("listenerId");
      }

      @override
      void ccUserBlocked(User user) {
        // Handle user blocked
      }

      @override
      void ccUserUnblocked(User user) {
        // Handle user unblocked
      }

      @override
      Widget build(BuildContext context) {
        return const Placeholder();
      }
    }
    ```
  </Tab>
</Tabs>

***

### Group Events

`CometChatGroupEvents` emits events when the logged-in user performs actions related to groups.

1. `ccGroupCreated`: Triggered when the logged-in user creates a group.
2. `ccGroupDeleted`: Triggered when the logged-in user deletes a group.
3. `ccGroupLeft`: Triggered when the logged-in user leaves a group.
4. `ccGroupMemberScopeChanged`: Triggered when the logged-in user changes the scope of another group member.
5. `ccGroupMemberBanned`: Triggered when the logged-in user bans a group member.
6. `ccGroupMemberKicked`: Triggered when the logged-in user kicks a group member.
7. `ccGroupMemberUnbanned`: Triggered when the logged-in user unbans a user.
8. `ccGroupMemberJoined`: Triggered when the logged-in user joins a group.
9. `ccGroupMemberAdded`: Triggered when the logged-in user adds new members.
10. `ccOwnershipChanged`: Triggered when the logged-in user transfers ownership.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    class _YourScreenState extends State<YourScreen> with CometChatGroupEventListener {
      @override
      void initState() {
        super.initState();
        CometChatGroupEvents.addGroupsListener("listenerId", this);
      }

      @override
      void dispose() {
        super.dispose();
        CometChatGroupEvents.removeGroupsListener("listenerId");
      }

      @override
      void ccGroupCreated(Group group) {
        // Handle group created
      }

      @override
      void ccGroupDeleted(Group group) {
        // Handle group deleted
      }

      @override
      Widget build(BuildContext context) {
        return const Placeholder();
      }
    }
    ```
  </Tab>
</Tabs>

***

### Message Events

`CometChatMessageEvents` emits events related to messages.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    class _YourScreenState extends State<YourScreen> with CometChatMessageEventListener {
      @override
      void initState() {
        super.initState();
        CometChatMessageEvents.addMessagesListener("listenerId", this);
      }

      @override
      void dispose() {
        super.dispose();
        CometChatMessageEvents.removeMessagesListener("listenerId");
      }

      @override
      Widget build(BuildContext context) {
        return const Placeholder();
      }
    }
    ```
  </Tab>
</Tabs>

***

### Conversation Events

`CometChatConversationEvents` emits events related to conversations.

1. `ccConversationDeleted`: Triggered when a conversation is deleted.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    class _YourScreenState extends State<YourScreen> with CometChatConversationEventListener {
      @override
      void initState() {
        super.initState();
        CometChatConversationEvents.addConversationListListener("listenerId", this);
      }

      @override
      void dispose() {
        super.dispose();
        CometChatConversationEvents.removeConversationListListener("listenerId");
      }

      @override
      void ccConversationDeleted(Conversation conversation) {
        // Handle conversation deleted
      }

      @override
      Widget build(BuildContext context) {
        return const Placeholder();
      }
    }
    ```
  </Tab>
</Tabs>

***

### UI Events

`CometChatUIEvents` emits `CometChatUIEventListener` callbacks for UI-level actions such as panel visibility, active chat changes, and card action taps. Add a listener with `CometChatUIEvents.addUiListener(listenerId, this)` and remove it in `dispose()`.

**Event types:**

| Event                                                                   | Description                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `showPanel(id, uiPosition, child)`                                      | Triggered to show an additional UI panel with custom elements.                                                                                                                                                                                                  |
| `hidePanel(id, uiPosition)`                                             | Triggered to hide a previously shown UI panel.                                                                                                                                                                                                                  |
| `ccActiveChatChanged(id, lastMessage, user, group, unreadMessageCount)` | Triggered when the active chat changes.                                                                                                                                                                                                                         |
| `openChat(user, group)`                                                 | Triggered to open a chat with a specific user or group.                                                                                                                                                                                                         |
| `ccComposeMessage(text, status)`                                        | Triggered when composing a message with a specific text and status.                                                                                                                                                                                             |
| `onAiFeatureTapped(user, group)`                                        | Triggered when an AI feature is tapped for a specific user or group.                                                                                                                                                                                            |
| `ccCardActionClicked(message, action)`                                  | Triggered when a user taps an interactive element (button/link) inside a [card message](/docs/sdk/flutter/send-message#card-message) (`CardMessage`) or an AI agent card (`AIAssistantMessage`). `action` is typed `dynamic`; cast it to `CometChatCardActionEvent`. |

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class _YourScreenState extends State<YourScreen> with CometChatUIEventListener {
      final String listenerId = "unique_listener_id";

      @override
      void initState() {
        super.initState();
        CometChatUIEvents.addUiListener(listenerId, this);
      }

      @override
      void dispose() {
        CometChatUIEvents.removeUiListener(listenerId);
        super.dispose();
      }

      @override
      void ccCardActionClicked(BaseMessage message, dynamic action) {
        // message -> CardMessage (standalone) or AIAssistantMessage (agent card)
        if (action is CometChatCardActionEvent) {
          debugPrint("Action: ${action.action}");
          debugPrint("Element ID: ${action.elementId}");
          debugPrint("Card JSON: ${action.cardJson}");
          // Handle navigation, API calls, etc.
        }
      }

      @override
      Widget build(BuildContext context) => const Placeholder();
    }
    ```
  </Tab>
</Tabs>

<Note>
  The UI Kit renders card bubbles automatically (`CometChatCardBubble`) and emits `ccCardActionClicked` when a user taps an action inside one — so a single subscriber handles every card action across your app. `message` is a `CardMessage` for standalone [card messages](/docs/sdk/flutter/send-message#card-message) and an `AIAssistantMessage` for cards embedded in AI agent replies. Cast `action` to `CometChatCardActionEvent` to read its `action`, `elementId`, and `cardJson`. See also [Methods → UI Events — Card Actions](/docs/ui-kit/flutter/methods#ui-events--card-actions).
</Note>


# Extensions
Source: https://www.cometchat.com/docs/ui-kit/flutter/extensions

Use CometChat Flutter UI Kit extensions for stickers, polls, collaborative tools, reactions, smart replies, and link previews.

## Overview

CometChat's UI Kit comes with built-in support for a wide variety of extensions that provide additional functionality. These extensions enhance the chatting experience, making it more interactive, secure, and efficient.

Activating any of the extensions in CometChat is a simple process done through your application's dashboard. Refer to our guide for detailed information on [Extensions](/docs/fundamentals/extensions-overview).

> **V6 Architecture Change:** In V5, extensions used a decorator/chain-of-responsibility pattern with `*Extension` and `*ExtensionDecorator` classes that wrapped the `DataSource` interface. V6 removes this entire pattern. Extension behavior is now handled directly by `MessageTemplateUtils` static methods. No registration is needed — just enable extensions in your CometChat Dashboard and they work automatically.

## Built-in Extensions

### Stickers

The Stickers extension allows users to express their emotions more creatively with pre-designed stickers.

Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the [Message Composer](/docs/ui-kit/flutter/message-composer) widget.

### Polls

The Polls extension enhances group discussions by allowing users to create polls with predefined answers.

Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/docs/ui-kit/flutter/message-composer) widget.

### Collaborative Whiteboard

The Collaborative Whiteboard extension facilitates real-time collaboration on a shared digital whiteboard.

Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/docs/ui-kit/flutter/message-composer) widget.

### Collaborative Document

Users can work together on a shared document with the Collaborative Document extension.

Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/docs/ui-kit/flutter/message-composer) widget.

### Message Translation

The Message Translation extension translates any message into your local locale, eliminating language barriers.

Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of [MessageList Widget](/docs/ui-kit/flutter/message-list).

### Link Preview

The Link Preview extension provides a summary of URLs shared in the chat, including title, description, and thumbnail.

Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the Message Bubble of [MessageList Widget](/docs/ui-kit/flutter/message-list).

### Thumbnail Generation

The Thumbnail Generation extension automatically creates smaller preview images for shared images, reducing bandwidth usage.

Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the Message Bubble of [MessageList Widget](/docs/ui-kit/flutter/message-list).

## V6 Extension Architecture

### What Changed

| Aspect        | V5                                                                               | V6                                            |
| ------------- | -------------------------------------------------------------------------------- | --------------------------------------------- |
| Registration  | `UIKitSettings.extensions = CometChatUIKitChatExtensions.getDefaultExtensions()` | Not needed — built-in                         |
| Architecture  | Decorator chain (up to 10 layers)                                                | `MessageTemplateUtils` static methods (1 hop) |
| Startup cost  | 9 `isExtensionEnabled()` network calls                                           | None                                          |
| Files removed | —                                                                                | 27 files (\~7000+ lines)                      |
| UI widgets    | Preserved                                                                        | Preserved (bubbles, configs, styles)          |

### What Was Removed

* All `*Extension` classes (e.g., `StickersExtension`, `PollsExtension`)
* All `*ExtensionDecorator` classes (e.g., `StickersExtensionDecorator`)
* `ChatConfigurator`, `DataSource` interface, `ExtensionsDataSource`
* `CometChatUIKitChatExtensions`, `CometChatUIKitChatAIFeatures`
* `CometChatUIKit.getDataSource()` method

### What Was Preserved

All extension UI widgets remain:

* `CometChatStickerBubble`, `CometChatStickerKeyboard`
* `CometChatPollsBubble`, `CometChatCreatePoll`
* `CometChatLinkPreviewBubble`
* `CometChatCollaborativeBubble`, `CometChatCollaborativeWebView`
* `MessageTranslationBubble`
* All configuration and style classes


# Conversation List + Message View
Source: https://www.cometchat.com/docs/ui-kit/flutter/flutter-conversation

Build a two-panel CometChat Flutter UI Kit layout with a conversation list, active message view, headers, lists, and composer.

The Conversation List + Message View layout provides a seamless two-panel chat interface. This layout allows users to switch between conversations while keeping the active chat open.

## Integration

### Step 1: Create the Conversations Screen

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    class ConversationsScreen extends StatelessWidget {
      const ConversationsScreen({super.key});

      @override
      Widget build(BuildContext context) {
        return Scaffold(
          appBar: AppBar(title: const Text('Conversations')),
          body: CometChatConversations(
            onItemTap: (conversation) {
              _openChat(context, conversation);
            },
          ),
        );
      }

      void _openChat(BuildContext context, Conversation conversation) {
        User? user;
        Group? group;

        if (conversation.conversationType == 'user') {
          user = conversation.conversationWith as User;
        } else {
          group = conversation.conversationWith as Group;
        }

        Navigator.push(
          context,
          MaterialPageRoute(
            builder: (_) => ChatScreen(user: user, group: group),
          ),
        );
      }
    }
    ```
  </Tab>
</Tabs>

### Step 2: Create the Chat Screen

Use the same `MessagesScreen` pattern from [One-to-One Chat](/docs/ui-kit/flutter/flutter-one-to-one-chat#step-2-render-the-messages-component):

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class ChatScreen extends StatelessWidget {
      final User? user;
      final Group? group;

      const ChatScreen({super.key, this.user, this.group});

      @override
      Widget build(BuildContext context) {
        return Scaffold(
          appBar: CometChatMessageHeader(user: user, group: group),
          body: SafeArea(
            child: Column(
              children: [
                Expanded(child: CometChatMessageList(user: user, group: group)),
                CometChatMessageComposer(user: user, group: group),
              ],
            ),
          ),
        );
      }
    }
    ```
  </Tab>
</Tabs>

### Step 3: Complete Example

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    void main() {
      runApp(const MyApp());
    }

    class MyApp extends StatelessWidget {
      const MyApp({super.key});

      @override
      Widget build(BuildContext context) {
        return MaterialApp(
          title: 'CometChat V6',
          theme: ThemeData(useMaterial3: true),
          home: const InitPage(),
        );
      }
    }

    class InitPage extends StatefulWidget {
      const InitPage({super.key});

      @override
      State<InitPage> createState() => _InitPageState();
    }

    class _InitPageState extends State<InitPage> {
      bool _ready = false;

      @override
      void initState() {
        super.initState();
        _init();
      }

      Future<void> _init() async {
        UIKitSettings settings = (UIKitSettingsBuilder()
              ..subscriptionType = CometChatSubscriptionType.allUsers
              ..autoEstablishSocketConnection = true
              ..region = "REGION"
              ..appId = "APP_ID"
              ..authKey = "AUTH_KEY")
            .build();

        CometChatUIKit.init(
          uiKitSettings: settings,
          onSuccess: (_) {
            CometChatUIKit.login("cometchat-uid-1", onSuccess: (_) {
              setState(() => _ready = true);
            }, onError: (e) {});
          },
          onError: (e) {},
        );
      }

      @override
      Widget build(BuildContext context) {
        if (!_ready) {
          return const Scaffold(body: Center(child: CircularProgressIndicator()));
        }
        return const ConversationsScreen();
      }
    }
    ```
  </Tab>
</Tabs>


# Building A One To One/Group Chat Experience
Source: https://www.cometchat.com/docs/ui-kit/flutter/flutter-one-to-one-chat

Build one-to-one and group chat screens in CometChat Flutter UI Kit with message headers, message lists, composers, and user lookup.

The One-to-One Chat feature provides a streamlined direct messaging interface, ideal for support chats, dating apps, and private messaging platforms.

***

### Step 1: Render the Message View

Fetch the target user and display the messaging screen. V6 uses the same `CometChatUIKit` initialization but with BLoC-powered widgets.

```dart main.dart theme={null}
@override
Widget build(BuildContext context) {
  return Scaffold(
    body: SafeArea(
      child: FutureBuilder<User>(
        future: fetchCometChatUser("cometchat-uid-2"),
        builder: (context, snapshot) {
          if (snapshot.connectionState == ConnectionState.waiting) {
            return const Center(child: CircularProgressIndicator());
          } else if (snapshot.hasError) {
            return Center(child: Text("Error: ${snapshot.error}"));
          } else if (snapshot.hasData) {
            return MessagesScreen(user: snapshot.data!);
          } else {
            return const Center(child: Text("User not found"));
          }
        },
      ),
    ),
  );
}
```

#### Full Example: main.dart

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
    import 'messages_screen.dart';
    import 'cometchat_config.dart';
    import 'dart:async';

    void main() => runApp(const MyApp());

    class MyApp extends StatelessWidget {
      const MyApp({super.key});

      @override
      Widget build(BuildContext context) {
        return MaterialApp(
          title: 'CometChat V6 UI Kit',
          theme: ThemeData(
            colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
            useMaterial3: true,
          ),
          home: const Home(),
        );
      }
    }

    class Home extends StatelessWidget {
      const Home({super.key});

      Future<void> _initializeAndLogin() async {
        final settings = UIKitSettingsBuilder()
          ..subscriptionType = CometChatSubscriptionType.allUsers
          ..autoEstablishSocketConnection = true
          ..appId = CometChatConfig.appId
          ..region = CometChatConfig.region
          ..authKey = CometChatConfig.authKey;

        await CometChatUIKit.init(uiKitSettings: settings.build());
        await CometChatUIKit.login(
          'cometchat-uid-1',
          onSuccess: (_) => debugPrint('Login Successful'),
          onError: (err) => throw Exception('Login Failed: $err'),
        );
      }

      @override
      Widget build(BuildContext context) {
        return FutureBuilder<void>(
          future: _initializeAndLogin(),
          builder: (ctx, snap) {
            if (snap.connectionState != ConnectionState.done) {
              return const Scaffold(
                body: SafeArea(child: Center(child: CircularProgressIndicator())),
              );
            }
            if (snap.hasError) {
              return Scaffold(
                body: SafeArea(
                  child: Center(child: Text('Error:\n${snap.error}', textAlign: TextAlign.center)),
                ),
              );
            }
            return const MessagesPage();
          },
        );
      }
    }

    class MessagesPage extends StatelessWidget {
      const MessagesPage({super.key});

      Future<User> fetchCometChatUser(String uid) async {
        final completer = Completer<User>();
        CometChat.getUser(
          uid,
          onSuccess: (user) => completer.complete(user),
          onError: (error) => completer.completeError(error),
        );
        return completer.future;
      }

      @override
      Widget build(BuildContext context) {
        return Scaffold(
          body: SafeArea(
            child: FutureBuilder<User>(
              future: fetchCometChatUser("cometchat-uid-2"),
              builder: (context, snapshot) {
                if (snapshot.connectionState == ConnectionState.waiting) {
                  return const Center(child: CircularProgressIndicator());
                } else if (snapshot.hasError) {
                  return Center(child: Text("Error: ${snapshot.error}"));
                } else if (snapshot.hasData) {
                  return MessagesScreen(user: snapshot.data!);
                } else {
                  return const Center(child: Text("User not found"));
                }
              },
            ),
          ),
        );
      }
    }
    ```
  </Tab>
</Tabs>

### Step 2: Render the Messages Component

Compose the messaging view using:

* [Message Header](/docs/ui-kit/flutter/message-header)
* [Message List](/docs/ui-kit/flutter/message-list)
* [Message Composer](/docs/ui-kit/flutter/message-composer)

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    class MessagesScreen extends StatefulWidget {
      final User? user;
      final Group? group;

      const MessagesScreen({Key? key, this.user, this.group}) : super(key: key);

      @override
      State<MessagesScreen> createState() => _MessagesScreenState();
    }

    class _MessagesScreenState extends State<MessagesScreen> {
      @override
      Widget build(BuildContext context) {
        return Scaffold(
          appBar: CometChatMessageHeader(
            user: widget.user,
            group: widget.group,
          ),
          body: SafeArea(
            child: Column(
              children: [
                Expanded(
                  child: CometChatMessageList(
                    user: widget.user,
                    group: widget.group,
                  ),
                ),
                CometChatMessageComposer(
                  user: widget.user,
                  group: widget.group,
                ),
              ],
            ),
          ),
        );
      }
    }
    ```
  </Tab>
</Tabs>

***

### Step 3: Run the App

```
flutter run
```

This launches the app with the one-to-one chat interface featuring the message header, list, and composer.

***

## Key V6 Differences

| Aspect           | V5                                                    | V6                                                      |
| ---------------- | ----------------------------------------------------- | ------------------------------------------------------- |
| Composite widget | `CometChatMessages` wraps header + list + composer    | No composite — compose individually                     |
| State management | GetX controllers                                      | BLoC pattern (`MessageListBloc`, `MessageComposerBloc`) |
| Extensions       | `CometChatUIKitChatExtensions.getDefaultExtensions()` | Extensions handled via `MessageTemplateUtils`           |
| Rich text        | Not available                                         | Built-in rich text formatting and code blocks           |

***

## Next Steps

* [Advanced Customizations](/docs/ui-kit/flutter/theme-introduction) — Personalize the chat UI to align with your brand.
* [Message List](/docs/ui-kit/flutter/message-list) — Customize message display and behavior.
* [Message Composer](/docs/ui-kit/flutter/message-composer) — Configure rich text, attachments, and audio recording.


# Building A Messaging UI With Tabs, Sidebar, And Message View
Source: https://www.cometchat.com/docs/ui-kit/flutter/flutter-tab-based-chat

Build a tab-based CometChat Flutter UI Kit chat UI with conversations, users, groups, sidebar navigation, and message view.

This guide walks you through creating a tab-based messaging UI using Flutter and CometChat V6 UIKit. The UI includes sections for Chats, Users, and Groups, allowing seamless navigation.

***

## User Interface Preview

This layout consists of:

1. Sidebar (Conversation List) — Displays recent conversations with active users and groups.
2. Message View — Shows the selected chat with real-time messages.
3. Message Input Box — Allows users to send messages seamlessly.

***

### Step 1: Render the Tab Component

Set up initialization and the tab-based layout. In V6, all list widgets (`CometChatConversations`, `CometChatUsers`, `CometChatGroups`) are powered by BLoC.

#### Full Example: main.dart

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
    import 'messages_screen.dart';
    import 'cometchat_config.dart';

    void main() => runApp(const MyApp());

    class MyApp extends StatelessWidget {
      const MyApp({super.key});

      @override
      Widget build(BuildContext context) {
        return MaterialApp(
          title: 'CometChat V6 UI Kit',
          theme: ThemeData(
            colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
            useMaterial3: true,
          ),
          home: const Home(),
        );
      }
    }

    class Home extends StatelessWidget {
      const Home({super.key});

      Future<void> _initializeAndLogin() async {
        final settings = UIKitSettingsBuilder()
          ..subscriptionType = CometChatSubscriptionType.allUsers
          ..autoEstablishSocketConnection = true
          ..appId = CometChatConfig.appId
          ..region = CometChatConfig.region
          ..authKey = CometChatConfig.authKey;

        await CometChatUIKit.init(uiKitSettings: settings.build());
        await CometChatUIKit.login(
          'cometchat-uid-1',
          onSuccess: (_) => debugPrint('Login Successful'),
          onError: (err) => throw Exception('Login Failed: $err'),
        );
      }

      @override
      Widget build(BuildContext context) {
        return FutureBuilder<void>(
          future: _initializeAndLogin(),
          builder: (ctx, snap) {
            if (snap.connectionState != ConnectionState.done) {
              return const Scaffold(
                body: SafeArea(child: Center(child: CircularProgressIndicator())),
              );
            }
            if (snap.hasError) {
              return Scaffold(
                body: SafeArea(
                  child: Center(child: Text('Error:\n${snap.error}', textAlign: TextAlign.center)),
                ),
              );
            }
            return const TabsScreen();
          },
        );
      }
    }

    class TabsScreen extends StatefulWidget {
      const TabsScreen({super.key});

      @override
      State<TabsScreen> createState() => _TabsScreenState();
    }

    class _TabsScreenState extends State<TabsScreen> {
      int _selectedIndex = 0;
      final PageController _pageController = PageController();

      void _onItemTapped(int index) {
        setState(() {
          _selectedIndex = index;
        });
        _pageController.jumpToPage(index);
      }

      @override
      Widget build(BuildContext context) {
        return Scaffold(
          body: PageView(
            controller: _pageController,
            onPageChanged: (index) {
              setState(() {
                _selectedIndex = index;
              });
            },
            children: [
              CometChatConversations(
                showBackButton: false,
                onItemTap: (conversation) {
                  Navigator.push(
                    context,
                    MaterialPageRoute(
                      builder: (context) => MessagesScreen(
                        user: conversation.conversationWith is User
                            ? conversation.conversationWith as User
                            : null,
                        group: conversation.conversationWith is Group
                            ? conversation.conversationWith as Group
                            : null,
                      ),
                    ),
                  );
                },
              ),
              CometChatUsers(),
              CometChatGroups(),
            ],
          ),
          bottomNavigationBar: BottomNavigationBar(
            currentIndex: _selectedIndex,
            onTap: _onItemTapped,
            items: const [
              BottomNavigationBarItem(icon: Icon(Icons.chat), label: "Chat"),
              BottomNavigationBarItem(icon: Icon(Icons.person), label: "Users"),
              BottomNavigationBarItem(icon: Icon(Icons.group), label: "Groups"),
            ],
          ),
        );
      }
    }
    ```
  </Tab>
</Tabs>

### Step 2: Render the Messages Component

Use the same `MessagesScreen` pattern from [One-to-One Chat](/docs/ui-kit/flutter/flutter-one-to-one-chat#step-2-render-the-messages-component):

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    class MessagesScreen extends StatelessWidget {
      final User? user;
      final Group? group;

      const MessagesScreen({super.key, this.user, this.group});

      @override
      Widget build(BuildContext context) {
        return Scaffold(
          appBar: CometChatMessageHeader(user: user, group: group),
          body: SafeArea(
            child: Column(
              children: [
                Expanded(child: CometChatMessageList(user: user, group: group)),
                CometChatMessageComposer(user: user, group: group),
              ],
            ),
          ),
        );
      }
    }
    ```
  </Tab>
</Tabs>

***

### Step 3: Run the App

```
flutter run
```

This launches the app with the tab-based chat experience. Navigate between Chats, Users, and Groups tabs and interact with the messaging features.

***

## Next Steps

* [Advanced Customizations](/docs/ui-kit/flutter/theme-introduction) — Personalize the chat UI to align with your brand.
* [Component Styling](/docs/ui-kit/flutter/component-styling) — Fine-tune individual component appearances.


# Getting Started With CometChat Flutter UI Kit V6
Source: https://www.cometchat.com/docs/ui-kit/flutter/getting-started

Set up CometChat Flutter UI Kit V6 with app credentials, package installation, initialization, users, groups, messages, and calls.

CometChat UI Kit V6 for Flutter is a package of pre-assembled UI elements built on clean architecture with BLoC state management. It provides essential messaging functionalities with options for light and dark themes, diverse fonts, colors, and extensive customization capabilities.

CometChat UI Kit V6 supports both one-to-one and group conversations. Follow the guide below to initiate conversations from scratch.

## Prerequisites

Before installing the **UI Kit**, you need to create a CometChat application on the CometChat Dashboard, which includes all the necessary data for a chat service, such as users, groups, calls, and messages. You will require the `App ID`, `AuthKey`, and `Region` of your CometChat application when initializing the SDK.

**i. Register on CometChat**

* You need to register on the **CometChat Dashboard** first. [Click here to sign up](https://app.cometchat.com/login).

**ii. Get Your Application Keys**

* Create a **new app**
* Head over to the **QuickStart** or **API & Auth Keys section** and note the **App ID**, **Auth Key**, and **Region**.

> Each CometChat application can be integrated with a single client app. Within the same application, users can communicate with each other across all platforms, whether they are on mobile devices or on the web.

**iii. Platform & IDE Setup**

* Flutter installed on your system.
* Android Studio or VS Code with configured Flutter/Dart plugins.
* Xcode & Pod (CocoaPods) for iOS.
* An iOS device or emulator with iOS 13.0 or above.
* Android device or emulator with Android version 7.0 (API 24) or above.

## Getting Started

### **Step 1: Create Flutter application project**

To get started, create a new flutter application project.

***

### **Step 2: Add Dependency**

```yaml pubspec.yaml theme={null}
dependencies:
  cometchat_chat_uikit: ^6.0.5
```

Final `pubspec.yaml`

```yaml pubspec.yaml theme={null}
name: my_chat_app
description: "A Flutter app with CometChat V6."

publish_to: 'none'

version: 1.0.0+1

environment:
  sdk: ^3.8.0

dependencies:
  flutter:
    sdk: flutter

  cometchat_chat_uikit: ^6.0.5

  cupertino_icons: ^1.0.8

dev_dependencies:
  flutter_test:
    sdk: flutter

  flutter_lints: ^4.0.0

flutter:
  uses-material-design: true
```

***

**2. Android App Setup**

Update the `minSdkVersion` in your Android project configuration, located at `android/app/build.gradle`:

```gradle build.gradle theme={null}
android {
    defaultConfig {
        minSdk = 24
        // Other configurations...
    }
}
```

***

**3. Update iOS Podfile**

In your Podfile (located at `ios/Podfile`), update the minimum iOS version:

```ruby Podfile theme={null}
platform :ios, '13.0'
```

***

**4. Import CometChat UIKit**

In your Dart code, import the CometChat UIKit package:

```dart main.dart theme={null}
import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
```

> V6 uses a single import. The `cometchat_uikit_shared` package is internalized — no separate import needed.

***

### **Step 3: Initialize UI Kit**

Before using any features from the CometChat UI Kit, initialize it with your app credentials.

1. **Create a Configuration File:**

```dart cometchat_config.dart theme={null}
class CometChatConfig {
  static const String appId = "APP_ID";     // Replace with your App ID
  static const String region = "REGION";    // Replace with your App Region
  static const String authKey = "AUTH_KEY"; // Replace with your Auth Key
}
```

2. **Initialize the UI Kit:**

```dart main.dart theme={null}
import 'cometchat_config.dart';

UIKitSettings uiKitSettings = (UIKitSettingsBuilder()
  ..subscriptionType = CometChatSubscriptionType.allUsers
  ..autoEstablishSocketConnection = true
  ..region = CometChatConfig.region
  ..appId = CometChatConfig.appId
  ..authKey = CometChatConfig.authKey
).build();

CometChatUIKit.init(
  uiKitSettings: uiKitSettings,
  onSuccess: (successMessage) async {
    debugPrint('CometChat Initialized');
  },
  onError: (error) {
    debugPrint('CometChat Initialization error');
  },
);
```

> **V6 difference from V5:** No `extensions` or `aiFeature` parameters needed. Extensions are built-in and handled automatically by `MessageTemplateUtils`.

***

### **Step 4: Login to UI Kit**

Once the UI Kit is initialized, authenticate your user using the `login()` method.

```dart main.dart theme={null}
CometChatUIKit.login(
  "cometchat-uid-1", // Replace with a valid UID
  onSuccess: (user) {
    debugPrint('CometChat LoggedIn success');
  },
  onError: (error) {
    debugPrint('CometChat LoggedIn error');
  },
);
```

You can test using any of the following pre-generated users:

* `cometchat-uid-1`
* `cometchat-uid-2`
* `cometchat-uid-3`
* `cometchat-uid-4`
* `cometchat-uid-5`

> For more information, refer to the documentation on [Init](/docs/ui-kit/flutter/methods#init) and [Login](/docs/ui-kit/flutter/methods#login-using-auth-key).

#### **Example: Initialization and Login Combined**

```dart main.dart theme={null}
import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
import 'package:flutter/material.dart';
import 'cometchat_config.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'CometChat V6',
      theme: ThemeData(useMaterial3: true),
      home: const InitPage(),
    );
  }
}

class InitPage extends StatefulWidget {
  const InitPage({super.key});

  @override
  State<InitPage> createState() => _InitPageState();
}

class _InitPageState extends State<InitPage> {
  bool _isInitializing = true;
  String? _error;

  @override
  void initState() {
    super.initState();
    _initCometChat();
  }

  Future<void> _initCometChat() async {
    UIKitSettings uiKitSettings = (UIKitSettingsBuilder()
          ..subscriptionType = CometChatSubscriptionType.allUsers
          ..autoEstablishSocketConnection = true
          ..region = CometChatConfig.region
          ..appId = CometChatConfig.appId
          ..authKey = CometChatConfig.authKey)
        .build();

    CometChatUIKit.init(
      uiKitSettings: uiKitSettings,
      onSuccess: (msg) {
        CometChatUIKit.login(
          "cometchat-uid-1",
          onSuccess: (user) {
            debugPrint('Logged in as: ${user.name}');
            setState(() => _isInitializing = false);
          },
          onError: (error) {
            setState(() {
              _isInitializing = false;
              _error = error.message;
            });
          },
        );
      },
      onError: (error) {
        setState(() {
          _isInitializing = false;
          _error = error.message;
        });
      },
    );
  }

  @override
  Widget build(BuildContext context) {
    if (_isInitializing) {
      return const Scaffold(body: Center(child: CircularProgressIndicator()));
    }
    if (_error != null) {
      return Scaffold(body: Center(child: Text('Error: $_error')));
    }
    return const Scaffold(body: Center(child: Text('Ready!')));
  }
}
```

***

### **Step 5: Choose a Chat Experience**

Integrate a conversation view that suits your application's UX requirements. Below are the available options:

***

### **1. Conversation List + Message View**

**Best for:** Flutter apps that need a smooth, stack-based navigation between conversations and messages.

**Highlights:**

* **Compact Layout** – Uses `Navigator.push()` for mobile-first navigation.
* **One-to-One & Group Chats** – Built-in support for private and group conversations.
* **Real-Time Messaging** – Message list auto-refreshes with CometChat events.
* **BLoC-Powered** – Predictable state management with `ConversationsBloc` and `MessageListBloc`.

**Use When:**

* You want a clean navigation experience for multiple chat sessions.
* Your Flutter app supports both direct and group messaging.

[Integrate Conversation List + Message View](./flutter-conversation)

***

### **2. One-to-One / Group Chat**

**Best for:** When a user lands directly into a chat screen, bypassing the conversation list.

In V6, you compose the chat screen using individual widgets:

```dart theme={null}
Scaffold(
  body: Column(
    children: [
      CometChatMessageHeader(user: user),
      Expanded(child: CometChatMessageList(user: user)),
      CometChatMessageComposer(user: user),
    ],
  ),
)
```

> V6 does not have a combined `CometChatMessages` composite widget. You compose the UI yourself using `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer`.

**Use When:**

* Your chat starts from a specific user or group ID.
* You want a clean, focused chat interface.
* Use case involves support, onboarding, or one-time messages.

[Integrate One-to-One / Group Chat](./flutter-one-to-one-chat)

***

### **3. Tab-Based Messaging UI (All-in-One)**

**Best for:** Flutter apps needing a multi-tab experience to access Chat, Users, Calls, and Settings.

**Use When:**

* You need a full-featured chat solution in one UI.
* Your users require structured navigation between modules.

[Integrate Tab-Based Chat](./flutter-tab-based-chat)

***

## **Build Your Own Chat Experience**

**Best for:** Developers who need complete control over their chat interface.

**Key Areas to Explore:**

* **[Core Features](./core-features)** – Learn about messaging, real-time updates, and other essential capabilities.
* **[Components](./components-overview)** – Utilize prebuilt UI elements or customize them to fit your design.
* **[Themes](./theme-introduction)** – Adjust colors, fonts, and styles to match your branding.

***

## **Next Steps**

* **[Integrate Conversation List + Message](/docs/ui-kit/flutter/flutter-conversation)**
* **[Integrate One-to-One Chat](/docs/ui-kit/flutter/flutter-one-to-one-chat)**
* **[Integrate Tab-Based Chat](/docs/ui-kit/flutter/flutter-tab-based-chat)**
* **[Advanced Customizations](/docs/ui-kit/flutter/theme-introduction)**

***


# Group Members
Source: https://www.cometchat.com/docs/ui-kit/flutter/group-members

Scrollable list of members in a group with scope indicators, search, and member management actions.

`CometChatGroupMembers` renders a scrollable list of members in a specific group with real-time updates, scope indicators (owner/admin/moderator/participant), search, and member management actions (kick, ban, change scope).

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatGroupMembers` is a list component that requires a `Group` object. It renders group members and supports actions like kick, ban, and scope change based on the logged-in user's permissions.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      onItemTap: (groupMember) {
        // Navigate to member profile or chat
      },
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

Using Navigator:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    Navigator.push(context, MaterialPageRoute(
      builder: (context) => CometChatGroupMembers(group: group),
    ));
    ```
  </Tab>
</Tabs>

Embedding as a widget:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    @override
    Widget build(BuildContext context) {
      return Scaffold(
        body: SafeArea(
          child: CometChatGroupMembers(group: group),
        ),
      );
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized, a user logged in, and a valid `Group` object.

***

## Filtering Members

Pass a `GroupMembersRequestBuilder` to control what loads:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      groupMembersRequestBuilder: GroupMembersRequestBuilder(group.guid)
        ..limit = 20
        ..searchKeyword = "john",
    )
    ```
  </Tab>
</Tabs>

### Filter Recipes

| Recipe           | Builder property                    |
| ---------------- | ----------------------------------- |
| Limit per page   | `..limit = 20`                      |
| Search by name   | `..searchKeyword = "john"`          |
| Filter by scopes | `..scopes = ["admin", "moderator"]` |

***

## Actions and Events

### Callback Methods

#### `onItemTap`

Fires when a member row is tapped.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      onItemTap: (groupMember) {
        // Navigate to member profile
      },
    )
    ```
  </Tab>
</Tabs>

#### `onItemLongPress`

Fires when a member row is long-pressed. By default shows the member action menu (kick/ban/scope change).

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      onItemLongPress: (groupMember) {
        // Custom long press behavior
      },
    )
    ```
  </Tab>
</Tabs>

#### `onBack`

Fires when the user presses the back button.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      onBack: () {
        Navigator.pop(context);
      },
    )
    ```
  </Tab>
</Tabs>

#### `onSelection`

Fires when members are selected/deselected in multi-select mode.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      selectionMode: SelectionMode.multiple,
      onSelection: (selectedMembers, context) {
        // Handle selected members
      },
    )
    ```
  </Tab>
</Tabs>

#### `onError`

Fires on internal errors.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      onError: (e) {
        debugPrint("Error: ${e.message}");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      onLoad: (memberList) {
        debugPrint("Loaded ${memberList.length} members");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      onEmpty: () {
        debugPrint("No members found");
      },
    )
    ```
  </Tab>
</Tabs>

### Global Events

The component emits events via `CometChatGroupEvents`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class _YourScreenState extends State<YourScreen> with CometChatGroupEventListener {
      @override
      void initState() {
        super.initState();
        CometChatGroupEvents.addGroupsListener("listenerId", this);
      }

      @override
      void dispose() {
        CometChatGroupEvents.removeGroupsListener("listenerId");
        super.dispose();
      }

      @override
      void ccGroupMemberKicked(Action action, User kickedUser, User kickedBy, Group kickedFrom) {
        // Handle member kicked
      }

      @override
      void ccGroupMemberBanned(Action action, User bannedUser, User bannedBy, Group bannedFrom) {
        // Handle member banned
      }

      @override
      void ccGroupMemberScopeChanged(Action action, User updatedUser, String scopeChangedTo, String scopeChangedFrom, Group group) {
        // Handle scope changed
      }
    }
    ```
  </Tab>
</Tabs>

### SDK Events (Real-Time, Automatic)

| SDK Listener                     | Internal behavior                                                |
| -------------------------------- | ---------------------------------------------------------------- |
| `onGroupMemberJoined`            | Adds member to list                                              |
| `onGroupMemberLeft`              | Removes member from list                                         |
| `onGroupMemberKicked`            | Removes member from list                                         |
| `onGroupMemberBanned`            | Removes member from list                                         |
| `onGroupMemberScopeChanged`      | Updates member scope in list                                     |
| `onUserOnline` / `onUserOffline` | Updates presence via per-member ValueNotifier (isolated rebuild) |
| Connection reconnected           | Triggers silent refresh                                          |

***

## Functionality

| Property                | Type             | Default      | Description                        |
| ----------------------- | ---------------- | ------------ | ---------------------------------- |
| `group`                 | `Group`          | **required** | The group whose members to display |
| `title`                 | `String?`        | `null`       | Custom app bar title               |
| `showBackButton`        | `bool`           | `true`       | Toggle back button                 |
| `hideAppbar`            | `bool?`          | `false`      | Toggle app bar visibility          |
| `hideSearch`            | `bool`           | `false`      | Toggle search bar                  |
| `usersStatusVisibility` | `bool?`          | `true`       | Show online/offline status         |
| `selectionMode`         | `SelectionMode?` | `null`       | Enable selection mode              |
| `hideKickMemberOption`  | `bool?`          | `false`      | Hide kick option in action menu    |
| `hideBanMemberOption`   | `bool?`          | `false`      | Hide ban option in action menu     |
| `hideScopeChangeOption` | `bool?`          | `false`      | Hide scope change option           |

***

## Custom View Slots

### Leading View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      leadingView: (context, groupMember) {
        return CircleAvatar(
          child: Text(groupMember.name?[0] ?? ""),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Title View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      titleView: (context, groupMember) {
        return Text(
          groupMember.name ?? "",
          style: TextStyle(fontWeight: FontWeight.bold),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      subtitleView: (context, groupMember) {
        return Text(
          groupMember.scope ?? "participant",
          style: TextStyle(color: Color(0xFF727272), fontSize: 14),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Trailing View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      trailingView: (context, groupMember) {
        return Chip(label: Text(groupMember.scope ?? ""));
      },
    )
    ```
  </Tab>
</Tabs>

### List Item View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      listItemView: (groupMember) {
        return ListTile(
          leading: CircleAvatar(child: Text(groupMember.name?[0] ?? "")),
          title: Text(groupMember.name ?? ""),
          subtitle: Text(groupMember.scope ?? "participant"),
          trailing: Chip(label: Text(groupMember.scope ?? "")),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      emptyStateView: (context) => Center(child: Text("No members")),
      errorStateView: (context) => Center(child: Text("Something went wrong")),
      loadingStateView: (context) => Center(child: CircularProgressIndicator()),
    )
    ```
  </Tab>
</Tabs>

***

## Menu Options

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // Replace all options
    CometChatGroupMembers(
      group: group,
      setOptions: (groupMember, bloc, context) {
        return [
          CometChatOption(
            id: "message",
            iconWidget: Icon(Icons.message),
            title: "Message",
            onClick: () {
              // Open chat with this member
            },
          ),
        ];
      },
    )

    // Append to defaults
    CometChatGroupMembers(
      group: group,
      addOptions: (groupMember, bloc, context) {
        return [
          CometChatOption(
            id: "profile",
            iconWidget: Icon(Icons.person),
            title: "View Profile",
            onClick: () {
              // Open member profile
            },
          ),
        ];
      },
    )
    ```
  </Tab>
</Tabs>

***

## Advanced

### BLoC Access

Provide a custom `GroupMembersBloc`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      groupMembersBloc: CustomGroupMembersBloc(),
    )
    ```
  </Tab>
</Tabs>

### Public BLoC Events

| Event                                      | Description                  |
| ------------------------------------------ | ---------------------------- |
| `LoadGroupMembers`                         | Load initial members         |
| `LoadMoreGroupMembers`                     | Load next page (pagination)  |
| `SearchGroupMembers(keyword)`              | Search members               |
| `KickMember(groupMember)`                  | Kick a member from the group |
| `BanMember(groupMember)`                   | Ban a member from the group  |
| `ChangeMemberScope(groupMember, newScope)` | Change member's scope        |
| `ToggleMemberSelection(uid)`               | Toggle selection state       |
| `ClearMemberSelection`                     | Clear all selections         |

For `ListBase` override hooks (`onItemAdded`, `onItemRemoved`, `onItemUpdated`, `onListCleared`, `onListReplaced`), see [BLoC & Data — ListBase Hooks](/docs/ui-kit/flutter/customization-bloc-data#listbase-hooks).

### Public BLoC Methods

| Method                   | Returns                 | Description                                      |
| ------------------------ | ----------------------- | ------------------------------------------------ |
| `getStatusNotifier(uid)` | `ValueNotifier<String>` | Per-member status notifier for isolated rebuilds |

### Permission-Based Actions

Member actions (kick, ban, scope change) are permission-aware based on the logged-in user's scope:

| Logged-in User Scope | Can Kick                 | Can Ban                  | Can Change Scope         |
| -------------------- | ------------------------ | ------------------------ | ------------------------ |
| Owner                | All members              | All members              | All members              |
| Admin                | Moderators, Participants | Moderators, Participants | Moderators, Participants |
| Moderator            | Participants             | Participants             | No                       |
| Participant          | No                       | No                       | No                       |

***

## Style

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      groupMembersStyle: CometChatGroupMembersStyle(
        avatarStyle: CometChatAvatarStyle(
          borderRadius: BorderRadius.circular(8),
          backgroundColor: Color(0xFFFBAA75),
        ),
        statusIndicatorStyle: CometChatStatusIndicatorStyle(),
        changeScopeStyle: CometChatChangeScopeStyle(),
        confirmDialogStyle: CometChatConfirmDialogStyle(),
      ),
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

### Style Properties

| Property               | Description                        |
| ---------------------- | ---------------------------------- |
| `avatarStyle`          | Avatar appearance                  |
| `statusIndicatorStyle` | Online/offline indicator           |
| `changeScopeStyle`     | Scope change dialog style          |
| `confirmDialogStyle`   | Kick/ban confirmation dialog style |

***

## Next Steps

<CardGroup>
  <Card title="Groups" icon="users" href="/ui-kit/flutter/groups">
    Browse available groups
  </Card>

  <Card title="Group Chat Guide" icon="book" href="/ui-kit/flutter/guide-group-chat">
    Complete group chat implementation
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/flutter/component-styling">
    Detailed styling reference
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/flutter/conversations">
    Browse recent conversations
  </Card>
</CardGroup>


# Groups
Source: https://www.cometchat.com/docs/ui-kit/flutter/groups

Scrollable list of all available groups with search, avatars, group type indicators, and member counts.

`CometChatGroups` renders a scrollable list of all available groups with real-time updates for group events, search, avatars, group type indicators (public/private/password), and member counts.

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatGroups` is a list component. It renders all available groups and emits the selected `Group` via `onItemTap`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a group chat layout.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onItemTap: (context, group) {
        // Navigate to group chat
      },
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

Using Navigator:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    Navigator.push(context, MaterialPageRoute(builder: (context) => const CometChatGroups()));
    ```
  </Tab>
</Tabs>

Embedding as a widget:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    @override
    Widget build(BuildContext context) {
      return Scaffold(
        body: SafeArea(
          child: CometChatGroups(),
        ),
      );
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

***

## Filtering Groups

Pass a `GroupsRequestBuilder` to control what loads:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      groupsRequestBuilder: GroupsRequestBuilder()
        ..limit = 10
        ..searchKeyword = "team",
    )
    ```
  </Tab>
</Tabs>

### Filter Recipes

| Recipe             | Builder property           |
| ------------------ | -------------------------- |
| Limit per page     | `..limit = 10`             |
| Search by keyword  | `..searchKeyword = "team"` |
| Joined groups only | `..joinedOnly = true`      |
| Filter by tags     | `..tags = ["project"]`     |
| With tags          | `..withTags = true`        |

***

## Actions and Events

### Callback Methods

#### `onItemTap`

Fires when a group row is tapped. Primary navigation hook.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onItemTap: (context, group) {
        // Navigate to group chat screen
      },
    )
    ```
  </Tab>
</Tabs>

#### `onItemLongPress`

Fires when a group row is long-pressed.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onItemLongPress: (context, group) {
        // Show context menu
      },
    )
    ```
  </Tab>
</Tabs>

#### `onBack`

Fires when the user presses the back button in the app bar.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onBack: () {
        Navigator.pop(context);
      },
    )
    ```
  </Tab>
</Tabs>

#### `onSelection`

Fires when groups are selected/deselected in multi-select mode.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      selectionMode: SelectionMode.multiple,
      onSelection: (selectedGroups, context) {
        // Handle selected groups
      },
    )
    ```
  </Tab>
</Tabs>

#### `onError`

Fires on internal errors.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onError: (e) {
        debugPrint("Error: ${e.message}");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched and loaded.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onLoad: (groupList) {
        debugPrint("Loaded ${groupList.length} groups");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onEmpty: () {
        debugPrint("No groups found");
      },
    )
    ```
  </Tab>
</Tabs>

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

| SDK Listener           | Internal behavior                                                      |
| ---------------------- | ---------------------------------------------------------------------- |
| `onGroupMemberJoined`  | Updates group member count                                             |
| `onGroupMemberLeft`    | Updates group member count                                             |
| `onGroupMemberKicked`  | Updates group member count, removes group if logged-in user was kicked |
| `onGroupMemberBanned`  | Updates group member count, removes group if logged-in user was banned |
| `onMemberAddedToGroup` | Updates group member count                                             |
| `ccGroupCreated`       | Adds new group to list                                                 |
| `ccGroupDeleted`       | Removes group from list                                                |
| Connection reconnected | Triggers silent refresh                                                |

***

## Functionality

| Property            | Type             | Default | Description                                    |
| ------------------- | ---------------- | ------- | ---------------------------------------------- |
| `title`             | `String?`        | `null`  | Custom app bar title                           |
| `showBackButton`    | `bool`           | `true`  | Toggle back button                             |
| `hideAppbar`        | `bool?`          | `false` | Toggle app bar visibility                      |
| `hideSearch`        | `bool`           | `false` | Toggle search bar                              |
| `selectionMode`     | `SelectionMode?` | `null`  | Enable selection mode (`single` or `multiple`) |
| `searchPlaceholder` | `String?`        | `null`  | Search placeholder text                        |

***

## Custom View Slots

### Leading View

Replace the avatar / left section.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      leadingView: (context, group) {
        return CircleAvatar(
          child: Text(group.name?[0] ?? "G"),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Title View

Replace the group name / title text.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      titleView: (context, group) {
        return Text(
          group.name ?? "",
          style: TextStyle(fontWeight: FontWeight.bold),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

Replace the subtitle text below the group name.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      subtitleView: (context, group) {
        return Text(
          "${group.membersCount} members",
          style: TextStyle(color: Color(0xFF727272), fontSize: 14),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Trailing View

Replace the right section of each group item.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      trailingView: (context, group) {
        return Text(group.type ?? "");
      },
    )
    ```
  </Tab>
</Tabs>

### List Item View

Replace the entire list item row.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      listItemView: (group) {
        return ListTile(
          leading: CircleAvatar(child: Text(group.name?[0] ?? "G")),
          title: Text(group.name ?? ""),
          subtitle: Text("${group.membersCount} members"),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      emptyStateView: (context) => Center(child: Text("No groups found")),
      errorStateView: (context) => Center(child: Text("Something went wrong")),
      loadingStateView: (context) => Center(child: CircularProgressIndicator()),
    )
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Minimal list — hide all chrome

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      hideAppbar: true,
      hideSearch: true,
    )
    ```
  </Tab>
</Tabs>

### Joined groups only

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      groupsRequestBuilder: GroupsRequestBuilder()
        ..joinedOnly = true,
    )
    ```
  </Tab>
</Tabs>

***

## Advanced

### BLoC Access

Provide a custom `GroupsBloc` to override behavior:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      groupsBloc: CustomGroupsBloc(),
    )
    ```
  </Tab>
</Tabs>

### Extending GroupsBloc

`GroupsBloc` uses the `ListBase<Group>` mixin with override hooks:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class CustomGroupsBloc extends GroupsBloc {
      @override
      void onItemAdded(Group item, List<Group> updatedList) {
        // Custom sorting logic
        super.onItemAdded(item, updatedList);
      }

      @override
      void onListReplaced(List<Group> previousList, List<Group> newList) {
        // Filter out specific groups
        final filtered = newList.where((g) => g.membersCount > 0).toList();
        super.onListReplaced(previousList, filtered);
      }
    }
    ```
  </Tab>
</Tabs>

For `ListBase` override hooks (`onItemAdded`, `onItemRemoved`, `onItemUpdated`, `onListCleared`, `onListReplaced`), see [BLoC & Data — ListBase Hooks](/docs/ui-kit/flutter/customization-bloc-data#listbase-hooks).

### Public BLoC Events

| Event                                 | Description                                                      |
| ------------------------------------- | ---------------------------------------------------------------- |
| `LoadGroups({searchKeyword, silent})` | Load initial groups. `silent: true` keeps existing list visible. |
| `LoadMoreGroups()`                    | Load next page (pagination)                                      |
| `RefreshGroups()`                     | Refresh the list                                                 |
| `SearchGroups(keyword)`               | Search groups with debouncing                                    |

***

## Style

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      groupsStyle: CometChatGroupsStyle(
        avatarStyle: CometChatAvatarStyle(
          borderRadius: BorderRadius.circular(8),
          backgroundColor: Color(0xFFFBAA75),
        ),
        statusIndicatorStyle: CometChatStatusIndicatorStyle(),
      ),
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

### Style Properties

| Property               | Description           |
| ---------------------- | --------------------- |
| `backgroundColor`      | List background color |
| `avatarStyle`          | Avatar appearance     |
| `statusIndicatorStyle` | Group type indicator  |
| `searchBoxStyle`       | Search box appearance |

See [Component Styling](/docs/ui-kit/flutter/component-styling) for the full reference.

***

## Next Steps

<CardGroup>
  <Card title="Group Members" icon="users" href="/ui-kit/flutter/group-members">
    View and manage group members
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/flutter/conversations">
    Browse recent conversations
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/flutter/component-styling">
    Detailed styling reference
  </Card>

  <Card title="Group Chat Guide" icon="book" href="/ui-kit/flutter/guide-group-chat">
    Complete group chat implementation
  </Card>
</CardGroup>


# Incoming Call
Source: https://www.cometchat.com/docs/ui-kit/flutter/incoming-call

Handle incoming CometChat Flutter UI Kit audio and video calls with full-screen caller info, accept, reject, and navigation setup.

`CometChatIncomingCall` displays a full-screen overlay when an incoming call is received, showing caller info with accept and reject buttons.

***

## Where It Fits

Typically triggered automatically when `CallNavigationContext.navigatorKey` is set in your `MaterialApp`.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    MaterialApp(navigatorKey: CallNavigationContext.navigatorKey, home: YourHomeScreen())
    ```
  </Tab>
</Tabs>

***

## Quick Start

### Automatic (Recommended)

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    MaterialApp(navigatorKey: CallNavigationContext.navigatorKey, home: YourHomeScreen())
    ```
  </Tab>
</Tabs>

### Manual Launch

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    Navigator.push(context, MaterialPageRoute(
      builder: (context) => CometChatIncomingCall(user: user, call: callObject),
    ));
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized, Calls UIKit added, `callingExtension` set. See [Call Features](/docs/ui-kit/flutter/call-features).

***

## Actions

#### `onAccept`

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatIncomingCall(user: user, call: callObject,
      onAccept: (BuildContext context, Call call) { /* Custom accept */ },
    )
    ```
  </Tab>
</Tabs>

#### `onDecline`

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatIncomingCall(user: user, call: callObject,
      onDecline: (BuildContext context, Call call) { /* Custom decline */ },
    )
    ```
  </Tab>
</Tabs>

#### `onError`

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatIncomingCall(user: user, call: callObject,
      onError: (e) { debugPrint("Error: ${e.message}"); },
    )
    ```
  </Tab>
</Tabs>

***

## Functionality

| Property               | Type                   | Description                 |
| ---------------------- | ---------------------- | --------------------------- |
| `user`                 | `User?`                | Caller user object          |
| `call`                 | `Call`                 | Call object (required)      |
| `callSettingsBuilder`  | `CallSettingsBuilder?` | Configure call settings     |
| `height` / `width`     | `double?`              | Widget dimensions           |
| `callIcon`             | `Widget?`              | Custom call type icon       |
| `acceptButtonText`     | `String?`              | Custom accept button text   |
| `declineButtonText`    | `String?`              | Custom decline button text  |
| `disableSoundForCalls` | `bool?`                | Disable incoming call sound |
| `customSoundForCalls`  | `String?`              | Custom sound asset path     |

***

## Custom View Slots

### Item View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatIncomingCall(user: user, call: callObject,
      itemView: (context, call) { return Container(); },
    )
    ```
  </Tab>
</Tabs>

### Leading View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatIncomingCall(user: user, call: callObject,
      leadingView: (context, call) {
        return CircleAvatar(radius: 40, backgroundImage: NetworkImage(call.sender?.avatar ?? ""));
      },
    )
    ```
  </Tab>
</Tabs>

### Title View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatIncomingCall(user: user, call: callObject,
      titleView: (context, call) {
        return Text(call.sender?.name ?? "Unknown",
          style: TextStyle(fontSize: 20, fontWeight: FontWeight.bold, color: Colors.white));
      },
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatIncomingCall(user: user, call: callObject,
      subTitleView: (context, call) {
        final type = call.type == CometChatConstants.CALL_TYPE_VIDEO ? "Video" : "Audio";
        return Text("Incoming $type Call", style: TextStyle(fontSize: 14, color: Colors.white70));
      },
    )
    ```
  </Tab>
</Tabs>

### Trailing View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatIncomingCall(user: user, call: callObject,
      trailingView: (context, call) {
        return Row(mainAxisAlignment: MainAxisAlignment.spaceEvenly, children: [
          ElevatedButton(onPressed: () {}, child: Text("Reject"),
            style: ElevatedButton.styleFrom(backgroundColor: Colors.red)),
          ElevatedButton(onPressed: () {}, child: Text("Accept"),
            style: ElevatedButton.styleFrom(backgroundColor: Colors.green)),
        ]);
      },
    )
    ```
  </Tab>
</Tabs>

***

## Style

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatIncomingCall(user: user, call: callObject,
      incomingCallStyle: CometChatIncomingCallStyle(
        backgroundColor: Color(0xFFEDEAFA),
        avatarStyle: CometChatAvatarStyle(backgroundColor: Color(0xFFAA9EE8), borderRadius: BorderRadius.circular(7.5)),
        acceptButtonColor: Color(0xFF6852D6),
        declineButtonColor: Colors.white,
        declineTextColor: Color(0xFFF44649),
        callIconColor: Color(0xFF6852D6),
      ),
    )
    ```
  </Tab>
</Tabs>

| Property             | Description               |
| -------------------- | ------------------------- |
| `backgroundColor`    | Background color          |
| `avatarStyle`        | Caller avatar appearance  |
| `acceptButtonColor`  | Accept button background  |
| `declineButtonColor` | Decline button background |
| `declineTextColor`   | Decline button text color |
| `callIconColor`      | Call type icon color      |

***

## Key V6 Differences

| Aspect           | V5                                                              | V6                                                                          |
| ---------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Subtitle         | Static `String?`                                                | Dynamic `Widget? Function(BuildContext, Call)?`                             |
| Decline icon     | URL-based `String?`                                             | Widget-based                                                                |
| Custom views     | Limited                                                         | Full `titleView`, `subTitleView`, `leadingView`, `trailingView`, `itemView` |
| State management | GetX controller                                                 | BLoC (`IncomingCallBloc`)                                                   |
| Removed          | `theme`, `avatarStyle`, `cardStyle`, `ongoingCallConfiguration` | Integrated into main style                                                  |

***

## Next Steps

<CardGroup>
  <Card title="Outgoing Call" icon="phone-arrow-up-right" href="/ui-kit/flutter/outgoing-call">Manage outgoing calls</Card>
  <Card title="Call Buttons" icon="phone" href="/ui-kit/flutter/call-buttons">Add call buttons</Card>
  <Card title="Call Features" icon="video" href="/ui-kit/flutter/call-features">Complete calling setup</Card>
  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/flutter/component-styling">Styling reference</Card>
</CardGroup>


# Localize
Source: https://www.cometchat.com/docs/ui-kit/flutter/localize

Localize CometChat Flutter UI Kit with supported languages, device language detection, translation files, and MaterialApp setup.

## Overview

CometChat V6 UI Kit provides language localization to adapt to the language of a specific country or region. The `CometChatLocalize` class allows you to detect the language of your users based on their device settings and set the language accordingly.

The UI Kit supports 19 languages:

* Arabic (ar), German (de), English (en, en-GB), Spanish (es), French (fr), Hindi (hi), Hungarian (hu), Japanese (ja), Korean (ko), Lithuanian (lt), Malay (ms), Dutch (nl), Portuguese (pt), Russian (ru), Swedish (sv), Turkish (tr), Chinese (zh, zh-TW)

## Usage

### Integration

Add the following dependency in `pubspec.yaml`:

<Tabs>
  <Tab title="Dart">
    ```yaml theme={null}
    flutter_localizations:
      sdk: flutter
    ```
  </Tab>
</Tabs>

***

Update MaterialApp Localizations Delegates:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
    import 'package:cometchat_uikit_shared/l10n/translations.dart' as cc;
    import 'package:flutter/material.dart';
    import 'package:flutter_localizations/flutter_localizations.dart';

    class MyApp extends StatelessWidget {
      const MyApp({super.key});

      @override
      Widget build(BuildContext context) {
        return MaterialApp(
          supportedLocales: const [
            Locale('en'), Locale('en', 'GB'), Locale('ar'), Locale('de'),
            Locale('es'), Locale('fr'), Locale('hi'), Locale('hu'),
            Locale('ja'), Locale('ko'), Locale('lt'), Locale('ms'),
            Locale('nl'), Locale('pt'), Locale('ru'), Locale('sv'),
            Locale('tr'), Locale('zh'), Locale('zh', 'TW'),
          ],
          localizationsDelegates: const [
            cc.Translations.delegate,
            GlobalMaterialLocalizations.delegate,
            GlobalWidgetsLocalizations.delegate,
            GlobalCupertinoLocalizations.delegate,
          ],
          theme: ThemeData(
            appBarTheme: AppBarTheme(scrolledUnderElevation: 0.0),
          ),
          title: 'CometChat Flutter App',
          home: YourHomeScreen(),
          debugShowCheckedModeBanner: false,
        );
      }
    }
    ```
  </Tab>
</Tabs>

***

You can also translate specific strings:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String translatedString = Translations.of(context).users;
    Text(translatedString);
    ```
  </Tab>
</Tabs>

### Customizing UI Kit Translations for a Specific Language

Override a specific language's default translations by creating a custom localization class:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'dart:async';
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart' as cc;
    import 'package:flutter/foundation.dart';
    import 'package:flutter/material.dart';

    class CustomEN extends TranslationsEn {
      static const delegate = _CustomCometChatLocalizationsDelegate();

      @override
      String get chats => "Overridden Chat";

      @override
      String get calls => "Overridden Call";
    }

    class _CustomCometChatLocalizationsDelegate
        extends LocalizationsDelegate<cc.Translations> {
      const _CustomCometChatLocalizationsDelegate();

      @override
      bool isSupported(Locale locale) => locale.languageCode == 'en';

      @override
      Future<cc.Translations> load(Locale locale) =>
          SynchronousFuture(CustomEN());

      @override
      bool shouldReload(_CustomCometChatLocalizationsDelegate old) => false;
    }
    ```
  </Tab>
</Tabs>

Then add `CustomEN.delegate` to your `localizationsDelegates` list before `cc.Translations.delegate`.

### Adding New Language Support

Extend the UI Kit with a new language by creating a custom translation class:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class TeluguLocalization extends cc.Translations {
      TeluguLocalization([super.locale = "te"]);
      static const delegate = _TeluguLocalizationsDelegate();

      @override
      String get chats => "సందేశాలు";

      @override
      String get calls => "ఫోన్ కాల్స్";
      // Override all relevant strings for full localization
    }

    class _TeluguLocalizationsDelegate
        extends LocalizationsDelegate<cc.Translations> {
      const _TeluguLocalizationsDelegate();

      @override
      bool isSupported(Locale locale) => locale.languageCode == 'te';

      @override
      Future<cc.Translations> load(Locale locale) =>
          SynchronousFuture(TeluguLocalization());

      @override
      bool shouldReload(_TeluguLocalizationsDelegate old) => false;
    }
    ```
  </Tab>
</Tabs>

### DateTimeFormatter

By providing a custom `DateTimeFormatterCallback`, you can globally configure how time and date values are displayed across all UI components. For details, refer to the [CometChatUIKit class](/docs/ui-kit/flutter/methods#dateformatter).


# Customizing Message Bubbles
Source: https://www.cometchat.com/docs/ui-kit/flutter/message-bubble-styling

Customize CometChat Flutter UI Kit message bubbles with incoming and outgoing styles, theme extensions, reactions, timestamps, and avatars.

The CometChat V6 UI Kit provides `CometChatOutgoingMessageBubbleStyle` and `CometChatIncomingMessageBubbleStyle` for fine-grained control over message bubble appearance. These classes extend `ThemeExtension`, allowing customizations through global theming or explicit style objects.

## How These Classes Help

### 1. Targeted Customization

Customize specific attributes of message bubbles:

* Background color, border radius, text style
* Specialized bubbles: Audio, File, Collaborative, Poll, Deleted, Link Preview, Sticker, Call bubbles
* Reactions, timestamps, avatars, and borders

### 2. Unified Global Theming

Apply styles via Flutter's global theming or pass them to `CometChatMessageListStyle`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    MaterialApp(
      title: 'Your app',
      theme: ThemeData(
        extensions: [
          CometChatIncomingMessageBubbleStyle(
            backgroundColor: Color(0xFFF76808),
          ),
          CometChatOutgoingMessageBubbleStyle(
            backgroundColor: Color(0xFFF76808),
          ),
        ],
      ),
      home: ...,
    );
    ```
  </Tab>
</Tabs>

### 3. Ease of Integration

Pass styles directly to `CometChatMessageList`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      group: group,
      style: CometChatMessageListStyle(
        incomingMessageBubbleStyle: CometChatIncomingMessageBubbleStyle(),
        outgoingMessageBubbleStyle: CometChatOutgoingMessageBubbleStyle(),
      ),
    )
    ```
  </Tab>
</Tabs>

## Customizable Message Bubbles

### Text Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          textBubbleStyle: CometChatTextBubbleStyle(
            backgroundColor: Color(0xFFF76808),
          ),
        ),
        CometChatIncomingMessageBubbleStyle(
          textBubbleStyle: CometChatTextBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Image Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          imageBubbleStyle: CometChatImageBubbleStyle(
            backgroundColor: Color(0xFFF76808),
          ),
        ),
        CometChatIncomingMessageBubbleStyle(
          imageBubbleStyle: CometChatImageBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Video Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          videoBubbleStyle: CometChatVideoBubbleStyle(
            backgroundColor: Color(0xFFF76808),
            playIconColor: Color(0xFFF76808),
          ),
        ),
        CometChatIncomingMessageBubbleStyle(
          videoBubbleStyle: CometChatVideoBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
            playIconColor: Color(0xFFF76808),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Voice Note Bubble

Styles the voice-note (recorded audio) bubble via `voiceNoteBubbleStyle` and `CometChatVoiceNoteBubbleStyle`.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          voiceNoteBubbleStyle: CometChatVoiceNoteBubbleStyle(
            backgroundColor: Color(0xFFF76808),
            playIconColor: Color(0xFFF76808),
          ),
        ),
        CometChatIncomingMessageBubbleStyle(
          voiceNoteBubbleStyle: CometChatVoiceNoteBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
            downloadIconColor: Color(0xFFF76808),
            audioBarColor: Color(0xFFF76808),
            playIconColor: Color(0xFFF76808),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

<Note>
  The older `audioBubbleStyle` / `CometChatAudioBubbleStyle` names are deprecated aliases of `voiceNoteBubbleStyle` / `CometChatVoiceNoteBubbleStyle` and still work, but prefer the voice-note names.
</Note>

### File Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          fileBubbleStyle: CometChatFileBubbleStyle(
            backgroundColor: Color(0xFFF76808),
          ),
        ),
        CometChatIncomingMessageBubbleStyle(
          fileBubbleStyle: CometChatFileBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
            downloadIconTint: Color(0xFFF76808),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Sticker Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          stickerBubbleStyle: CometChatStickerBubbleStyle(
            backgroundColor: Color(0xFFF76808),
          ),
        ),
        CometChatIncomingMessageBubbleStyle(
          stickerBubbleStyle: CometChatStickerBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Call Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          videoCallBubbleStyle: CometChatCallBubbleStyle(
            backgroundColor: Color(0xFFF76808),
            iconColor: Color(0xFFF76808),
            buttonTextStyle: TextStyle(color: Colors.white),
            dividerColor: Color(0xFFFBAA75),
          ),
        ),
        CometChatIncomingMessageBubbleStyle(
          videoCallBubbleStyle: CometChatCallBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
            iconColor: Color(0xFFF76808),
            buttonTextStyle: TextStyle(color: Color(0xFFF76808)),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Collaborative Whiteboard Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          collaborativeWhiteboardBubbleStyle: CometChatCollaborativeBubbleStyle(
            backgroundColor: Color(0xFFF76808),
            iconTint: Color(0xFFFFFFFF),
            titleStyle: TextStyle(fontWeight: FontWeight.bold, color: Color(0xFFFFFFFF)),
            buttonTextStyle: TextStyle(color: Color(0xFFFFFFFF)),
            dividerColor: Color(0xFFFBAA75),
          ),
        ),
        CometChatIncomingMessageBubbleStyle(
          collaborativeWhiteboardBubbleStyle: CometChatCollaborativeBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
            iconTint: Color(0xFFF76808),
            titleStyle: TextStyle(fontWeight: FontWeight.bold),
            buttonTextStyle: TextStyle(color: Color(0xFFF76808)),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Collaborative Document Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          collaborativeDocumentBubbleStyle: CometChatCollaborativeBubbleStyle(
            backgroundColor: Color(0xFFF76808),
            iconTint: Color(0xFFFFFFFF),
            titleStyle: TextStyle(fontWeight: FontWeight.bold, color: Color(0xFFFFFFFF)),
            buttonTextStyle: TextStyle(color: Color(0xFFFFFFFF)),
            dividerColor: Color(0xFFFBAA75),
          ),
        ),
        CometChatIncomingMessageBubbleStyle(
          collaborativeDocumentBubbleStyle: CometChatCollaborativeBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
            iconTint: Color(0xFFF76808),
            titleStyle: TextStyle(fontWeight: FontWeight.bold),
            buttonTextStyle: TextStyle(color: Color(0xFFF76808)),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Poll Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          pollsBubbleStyle: CometChatPollsBubbleStyle(
            backgroundColor: Color(0xFFF76808),
            progressBackgroundColor: Color(0xFFFBAA75),
            iconColor: Color(0xFFF76808),
          ),
        ),
        CometChatIncomingMessageBubbleStyle(
          pollsBubbleStyle: CometChatPollsBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
            progressBackgroundColor: Color(0xFFDCDCDC),
            progressColor: Color(0xFFF76808),
            iconColor: Colors.white,
            selectedOptionColor: Color(0xFFF76808),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Link Preview Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          linkPreviewBubbleStyle: CometChatLinkPreviewBubbleStyle(
            backgroundColor: Color(0xFFFBAA75),
          ),
          textBubbleStyle: CometChatTextBubbleStyle(
            backgroundColor: Color(0xFFF76808),
          ),
        ),
        CometChatIncomingMessageBubbleStyle(
          linkPreviewBubbleStyle: CometChatLinkPreviewBubbleStyle(
            backgroundColor: Color(0xFFFBAA75),
          ),
          textBubbleStyle: CometChatTextBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Action Message Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatActionBubbleStyle(
          textStyle: TextStyle(color: Color(0xFFF76808)),
          border: Border.all(color: Color(0xFFF76808)),
          backgroundColor: Color(0xFFFEEDE1),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### Deleted Message Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatOutgoingMessageBubbleStyle(
          deletedBubbleStyle: CometChatDeletedBubbleStyle(
            backgroundColor: Color(0xFFF76808),
          ),
        ),
        CometChatIncomingMessageBubbleStyle(
          deletedBubbleStyle: CometChatDeletedBubbleStyle(
            backgroundColor: Color(0xFFFEEDE1),
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

### AI Assistant Bubble

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatAiAssistantBubbleStyle(
          backgroundColor: Colors.transparent,
          textColor: const Color(0xFF141414),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

## Multiple Attachments

When `enableMultipleAttachments` is on, a message's images / videos / audio files / documents render through dedicated **multi-attachment** bubbles. These are styled differently from the single-attachment bubbles above: each has its own `ThemeExtension` class that you register **directly** in `ThemeData.extensions` — they are *not* nested inside `CometChatIncomingMessageBubbleStyle` / `CometChatOutgoingMessageBubbleStyle`.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ThemeData(
      extensions: [
        CometChatImagesBubbleStyle(placeholderColor: Color(0xFFFEEDE1)),
        CometChatVideosBubbleStyle(playIconColor: Color(0xFFF76808)),
        CometChatAudiosBubbleStyle(playIconColor: Color(0xFFF76808)),
        CometChatFilesBubbleStyle(backgroundColor: Color(0xFFFEEDE1)),
      ],
    )
    ```
  </Tab>
</Tabs>

<Note>
  Both families can coexist. The single-attachment `imageBubbleStyle` / `videoBubbleStyle` / `voiceNoteBubbleStyle` / `fileBubbleStyle` apply when a message carries one attachment (or when multiple attachments are disabled); the classes below apply to the multi-attachment grids and lists.
</Note>

### Images Bubble — `CometChatImagesBubbleStyle`

<Frame>
  <img alt="Images bubble rendering a 2×2 grid of image attachments with a +N overflow tile" />
</Frame>

The count-based image grid (1 / 2 / 3 / 4 / 5+ with a "+N" overflow tile).

| Property             | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| `tileBorderRadius`   | Corner radius of each image tile.                                 |
| `gridSpacing`        | Gap between tiles.                                                |
| `placeholderColor`   | Fill shown while a tile loads, and behind the "no preview" glyph. |
| `overflowScrimColor` | Scrim over the "+N" tile when there are more images than cells.   |
| `overflowTextStyle`  | Text style of the "+N" count.                                     |
| `captionTextStyle`   | Text style of the caption below the grid.                         |

### Videos Bubble — `CometChatVideosBubbleStyle`

<Frame>
  <img alt="Videos bubble rendering a 2×2 grid of video attachments with play badges and a +N overflow tile" />
</Frame>

The video grid — poster frames under a play badge, with an optional duration chip.

| Property                                   | Description                             |
| ------------------------------------------ | --------------------------------------- |
| `tileBorderRadius`                         | Corner radius of each video tile.       |
| `gridSpacing`                              | Gap between tiles.                      |
| `placeholderColor`                         | Poster placeholder fill.                |
| `playIconBackgroundColor`                  | Background of the centered play badge.  |
| `playIconColor`                            | Play glyph colour.                      |
| `nameTextStyle`                            | Text style for a video's name label.    |
| `durationChipBackgroundColor`              | Background of the `m:ss` duration pill. |
| `durationChipTextStyle`                    | Duration-pill text style.               |
| `showVideoDuration`                        | Whether to show the duration chip.      |
| `overflowScrimColor` / `overflowTextStyle` | The "+N" overflow tile.                 |
| `captionTextStyle`                         | Caption text style.                     |

### Audios Bubble — `CometChatAudiosBubbleStyle`

<Frame>
  <img alt="Audios bubble rendering a stack of inline audio player rows with a Show more toggle" />
</Frame>

The stack of inline audio-file player rows (picked audio files, not voice notes).

| Property                                                         | Description                    |
| ---------------------------------------------------------------- | ------------------------------ |
| `rowBackgroundColor`                                             | Background of each player row. |
| `rowBorderRadius`                                                | Row corner radius.             |
| `rowSpacing`                                                     | Gap between rows.              |
| `playIconBackgroundColor`                                        | Play/pause circle background.  |
| `playIconColor`                                                  | Play/pause glyph colour.       |
| `sliderActiveColor` / `sliderInactiveColor` / `sliderThumbColor` | Seek-bar colours.              |
| `nameTextStyle`                                                  | File-name text style.          |
| `durationTextStyle`                                              | Elapsed/total time text style. |
| `downloadIconColor`                                              | Download icon colour.          |
| `captionTextStyle`                                               | Caption text style.            |

### Files Bubble — `CometChatFilesBubbleStyle`

<Frame>
  <img alt="Files bubble rendering a stack of document cards with type icon, name, size and download, plus a Show more toggle" />
</Frame>

The list of document/file cards (icon + name + download).

| Property            | Description                                          |
| ------------------- | ---------------------------------------------------- |
| `backgroundColor`   | File-card background.                                |
| `cardBorderRadius`  | Card corner radius.                                  |
| `cardSpacing`       | Gap between cards.                                   |
| `iconPlateColor`    | Background plate behind the file-type icon.          |
| `titleTextStyle`    | File-name text style.                                |
| `subtitleTextStyle` | Size / type line text style.                         |
| `downloadIconTint`  | Download icon tint.                                  |
| `toggleTextStyle`   | "Show more / less" toggle text style (for 4+ files). |
| `captionTextStyle`  | Caption text style.                                  |

### Media Grid — `CometChatMediaGridStyle`

The lower-level grid the **Images** and **Videos** bubbles build on. Most apps style via the two bubble classes above; register `CometChatMediaGridStyle` directly only to control the grid layer everywhere at once.

| Property                                                | Description                                                    |
| ------------------------------------------------------- | -------------------------------------------------------------- |
| `cellBorderRadius`                                      | Grid-cell corner radius.                                       |
| `placeholderColor`                                      | Cell placeholder fill.                                         |
| `playBadgeBackgroundColor` / `playBadgeIconColor`       | Video play badge.                                              |
| `durationChipBackgroundColor` / `durationChipTextStyle` | Duration pill.                                                 |
| `nameTextStyle`                                         | Cell name text style.                                          |
| `overflowScrimColor` / `overflowTextStyle`              | The "+N" overflow tile.                                        |
| `showVideoDuration`                                     | Whether to show duration chips.                                |
| `tripleLayout`                                          | Arrangement for a 3-item grid (`auto` / hero-top / hero-left). |
| `heroFraction`                                          | The hero cell's share of a 3-item grid.                        |


# Message Composer
Source: https://www.cometchat.com/docs/ui-kit/flutter/message-composer

Configure CometChat Flutter UI Kit Message Composer for text, media, custom messages, live reactions, editing, rich text, and audio.

## Overview

`CometChatMessageComposer` is a [Widget](/docs/ui-kit/flutter/components-overview#widget) that enables users to write and send a variety of messages, including text, image, video, and custom messages.

Features such as **Live Reaction**, **Attachments**, **Message Editing**, **Rich Text Formatting**, **Code Blocks**, and **Inline Audio Recording** are supported.

`CometChatMessageComposer` is comprised of the following Base Widgets:

| Base Widgets | Description                                                                 |
| ------------ | --------------------------------------------------------------------------- |
| MessageInput | Provides a basic layout for the contents, such as the TextField and buttons |
| ActionSheet  | Presents a list of options in either a list or grid mode                    |

In V6, the composer is powered by `MessageComposerBloc` and decomposed into focused sub-widgets.

## Usage

### Integration

##### 1. Using Navigator to Launch `CometChatMessageComposer`

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    Navigator.push(context, MaterialPageRoute(builder: (context) => CometChatMessageComposer(user: user)));
    ```
  </Tab>
</Tabs>

##### 2. Embedding `CometChatMessageComposer` as a Widget in the build Method

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
    import 'package:flutter/material.dart';

    class MessageComposerScreen extends StatefulWidget {
      const MessageComposerScreen({super.key});

      @override
      State<MessageComposerScreen> createState() => _MessageComposerScreenState();
    }

    class _MessageComposerScreenState extends State<MessageComposerScreen> {
      @override
      Widget build(BuildContext context) {
        return Scaffold(
          body: Column(
            children: [
              Expanded(child: CometChatMessageList(user: user)),
              CometChatMessageComposer(user: user),
            ],
          ),
        );
      }
    }
    ```
  </Tab>
</Tabs>

***

### Actions

##### 1. OnSendButtonClick

The `OnSendButtonClick` event gets activated when the send message button is clicked.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      onSendButtonTap: (BuildContext context, BaseMessage baseMessage, PreviewMessageMode? previewMessageMode) {
        // Handle send
      },
    )
    ```
  </Tab>
</Tabs>

***

##### 2. onChange

Handles changes in the value of text in the input field.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      onChange: (String? text) {
        // Handle text change
      },
    )
    ```
  </Tab>
</Tabs>

***

##### 3. onError

Listens for any errors that occur.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      onError: (e) {
        // Handle error
      },
    )
    ```
  </Tab>
</Tabs>

***

### Filters

`CometChatMessageComposer` widget does not have any available filters.

***

### Events

The `CometChatMessageComposer` Widget does not emit any events of its own.

***

## Customization

### Style

##### 1. CometChatMessageComposerStyle

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      messageComposerStyle: CometChatMessageComposerStyle(
        sendButtonIconBackgroundColor: Color(0xFFF76808),
        secondaryButtonIconColor: Color(0xFFF76808),
        auxiliaryButtonIconColor: Color(0xFFF76808),
      ),
    )
    ```
  </Tab>
</Tabs>

##### 2. MediaRecorder Style

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      messageComposerStyle: CometChatMessageComposerStyle(
        mediaRecorderStyle: CometChatMediaRecorderStyle(
          recordIndicatorBackgroundColor: Color(0xFFF44649),
          recordIndicatorBorderRadius: BorderRadius.circular(20),
        ),
      ),
    )
    ```
  </Tab>
</Tabs>

***

### Functionality

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      placeholderText: "Type a message...",
      disableMentions: true,
    )
    ```
  </Tab>
</Tabs>

## Message Composer Properties

| Property                        | Data Type                                                   | Description                                                                                                                                                                                                                                                                               |
| ------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user`                          | `User?`                                                     | Sets user for the message composer.                                                                                                                                                                                                                                                       |
| `group`                         | `Group?`                                                    | Sets group for the message composer.                                                                                                                                                                                                                                                      |
| `messageComposerStyle`          | `CometChatMessageComposerStyle?`                            | Sets style for the message composer.                                                                                                                                                                                                                                                      |
| `placeholderText`               | `String?`                                                   | Hint text for the input field.                                                                                                                                                                                                                                                            |
| `text`                          | `String?`                                                   | Initial text for the input field.                                                                                                                                                                                                                                                         |
| `onChange`                      | `Function(String text)?`                                    | Callback triggered when text changes.                                                                                                                                                                                                                                                     |
| `textEditingController`         | `TextEditingController?`                                    | Controls the state of the text field.                                                                                                                                                                                                                                                     |
| `maxLine`                       | `int?`                                                      | Maximum number of lines allowed.                                                                                                                                                                                                                                                          |
| `disableMentions`               | `bool?`                                                     | Disables mentions in the composer.                                                                                                                                                                                                                                                        |
| `disableTypingEvents`           | `bool`                                                      | Disables typing events.                                                                                                                                                                                                                                                                   |
| `disableSoundForMessages`       | `bool`                                                      | Disables sound for sent messages.                                                                                                                                                                                                                                                         |
| `parentMessageId`               | `int`                                                       | ID of the parent message (default is 0).                                                                                                                                                                                                                                                  |
| `sendButtonView`                | `Widget?`                                                   | Custom send button widget.                                                                                                                                                                                                                                                                |
| `attachmentIcon`                | `Widget?`                                                   | Custom attachment icon.                                                                                                                                                                                                                                                                   |
| `voiceRecordingIcon`            | `Widget?`                                                   | Custom voice recording icon.                                                                                                                                                                                                                                                              |
| `auxiliaryButtonView`           | `ComposerWidgetBuilder?`                                    | UI component as auxiliary button.                                                                                                                                                                                                                                                         |
| `secondaryButtonView`           | `ComposerWidgetBuilder?`                                    | UI component as secondary button.                                                                                                                                                                                                                                                         |
| `hideVoiceRecordingButton`      | `bool?`                                                     | Hide the voice recording button.                                                                                                                                                                                                                                                          |
| `attachmentOptions`             | `ComposerActionsBuilder?`                                   | Provides options for file attachments.                                                                                                                                                                                                                                                    |
| `hideAttachmentButton`          | `bool?`                                                     | Hide/display attachment button.                                                                                                                                                                                                                                                           |
| `hideImageAttachmentOption`     | `bool?`                                                     | Hide/display image attachment option.                                                                                                                                                                                                                                                     |
| `hideVideoAttachmentOption`     | `bool?`                                                     | Hide/display video attachment option.                                                                                                                                                                                                                                                     |
| `hideAudioAttachmentOption`     | `bool?`                                                     | Hide/display audio attachment option.                                                                                                                                                                                                                                                     |
| `hideFileAttachmentOption`      | `bool?`                                                     | Hide/display file attachment option.                                                                                                                                                                                                                                                      |
| `hidePollsOption`               | `bool?`                                                     | Hide/display polls option.                                                                                                                                                                                                                                                                |
| `onSendButtonTap`               | `Function(BuildContext, BaseMessage, PreviewMessageMode?)?` | Callback when send button is tapped.                                                                                                                                                                                                                                                      |
| `onError`                       | `OnError?`                                                  | Callback to handle errors.                                                                                                                                                                                                                                                                |
| `hideSendButton`                | `bool?`                                                     | Hide/display the send button.                                                                                                                                                                                                                                                             |
| `hideStickersButton`            | `bool?`                                                     | Hide/display the sticker button.                                                                                                                                                                                                                                                          |
| `sendButtonIcon`                | `Widget?`                                                   | Custom send button icon.                                                                                                                                                                                                                                                                  |
| `layout`                        | `CometChatComposerLayout`                                   | Composer skeleton: `singleLine` (default) or `doubleLine`. See [Layout](#layout) below.                                                                                                                                                                                                   |
| `enableRichTextFormatting`      | `bool`                                                      | Master switch for rich text (markdown detection, toolbar, WYSIWYG rendering). Default `true`.                                                                                                                                                                                             |
| `showRichTextFormattingOptions` | `bool`                                                      | Whether the rich text toolbar UI is visible. Default `true`.                                                                                                                                                                                                                              |
| `hideRichTextFormattingOptions` | `Set<FormatType>`                                           | Set of format buttons to hide from the toolbar. Default `{}`.                                                                                                                                                                                                                             |
| `richTextToolbarView`           | `Widget Function(BuildContext, TextEditingController)?`     | Custom rich text toolbar widget.                                                                                                                                                                                                                                                          |
| `onRichTextFormatApplied`       | `void Function(FormatType)?`                                | Callback fired when a toolbar format is applied.                                                                                                                                                                                                                                          |
| `hideBottomSafeArea`            | `bool`                                                      | Hide bottom safe area padding (default: `false`).                                                                                                                                                                                                                                         |
| `resizeToAvoidBottomInset`      | `bool`                                                      | Indicates the parent `Scaffold` uses its default `resizeToAvoidBottomInset: true` and will handle keyboard insets itself. Default `true`. Flip to `false` only if you opt into the composer's internal keyboard-aware spacing and set `resizeToAvoidBottomInset: false` on your Scaffold. |
| `onKeyboardDiagnostics`         | `CometChatKeyboardDiagnosticsCallback?`                     | Debug hook fired on every internal keyboard-state change. Leave `null` in production.                                                                                                                                                                                                     |

***

### Advanced

#### TextFormatters

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      textFormatters: [
        CometChatMentionsFormatter(
          style: CometChatMentionsStyle(
            mentionSelfTextBackgroundColor: Color(0xFFF76808),
            mentionTextBackgroundColor: Colors.white,
            mentionTextColor: Colors.black,
            mentionSelfTextColor: Colors.white,
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

***

#### AttachmentOptions

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      attachmentOptions: (context, user, group, id) {
        return <CometChatMessageComposerAction>[
          CometChatMessageComposerAction(
            id: "Custom Option",
            title: "Custom Option",
            icon: Icon(Icons.add_box, color: Colors.black),
          ),
        ];
      },
    )
    ```
  </Tab>
</Tabs>

***

#### AuxiliaryButton Widget

You can customize the auxiliary button area (mic, sticker, etc.) using the `auxiliaryButtonView` parameter:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      auxiliaryButtonView: (context, user, group, id) {
        return Row(
          children: [
            IconButton(
              icon: Icon(Icons.location_pin, color: Color(0xFF6852D6)),
              onPressed: () {
                // Handle location sharing
              },
            ),
          ],
        );
      },
    )
    ```
  </Tab>
</Tabs>

***

## Layout

The composer skeleton supports two layouts via the `layout` prop:

| Value                                | Description                                                                           |
| ------------------------------------ | ------------------------------------------------------------------------------------- |
| `CometChatComposerLayout.singleLine` | **Default.** Text field and all buttons share a single row.                           |
| `CometChatComposerLayout.doubleLine` | Classic v5 look — text field on its own row, buttons on a second row below a divider. |

All existing props (hide flags, view slots, style, mentions, rich text, voice recording, reply/edit preview, AI options) work identically in both layouts.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      layout: CometChatComposerLayout.doubleLine,
    )
    ```
  </Tab>
</Tabs>

***

## Rich Text Formatting

The composer ships with a WYSIWYG rich-text toolbar that parses Markdown as the user types and renders formatted spans in place. Configuration is done with three flat props.

### Enable with defaults

Rich text is on by default — no props required.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(user: user)
    ```
  </Tab>
</Tabs>

### Show or hide the toolbar UI

`showRichTextFormattingOptions` controls toolbar visibility. When `false`, markdown is still parsed in typed text but no toolbar is rendered.

| Layout       | Toolbar placement                                                      |
| ------------ | ---------------------------------------------------------------------- |
| `singleLine` | Persistent row directly below the text input                           |
| `doubleLine` | Behind an `Aa` toggle in the button row — tapping swaps in the toolbar |

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      showRichTextFormattingOptions: false, // parses markdown, no toolbar
    )
    ```
  </Tab>
</Tabs>

### Hide specific format buttons

Pass a `Set<FormatType>` listing the buttons to remove from the toolbar.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      hideRichTextFormattingOptions: const {
        FormatType.strikethrough,
        FormatType.codeBlock,
        FormatType.blockquote,
      },
    )
    ```
  </Tab>
</Tabs>

### Disable rich text entirely

Set `enableRichTextFormatting: false` to behave as a plain text field — no markdown parsing, no toolbar, regardless of the other two props.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      enableRichTextFormatting: false,
    )
    ```
  </Tab>
</Tabs>

### FormatType values

| Value                      | Markdown             |
| -------------------------- | -------------------- |
| `FormatType.bold`          | `**text**`           |
| `FormatType.italic`        | `_text_` or `*text*` |
| `FormatType.underline`     | `<u>text</u>`        |
| `FormatType.strikethrough` | `~~text~~`           |
| `FormatType.inlineCode`    | `` `code` ``         |
| `FormatType.codeBlock`     | ` ```code``` `       |
| `FormatType.link`          | `[text](url)`        |
| `FormatType.bulletList`    | `- item`             |
| `FormatType.orderedList`   | `1. item`            |
| `FormatType.blockquote`    | `> quote`            |

### Custom toolbar view

`richTextToolbarView` receives the active controller. Because the controller is a `RichTextEditingController` under the hood, apply formats directly via `applyFormat`.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      richTextToolbarView: (context, controller) {
        return Row(
          children: [
            IconButton(
              icon: const Icon(Icons.format_bold),
              onPressed: () {
                (controller as RichTextEditingController).applyFormat(FormatType.bold);
              },
            ),
            IconButton(
              icon: const Icon(Icons.format_italic),
              onPressed: () {
                (controller as RichTextEditingController).applyFormat(FormatType.italic);
              },
            ),
          ],
        );
      },
      onRichTextFormatApplied: (formatType) {
        debugPrint('Applied ${formatType.name}');
      },
    )
    ```
  </Tab>
</Tabs>

***

## Multiple Attachments

The composer can stage several media/file attachments and send them as one message.

1. **Pick** — the image/video option opens a multi-select picker, capped to the slots left on the message. Audio and documents are multi-select too.
2. **Stage** — each pick lands in the **attachment tray** as a tile with a live progress ring, and starts uploading immediately.
3. **Send** — the send button stays disabled until every tile finishes. Text typed alongside rides along as the **caption**, with rich-text formatting preserved as Markdown.

Files can also arrive by **clipboard paste** (images, video, audio, documents) and, on web, by **drag-and-drop** onto the composer.

A selection spanning several kinds is split by kind and sent as one message per kind, in the order image → video → audio → file. Every message therefore carries a single kind and renders with that kind's bubble — pick three photos and a PDF and the photos still arrive as an image grid, the PDF as a file card. They share a `batchId`, so the [Message List](/docs/ui-kit/flutter/message-list#multiple-attachments) groups them as one block.

<Note>
  Voice notes are never staged — a recording is always its own message and sends immediately. While the tray holds any tile, the mic button is hidden.
</Note>

### Limits and Validation

Limits come from your app's settings in the [CometChat dashboard](https://app.cometchat.com) and are read at runtime — the UI Kit does not hardcode them.

| Limit             | Setting                          | Behaviour                                                                                                                          |
| ----------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Files per message | `file.count.max` (default 10)    | The picker is capped to the remaining slots. A selection larger than that is rejected **whole**, with a toast — nothing is staged. |
| Per-file size     | `file.size.max` (default 100 MB) | An over-sized file becomes a non-retryable error tile stating the limit.                                                           |
| File type         | Server-side                      | Rejected uploads become error tiles.                                                                                               |

Error tiles come in two flavours and behave differently:

* **Failed** (network dropped) — tap the tile to **retry** it in place.
* **Rejected** (too large, wrong type, over the count) — not retryable; tapping explains why, and you remove the tile.

Sending is blocked while any tile is uploading **or** in error, so a caption can never go out while its attachments are still in flight.

### Disabling Multiple Attachments

Multiple attachments are on by default. Turn them off to restore the classic one-file-per-message behaviour.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      enableMultipleAttachments: false,
    )
    ```
  </Tab>
</Tabs>

<Warning>
  This is composer-side only. Incoming messages carrying several attachments still render as grouped bubbles — that is controlled by `enableMultipleAttachments` on [`CometChatMessageList`](/docs/ui-kit/flutter/message-list#multiple-attachments).
</Warning>

### Styling the Attachment Tray

The staging tray's tiles are styled through the composer's own style object.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      messageComposerStyle: CometChatMessageComposerStyle(
        attachmentTrayStyle: CometChatAttachmentTrayStyle(),
      ),
    )
    ```
  </Tab>
</Tabs>

### Style the error alerts

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      // Brief toast shown when a selection is over the count limit.
      errorAlertStyle: CometChatErrorAlertStyle(),
      // Snackbar that explains why a tile failed.
      attachmentErrorSnackBarStyle: CometChatAttachmentErrorSnackBarStyle(),
      // Or replace that snackbar entirely.
      attachmentErrorSnackBarBuilder: (context, tile) => MySnackBar(tile),
      // Called when the user taps an error tile.
      onAttachmentErrorTap: (tile) {},
    )
    ```
  </Tab>
</Tabs>

### Multiple Attachments Properties

| Property                         | Data Type                                        | Description                                                  |
| -------------------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
| `enableMultipleAttachments`      | `bool`                                           | Master switch for staging. Defaults to `true`.               |
| `attachmentTrayController`       | `AttachmentTrayController?`                      | Drive the tray yourself. When omitted the composer owns one. |
| `onAttachmentTrayAdd`            | `VoidCallback?`                                  | Fires when the user taps **+** on the tray.                  |
| `onAttachmentTraySend`           | `VoidCallback?`                                  | Overrides the batch send — you send the messages yourself.   |
| `disableImagePaste`              | `bool`                                           | Turns off clipboard paste. Defaults to `false`.              |
| `disableDragAndDrop`             | `bool`                                           | Turns off drag-and-drop on web. Defaults to `false`.         |
| `errorAlertStyle`                | `CometChatErrorAlertStyle?`                      | Styles the over-limit toast.                                 |
| `attachmentErrorSnackBarStyle`   | `CometChatAttachmentErrorSnackBarStyle?`         | Styles the error-tile snackbar.                              |
| `attachmentErrorSnackBarBuilder` | `Widget Function(BuildContext, AttachmentTile)?` | Replaces the error snackbar.                                 |
| `onAttachmentErrorTap`           | `Function(AttachmentTile)?`                      | Called when an error tile is tapped.                         |

For the upload API underneath the tray, see [Upload Files & Send Attachments](/docs/sdk/flutter/upload-files).

***

## V6 Architecture

### Sub-Widget Decomposition

| Widget                            | Purpose                   |
| --------------------------------- | ------------------------- |
| `AttachmentOptionsOverlay`        | Attachment picker overlay |
| `MessageComposerAuxiliaryButtons` | Auxiliary button area     |
| `MessageComposerSecondaryButtons` | Secondary button area     |
| `MessageComposerSendButton`       | Send button               |
| `MessageComposerSuggestionList`   | Suggestion/mention list   |
| `ComposerAttachmentUtils`         | Attachment utilities      |

### BLoC Architecture

| Component              | Description                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| `MessageComposerBloc`  | Manages composer state                                                                             |
| `MessageComposerEvent` | Events: `SendTextMessage`, `SendMediaMessage`, `EditTextMessage`, `StartTyping`, `EndTyping`, etc. |
| `MessageComposerState` | Composer state                                                                                     |

### Use Cases

| Use Case                   | Description                 |
| -------------------------- | --------------------------- |
| `SendTextMessageUseCase`   | Sends text messages         |
| `SendMediaMessageUseCase`  | Sends media messages        |
| `SendCustomMessageUseCase` | Sends custom messages       |
| `EditMessageUseCase`       | Edits messages              |
| `TypingUseCases`           | Start/end typing indicators |
| `GetLoggedInUserUseCase`   | Gets the logged-in user     |


# Message Header
Source: https://www.cometchat.com/docs/ui-kit/flutter/message-header

Configure CometChat Flutter UI Kit Message Header with user or group details, presence, typing indicators, navigation, and actions.

`CometChatMessageHeader` renders the header of a chat conversation showing user/group avatar, name, online/offline status, typing indicators, back navigation, and action buttons (call buttons, menu).

<Frame>
  <img />
</Frame>

***

## Where It Fits

`CometChatMessageHeader` is a toolbar component. It sits at the top of a chat screen above `CometChatMessageList` and `CometChatMessageComposer`. It automatically shows typing indicators and user presence in real-time.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    Scaffold(
      body: Column(
        children: [
          CometChatMessageHeader(user: user),
          Expanded(child: CometChatMessageList(user: user)),
          CometChatMessageComposer(user: user),
        ],
      ),
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
    import 'package:flutter/material.dart';

    class ChatScreen extends StatelessWidget {
      final User user;
      const ChatScreen({super.key, required this.user});

      @override
      Widget build(BuildContext context) {
        return Scaffold(
          appBar: PreferredSize(
            preferredSize: const Size.fromHeight(60),
            child: CometChatMessageHeader(user: user),
          ),
          body: Column(
            children: [
              Expanded(child: CometChatMessageList(user: user)),
              CometChatMessageComposer(user: user),
            ],
          ),
        );
      }
    }
    ```
  </Tab>
</Tabs>

For group chats, pass a `Group` object instead:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageHeader(group: group)
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and a valid `User` or `Group` object.

***

## Actions and Events

### Callback Methods

#### `onBack`

Fires when the user presses the back button.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageHeader(
      user: user,
      onBack: () {
        Navigator.pop(context);
      },
    )
    ```
  </Tab>
</Tabs>

#### `onError`

Fires on internal errors.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageHeader(
      user: user,
      onError: (e) {
        debugPrint("Error: ${e.message}");
      },
    )
    ```
  </Tab>
</Tabs>

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

| SDK Listener                                  | Internal behavior                           |
| --------------------------------------------- | ------------------------------------------- |
| `onUserOnline` / `onUserOffline`              | Updates online/offline status and last seen |
| `onTypingStarted` / `onTypingEnded`           | Shows/hides typing indicator in subtitle    |
| `onGroupMemberJoined` / `onGroupMemberLeft`   | Updates group member count                  |
| `onGroupMemberKicked` / `onGroupMemberBanned` | Updates group member count                  |
| `onMemberAddedToGroup`                        | Updates group member count                  |
| `ccOwnershipChanged`                          | Updates group owner info                    |
| `onUserBlocked` / `onUserUnblocked`           | Updates user blocked state                  |
| Connection reconnected                        | Refreshes user/group data                   |

***

## Functionality

| Property                 | Type            | Default | Description                                                  |
| ------------------------ | --------------- | ------- | ------------------------------------------------------------ |
| `user`                   | `User?`         | `null`  | User object for 1:1 chat header                              |
| `group`                  | `Group?`        | `null`  | Group object for group chat header                           |
| `showBackButton`         | `bool?`         | `true`  | Toggle back button visibility                                |
| `backButton`             | `Widget?`       | `null`  | Custom back button widget                                    |
| `appBarOptions`          | `List<Widget>?` | `null`  | Additional widgets in the app bar (e.g., call buttons, menu) |
| `hideUserStatus`         | `bool?`         | `false` | Hide online/offline status for users                         |
| `disableTypingIndicator` | `bool?`         | `false` | Disable typing indicator display                             |

***

## Custom View Slots

### Subtitle View

Replace the default subtitle (online status / typing indicator / member count).

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageHeader(
      user: user,
      subtitleView: (user, group) {
        if (user != null) {
          return Text(
            user.status == "online" ? "Active now" : "Last seen recently",
            style: TextStyle(color: Color(0xFF727272), fontSize: 12),
          );
        }
        if (group != null) {
          return Text(
            "${group.membersCount} members",
            style: TextStyle(color: Color(0xFF727272), fontSize: 12),
          );
        }
        return null;
      },
    )
    ```
  </Tab>
</Tabs>

### Leading View

Replace the avatar / left section.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageHeader(
      user: user,
      leadingView: (user, group) {
        return CircleAvatar(
          backgroundImage: NetworkImage(user?.avatar ?? ""),
          child: user?.avatar == null ? Text(user?.name?[0] ?? "") : null,
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Title View

Replace the name / title text.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageHeader(
      user: user,
      titleView: (user, group) {
        return Text(
          user?.name ?? group?.name ?? "",
          style: TextStyle(fontWeight: FontWeight.bold, fontSize: 16),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Trailing View

Replace the right section (call buttons, menu, etc.).

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageHeader(
      user: user,
      trailingView: (user, group) {
        return Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            IconButton(icon: Icon(Icons.call), onPressed: () {}),
            IconButton(icon: Icon(Icons.videocam), onPressed: () {}),
            IconButton(icon: Icon(Icons.info_outline), onPressed: () {}),
          ],
        );
      },
    )
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Header with info button for groups

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageHeader(
      group: group,
      trailingView: (user, group) {
        return IconButton(
          icon: Icon(Icons.info_outline),
          onPressed: () {
            Navigator.push(context, MaterialPageRoute(
              builder: (context) => GroupInfoScreen(group: group!),
            ));
          },
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Hide back button (embedded in tab layout)

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageHeader(
      user: user,
      showBackButton: false,
    )
    ```
  </Tab>
</Tabs>

***

## Advanced

### BLoC Access

Provide a custom `MessageHeaderBloc`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageHeader(
      user: user,
      messageHeaderBloc: CustomMessageHeaderBloc(),
    )
    ```
  </Tab>
</Tabs>

### Public BLoC Methods

| Method                | Returns                           | Description                                     |
| --------------------- | --------------------------------- | ----------------------------------------------- |
| `getTypingNotifier()` | `ValueNotifier<TypingIndicator?>` | Typing indicator notifier for isolated rebuilds |

***

## Style

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageHeader(
      user: user,
      messageHeaderStyle: CometChatMessageHeaderStyle(
        backgroundColor: Colors.white,
        avatarStyle: CometChatAvatarStyle(
          borderRadius: BorderRadius.circular(8),
        ),
        statusIndicatorStyle: CometChatStatusIndicatorStyle(),
        typingIndicatorStyle: CometChatTypingIndicatorStyle(),
      ),
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img />
</Frame>

### Style Properties

| Property               | Description                 |
| ---------------------- | --------------------------- |
| `backgroundColor`      | Header background color     |
| `avatarStyle`          | Avatar appearance           |
| `statusIndicatorStyle` | Online/offline indicator    |
| `typingIndicatorStyle` | Typing indicator text style |

See [Component Styling](/docs/ui-kit/flutter/component-styling) for the full reference.

***

## Next Steps

<CardGroup>
  <Card title="Message List" icon="comments" href="/ui-kit/flutter/message-list">
    Display messages in a conversation
  </Card>

  <Card title="Message Composer" icon="pen" href="/ui-kit/flutter/message-composer">
    Compose and send messages
  </Card>

  <Card title="Call Buttons" icon="phone" href="/ui-kit/flutter/call-buttons">
    Add voice and video call buttons
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/flutter/component-styling">
    Detailed styling reference
  </Card>
</CardGroup>


# Message List
Source: https://www.cometchat.com/docs/ui-kit/flutter/message-list

Scrollable list of messages for a conversation with real-time updates, reactions, threaded replies, and message actions.

`CometChatMessageList` renders a scrollable list of messages for a conversation with real-time updates for new messages, edits, deletions, reactions, and threaded replies.

***

## Where It Fits

`CometChatMessageList` is a message display component. It requires either a `User` or `Group` object to fetch and render messages. Wire it with `CometChatMessageHeader` and `CometChatMessageComposer` to build a complete messaging layout.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

Using Navigator:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    Navigator.push(context, MaterialPageRoute(builder: (context) => CometChatMessageList(user: user)));
    ```
  </Tab>
</Tabs>

Embedding as a widget:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    @override
    Widget build(BuildContext context) {
      return Scaffold(
        body: SafeArea(
          child: CometChatMessageList(
            user: user, // or group: group
          ),
        ),
      );
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

<Warning>
  Simply adding the `MessageList` component to the layout will only display the loading indicator. You must supply a `User` or `Group` object to fetch messages.
</Warning>

***

## Filtering

Pass a `MessagesRequestBuilder` to control what loads:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      messagesRequestBuilder: MessagesRequestBuilder()
        ..uid = user.uid
        ..searchKeyword = "hello"
        ..limit = 30,
    )
    ```
  </Tab>
</Tabs>

<Note>
  The following parameters in `MessagesRequestBuilder` will always be altered inside the message list: UID, GUID, types, categories.
</Note>

***

## Actions and Events

### Callback Methods

#### `onThreadRepliesClick`

Fires when a user taps a threaded message bubble.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      onThreadRepliesClick: (message, context, {template}) {
        // Navigate to thread view
      },
    )
    ```
  </Tab>
</Tabs>

#### `onError`

Fires on internal errors.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      onError: (e) {
        debugPrint("Error: ${e.message}");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched and loaded.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      onLoad: (messages) {
        debugPrint("Loaded ${messages.length}");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      onEmpty: () {
        debugPrint("No messages");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onReactionClick`

Fires when a reaction pill is tapped.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      onReactionClick: (emoji, message) {
        // Handle reaction click
      },
    )
    ```
  </Tab>
</Tabs>

#### `onReactionLongPress`

Fires when a reaction pill is long-pressed.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      onReactionLongPress: (emoji, message) {
        // Handle reaction long press
      },
    )
    ```
  </Tab>
</Tabs>

### SDK Events (Real-Time, Automatic)

The component listens to SDK message events internally. No manual setup needed.

| SDK Listener                                                                   | Internal behavior                             |
| ------------------------------------------------------------------------------ | --------------------------------------------- |
| `onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived` | Inserts new message with animation            |
| `onMessageEdited`                                                              | Updates message in-place                      |
| `onMessageDeleted`                                                             | Removes or marks message as deleted           |
| `onMessagesDelivered` / `onMessagesRead`                                       | Updates receipt status via ValueNotifier      |
| `onTypingStarted` / `onTypingEnded`                                            | Updates typing indicator                      |
| `onMessageReactionAdded` / `onMessageReactionRemoved`                          | Updates reaction counts                       |
| Connection reconnected                                                         | Triggers silent sync to fetch missed messages |

***

## Functionality

| Property                    | Type                                | Default    | Description                                                                                                           |
| --------------------------- | ----------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- |
| `user`                      | `User?`                             | required\* | User for 1-on-1 conversation                                                                                          |
| `group`                     | `Group?`                            | required\* | Group for group conversation                                                                                          |
| `parentMessageId`           | `int?`                              | `null`     | Parent message ID for thread replies                                                                                  |
| `alignment`                 | `ChatAlignment`                     | `standard` | Chat alignment setting                                                                                                |
| `hideDeletedMessages`       | `bool`                              | `false`    | Hide deleted messages entirely                                                                                        |
| `disableReceipts`           | `bool`                              | `false`    | Disable read/delivery receipts                                                                                        |
| `disableSoundForMessages`   | `bool`                              | `false`    | Disable message sounds                                                                                                |
| `hideReplies`               | `bool`                              | `true`     | Hide thread replies in main conversation                                                                              |
| `hideGroupActionMessages`   | `bool?`                             | `false`    | Hide group action messages                                                                                            |
| `hideTimestamp`             | `bool?`                             | `null`     | Toggle timestamp visibility                                                                                           |
| `hideDateSeparator`         | `bool?`                             | `false`    | Hide date separators                                                                                                  |
| `hideStickyDate`            | `bool?`                             | `false`    | Hide floating sticky date header                                                                                      |
| `avatarVisibility`          | `bool?`                             | `true`     | Toggle avatar visibility                                                                                              |
| `receiptsVisibility`        | `bool?`                             | `true`     | Toggle read receipts                                                                                                  |
| `disableReactions`          | `bool?`                             | `false`    | Toggle reactions                                                                                                      |
| `enableMultipleAttachments` | `bool`                              | `true`     | Render multi-attachment media messages as grouped per-type bubbles. See [Multiple Attachments](#multiple-attachments) |
| `enableSwipeToReply`        | `bool`                              | `true`     | Enable swipe-to-reply gesture                                                                                         |
| `startFromUnreadMessages`   | `bool`                              | `false`    | Scroll to first unread on open                                                                                        |
| `loadLastAgentConversation` | `bool`                              | `false`    | Loads the most recent existing agent conversation on start                                                            |
| `showMarkAsUnreadOption`    | `bool`                              | `false`    | Show "Mark as Unread" in long-press options                                                                           |
| `goToMessageId`             | `int?`                              | `null`     | Scroll to a specific message after load                                                                               |
| `hideFlagOption`            | `bool`                              | `false`    | Hide the Flag/Report option from message long-press actions                                                           |
| `hideFlagRemarkField`       | `bool`                              | `false`    | Hide the optional remark/context text field in the flag dialog                                                        |
| `flagReasonLocalizer`       | `String Function(String reasonId)?` | `null`     | Custom localizer that converts a flag-reason ID into a display string                                                 |

\* One of `user` or `group` is required.

***

## Custom View Slots

### Header View

Custom view displayed at the top of the message list.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      headerView: (context, {user, group, parentMessageId}) {
        return Container(
          padding: EdgeInsets.all(8),
          child: Text("Pinned Messages"),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Footer View

Custom view displayed at the bottom of the message list.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      footerView: (context, {user, group, parentMessageId}) {
        return Container(
          padding: EdgeInsets.all(8),
          child: Text("End of messages"),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      emptyStateView: (context) => Center(child: Text("No messages yet")),
      errorStateView: (context) => Center(child: Text("Something went wrong")),
      loadingStateView: (context) => Center(child: CircularProgressIndicator()),
      emptyChatGreetingView: (context) => Center(child: Text("Say hello!")),
    )
    ```
  </Tab>
</Tabs>

### Text Formatters (Mentions)

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      textFormatters: [
        CometChatMentionsFormatter(),
      ],
    )
    ```
  </Tab>
</Tabs>

### Message Templates

Override or extend message bubble rendering:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // Replace all templates
    CometChatMessageList(
      user: user,
      templates: getCustomTemplates(),
    )

    // Add/override specific templates (merged with defaults)
    CometChatMessageList(
      user: user,
      addTemplate: [
        CometChatMessageTemplate(
          type: MessageTypeConstants.text,
          category: MessageCategoryConstants.message,
          contentView: (message, context, alignment, {additionalConfigurations}) {
            return Text((message as TextMessage).text,
              style: TextStyle(color: Colors.red));
          },
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

See [Message Template](/docs/ui-kit/flutter/message-template) for the full template structure.

***

## Multiple Attachments

A media message carrying several attachments renders with a dedicated per-type bubble: a **media grid** for images and videos, **inline player rows** for audio files, and a **connected card stack** for documents.

| Message type         | Bubble                  | Rendering                                                |
| -------------------- | ----------------------- | -------------------------------------------------------- |
| `image`              | `CometChatImagesBubble` | Grid — 1, 2, 3 or 2×2, with a `+N` tile past 4           |
| `video`              | `CometChatVideosBubble` | Grid with poster frames, a play badge and an `m:ss` chip |
| `audio` (files)      | `CometChatAudiosBubble` | Stacked player rows; collapses past 4                    |
| `audio` (voice note) | `CometChatAudioBubble`  | The classic waveform player                              |
| `file`               | `CometChatFilesBubble`  | Connected card stack with a "+N more" toggle             |

Tapping any image/video cell opens the full-screen media viewer, paged across the message's image, video and audio attachments.

<Note>
  A **voice note** always renders as the classic single audio bubble, whatever the flag below — it is single by nature. Only picked audio *files* use the multi-attachment bubble.
</Note>

A message always carries attachments of a single kind, so each one renders with the bubble for that kind. Picking a mix — say three photos and a PDF — sends an `image` message and a `file` message: the photos render as a grid, the PDF as a card. They share a `batchId` and group as described below.

### Grouping

Messages produced by one send share `batchId`, `batchIndex` and `batchSize` metadata, and the list presents them as one block:

* the avatar and sender name appear on the **first** message only
* the timestamp and receipt appear on the **last** message only
* reactions stay attached to their individual message
* the caption rides on the **last** message of the batch

Deleting one message of a batch takes it out of the group: it renders as a standalone delete bubble, and its neighbours treat it as a batch boundary.

### Enable or disable

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      enableMultipleAttachments: true, // default
    )
    ```
  </Tab>
</Tabs>

Set it to `false` to render the classic single-attachment bubbles (`CometChatImageBubble`, `CometChatVideoBubble`, `CometChatAudioBubble`, `CometChatFileBubble`) instead. Those bubbles are **deprecated** and remain only for that path.

You can also drive it per-template through `AdditionalConfigurations`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    AdditionalConfigurations(enableMultipleAttachments: false)
    ```
  </Tab>
</Tabs>

### Styling

Each bubble has its own style class:

| Bubble                  | Style                        |
| ----------------------- | ---------------------------- |
| `CometChatImagesBubble` | `CometChatImagesBubbleStyle` |
| `CometChatVideosBubble` | `CometChatVideosBubbleStyle` |
| `CometChatAudiosBubble` | `CometChatAudiosBubbleStyle` |
| `CometChatFilesBubble`  | `CometChatFilesBubbleStyle`  |

Where a property has an equivalent on the old singular bubble it keeps the same name (`playIconColor`, `titleTextStyle`, `backgroundColor`…), so migrating is a rename of the class, not of every field. Grid-only knobs — `tileBorderRadius`, `gridSpacing`, `overflowScrimColor`, `captionTextStyle`, the duration chip and the "+N more" toggle — have no old counterpart.

<Warning>
  These bubbles are styled **only** through theme extensions. The per-message-list slots — `AdditionalConfigurations.imageBubbleStyle` and `CometChatIncoming/OutgoingMessageBubbleStyle.imageBubbleStyle` — still target the **deprecated** singular bubbles and are ignored while `enableMultipleAttachments` is `true`. Move that styling into the theme.
</Warning>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    MaterialApp(
      theme: ThemeData(
        extensions: const [
          CometChatImagesBubbleStyle(gridSpacing: 3, tileBorderRadius: 8),
          CometChatVideosBubbleStyle(showVideoDuration: true),
          CometChatFilesBubbleStyle(titleTextStyle: TextStyle(fontSize: 15)),
        ],
      ),
    )
    ```
  </Tab>
</Tabs>

To stage and send multiple attachments, see [Message Composer](/docs/ui-kit/flutter/message-composer#multiple-attachments).

***

## Message Option Visibility

| Property                     | Default | Description              |
| ---------------------------- | ------- | ------------------------ |
| `hideCopyMessageOption`      | `false` | Hide "Copy Message"      |
| `hideDeleteMessageOption`    | `false` | Hide "Delete Message"    |
| `hideEditMessageOption`      | `false` | Hide "Edit Message"      |
| `hideMessageInfoOption`      | `false` | Hide "Message Info"      |
| `hideMessagePrivatelyOption` | `false` | Hide "Message Privately" |
| `hideReactionOption`         | `fa