> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# UI Kit Builder 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 src="https://mintcdn.com/cometchat-22654f5b/fMPnzFAmFCFD5fSa/images/mobile-chat-builder.png?fit=max&auto=format&n=fMPnzFAmFCFD5fSa&q=85&s=0ec4b6efcc3c29aa365ea80719e14cc4" width="3014" height="1580" data-path="images/mobile-chat-builder.png" />
</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 src="https://mintcdn.com/cometchat-22654f5b/HFXOvmhiLRb5ClID/images/91e1727b-dashboard_features-5d33b046f945728c1521aee216f3555a.png?fit=max&auto=format&n=HFXOvmhiLRb5ClID&q=85&s=72a2f5f7071f3104feab01df7dd851bd" width="3016" height="1594" data-path="images/91e1727b-dashboard_features-5d33b046f945728c1521aee216f3555a.png" />
</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](/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 cols={2}>
  <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>