> ## 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 Settings

> Every setting in the exported UI Kit Builder settings file for Next.js — chat features, calling, layout and style — with what each one does.

Your choices in the UI Kit Builder are exported as a JSON file. Editing that file is the supported way to change features after export: no component code changes.

## Where the settings live

| File | Role |
| - | - |
| `src/builder/cometchat-builder-settings.json` | **Your settings.** Written by the dashboard at export, and safe to edit by hand afterwards |
| `src/builder/builderSettings.ts` | Loads the JSON and exports `builderSettings` |
| `src/CometChat/config/settings.types.ts` | The TypeScript types, including `CometChatSettingsInterface` |
| `src/CometChat/config/defaultSettings.ts` | The fallback for every key. Exports `storedSettingsDefaults`, used whenever a settings file is present — which is always, in an exported app |

The file has this shape:

```json theme={null}
{
  "builderId": "…",
  "settings": {
    "chatFeatures": { },
    "callFeatures": { },
    "layout": { },
    "style": { }
  }
}
```

`CometChatNoSSR.tsx` passes `builderSettings` to `<SettingsProvider>`, which merges it over the defaults.

> [!NOTE]
>
> **Every key is optional.** Anything the file leaves out uses its default, so a
> partial file — or one exported before a newer setting existed — still works.
> Arrays such as `layout.tabs` replace the default rather than merging with it.

Inside the app, components read the resolved settings with `useSettings()` from `src/CometChat/config/SettingsContext`.

> [!WARNING]
>
> In [v6](https://www.cometchat.com/docs/ui-kit/react/v6/overview.md) these settings lived in a TypeScript file, `src/CometChat/CometChatSettings.ts`, and a few app-level options (`showGroupActionMessages`, `autoOpenFirstItem`) were props on `CometChatApp`. Both are gone in [React UI Kit v7](https://www.cometchat.com/docs/ui-kit/react/overview.md): settings are JSON in `src/builder/`, and there is no `CometChatApp`. See [Integration](https://www.cometchat.com/docs/chat-builder/nextjs/integration.md).

***

## 1. Chat Features (`chatFeatures`)

### 1.1 Core messaging experience (`coreMessagingExperience`)

| Property | Default | Description |
| - | - | - |
| `typingIndicator` | `true` | Displays when a user is typing |
| `threadConversationAndReplies` | `true` | Enables threaded conversations and replies |
| `photosSharing` | `true` | Allows sharing of images |
| `videoSharing` | `true` | Supports video file sharing |
| `audioSharing` | `true` | Enables sharing of audio recordings |
| `fileSharing` | `true` | Allows file sharing |
| `editMessage` | `true` | Enables editing sent messages |
| `deleteMessage` | `true` | Allows users to delete their sent messages |
| `messageDeliveryAndReadReceipts` | `true` | Shows message delivery and read receipts |
| `userAndFriendsPresence` | `true` | Displays users' online/offline status |
| `conversationAndAdvancedSearch` | `true` | Enables conversation and advanced search |
| `moderation` | `true` | Shows the notice when a message is blocked by moderation |
| `richTextFormatting` | `true` | Shows the rich text formatting options (bold, italic, lists, code…) in the composer |
| `quotedReplies` | `false` | Allows quoting messages in replies |
| `markAsUnread` | `false` | Enables marking messages as unread |
| `multipleAttachments` | `false` | Lets users attach several files to one message before sending. When `false`, each attachment sends immediately |
| `pinMessage` | `false` | Offers "Pin" and "Unpin" on a message, and the Pinned Messages entry in the chat header. The marker on an already-pinned message is not affected |
| `saveMessage` | `false` | Offers "Save" and "Unsave" on a message, and the Saved Messages entry in the sidebar menu |
| `pinConversation` | `false` | Offers "Pin" and "Unpin" on a conversation. A conversation that is already pinned stays pinned and keeps its marker |
| `threadSubscription` | `false` | Offers following a thread, and shows the bell in the thread header |

> [!NOTE]
>
> The keys defaulting to `false` are opt-in, and the distinction matters when you edit this file
> by hand. They were each added after settings files already existed, so leaving one out means
> "this file predates the feature" rather than "leave it on" — set it to `true` to use it.
>
> Three of the last four also depend on your plan: `pinMessage`, `saveMessage` and
> `pinConversation` check the app's entitlements at runtime, so setting one to `true` can only
> reveal a feature your plan already includes. `threadSubscription` has no such check.

### 1.2 Deeper user engagement (`deeperUserEngagement`)

| Property | Type | Description |
| - | - | - |
| `mentions` | boolean | Enables @mentions in chat |
| `mentionAll` | boolean | Allows @all to notify every group member |
| `reactions` | boolean | Allows reacting to messages |
| `messageTranslation` | boolean | Provides message translation |
| `polls` | boolean | Enables creating and answering polls |
| `collaborativeWhiteboard` | boolean | Allows real-time whiteboard collaboration |
| `collaborativeDocument` | boolean | Enables document collaboration |
| `voiceNotes` | boolean | Allows sending voice notes |
| `emojis` | boolean | Supports emojis in chat |
| `stickers` | boolean | Allows sending stickers |
| `userInfo` | boolean | Displays the user details panel |
| `groupInfo` | boolean | Displays the group details panel |

### 1.3 AI user copilot (`aiUserCopilot`)

| Property | Type | Description |
| - | - | - |
| `conversationStarter` | boolean | Suggests AI-generated conversation starters |
| `conversationSummary` | boolean | Offers a summary of the conversation |
| `smartReply` | boolean | Suggests replies based on context |

### 1.4 User management (`userManagement`)

| Property | Type | Description |
| - | - | - |
| `friendsOnly` | boolean | Restricts chat to friends only |

### 1.5 Group management (`groupManagement`)

| Property | Type | Description |
| - | - | - |
| `createGroup` | boolean | Allows creating new groups |
| `addMembersToGroups` | boolean | Enables adding members to groups |
| `joinLeaveGroup` | boolean | Allows joining and leaving groups |
| `deleteGroup` | boolean | Enables "Delete and exit" for group owners |
| `viewGroupMembers` | boolean | Shows the group member list |

### 1.6 Moderator controls (`moderatorControls`)

| Property | Type | Description |
| - | - | - |
| `kickUsers` | boolean | Offers "Kick" on a group member |
| `banUsers` | boolean | Offers "Ban" on a group member |
| `promoteDemoteMembers` | boolean | Offers "Change Scope" on a group member |
| `reportMessage` | boolean | Offers "Report" on a received message |

### 1.7 Private messaging within groups (`privateMessagingWithinGroups`)

| Property | Type | Description |
| - | - | - |
| `sendPrivateMessageToGroupMembers` | boolean | Offers "Message Privately" on a message in a group |

### 1.8 In-app sounds (`inAppSounds`)

| Property | Type | Description |
| - | - | - |
| `incomingMessageSound` | boolean | Plays a sound when a message arrives |
| `outgoingMessageSound` | boolean | Plays a sound when a message is sent |

***

## 2. Call Features (`callFeatures`)

### 2.1 Voice and video calling (`voiceAndVideoCalling`)

| Property | Type | Description |
| - | - | - |
| `oneOnOneVoiceCalling` | boolean | Voice call button in one-on-one chats |
| `oneOnOneVideoCalling` | boolean | Video call button in one-on-one chats |
| `groupVoiceConference` | boolean | Voice call button in groups |
| `groupVideoConference` | boolean | Video call button in groups |

> [!NOTE]
>
> Calling also requires `@cometchat/calls-sdk-javascript` to be installed and
> `setCallingEnabled(true)` in your initialization — see
> [Integration](https://www.cometchat.com/docs/chat-builder/nextjs/integration.md).

***

## 3. Layout (`layout`)

| Property | Default | Description |
| - | - | - |
| `withSideBar` | `true` | When `false`, renders a single chat pane with no conversations list |
| `tabs` | all four | Which tabs the sidebar offers, in order — `['chats', 'calls', 'users', 'groups']`. A single tab hides the tab bar |
| `chatType` | `'user'` | `'user'` or `'group'` — which kind of chat opens when there is no sidebar |
| `compactMessageComposer` | `false` | Uses the compact composer instead of the multi-line one |

***

## 4. Style (`style`)

Applied by `src/builder/useBuilderTheme.ts`.

### 4.1 Theme

| Property | Type | Description |
| - | - | - |
| `theme` | string | `'light'`, `'dark'`, or `'system'`. `'system'` follows the operating system setting |

### 4.2 Color

| Property | Type | Description |
| - | - | - |
| `brandColor` | string | Primary UI color (hex, e.g. `'#6852D6'`). The lighter and darker shades used across the UI are derived from it |
| `primaryTextLight` | string | Text color in light mode |
| `primaryTextDark` | string | Text color in dark mode |
| `secondaryTextLight` | string | Secondary text color in light mode |
| `secondaryTextDark` | string | Secondary text color in dark mode |

### 4.3 Typography

| Property | Type | Description |
| - | - | - |
| `font` | string | The UI font family, e.g. `'roboto'`. The UI Kit Builder's Font dropdown lists the supported values |
| `size` | string | `'compact'`, `'default'`, or `'comfortable'` |

> [!NOTE]
>
> The font name is applied as given. A font the browser cannot resolve falls
> back to the system default, so if you set a font of your own, load it in your
> app with `@font-face` or a stylesheet link.

***

## 5. No Code (`noCode`) — ignored by this app

Used only by the CometChat no-code widget. The dashboard may include this section in your export; this app ignores it.

| Property | Type | Description |
| - | - | - |
| `docked` | boolean | Whether the widget is docked |
| `styles.buttonBackGround` | string | Background color for the docked button |
| `styles.buttonShape` | string | Shape of the docked button, e.g. `'rounded'` |
| `styles.openIcon`, `styles.closeIcon` | string | Icons for the docked button |
| `styles.customJs`, `styles.customCss` | string | Custom code applied to the widget |
| `styles.dockedAlignment` | string | `'left'` or `'right'` |

***

## 6. Agent (`agent`) — ignored by this app

Used only by CometChat's AI agent experiences.

| Property | Type | Description |
| - | - | - |
| `chatHistory` | boolean | Access to previous chat history |
| `newChat` | boolean | Starting new conversations |
| `agentIcon` | string | URL or path to the agent's icon |
| `showAgentIcon` | boolean | Whether to display the agent icon |

***

## Example

A partial file that turns off calling and forces dark mode. Everything else keeps its default:

```json theme={null}
{
  "builderId": "your-builder-id",
  "settings": {
    "callFeatures": {
      "voiceAndVideoCalling": {
        "oneOnOneVoiceCalling": false,
        "oneOnOneVideoCalling": false,
        "groupVoiceConference": false,
        "groupVideoConference": false
      }
    },
    "style": {
      "theme": "dark",
      "color": { "brandColor": "#6852D6" }
    }
  }
}
```

> **[Directory Structure](https://www.cometchat.com/docs/chat-builder/nextjs/builder-dir-structure.md)**
>
> Where this file sits, and what else is yours to edit.

> **[Customizations](https://www.cometchat.com/docs/chat-builder/nextjs/builder-customisations.md)**
>
> Go beyond the settings file.


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