UI Kit Builder 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.

​

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.

---

​

Requirements

The exported app targets React UI Kit v7:

React	18 or 19
Build tool	Vite (the exported app ships with it) or Create React App
UI Kit	@cometchat/chat-uikit-react v7
TypeScript	jsx: "react-jsx" and resolveJsonModule: true — see Troubleshooting

---

​

Launch the UI Kit Builder

1. Log in to your CometChat Dashboard.
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)

Only checked features will be enabled in your Dashboard. You can always modify these settings later in the CometChat Dashboard.

---

​

Preview Customizations (Optional)

Before integrating the exported app into your project, you can run it on its own. This step is optional — skip it if you want to integrate directly.

1. Open the cometchat-app-react folder.
2. Install dependencies:

npm i

3. Run the app:

npm run dev

Your app credentials are already prepopulated in src/index.tsx.

The exported app is built with Vite, and its entry point stays at src/index.tsx rather than Vite’s usual src/main.tsx, so the credentials block is always in the same place.

---

​

Integrate into Your Project

Follow these steps to integrate the exported app into your existing React project.

​

Step 1: Install Dependencies

npm install @cometchat/chat-uikit-react@^7.2.4 @cometchat/chat-sdk-javascript@^4.2.0 @cometchat/calls-sdk-javascript@^5.0.6

​

Step 2: Copy Two Folders

Copy both of these from the exported app into your project’s src directory:

Folder	What it is
src/CometChat	The CometChat sample app. Treat it as vendored — it is replaced wholesale on every UI Kit release, so edits here are lost.
src/builder	Your builder settings, theming and localization. This is the part you own and customize.

Both are required: src/CometChat reads its configuration from src/builder.

Copying only src/CometChat leaves the app without its settings, theme and localization. The split is deliberate: because your customizations sit outside the vendored folder, a later re-export means copying src/CometChat alone.

​

Step 3: Initialize CometChat UI Kit

Initialization also wires up SettingsProvider, which feeds your builder settings into the app. Select your setup:

Vite

Open src/main.tsx and update it:

import { createRoot } from "react-dom/client";
import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";
import App from "./App";
import "./builder/shell.css"; // Gives the chat UI its full height — required.
import { SettingsProvider } from "./CometChat/config/SettingsContext";
import { builderSettings } from "./builder/builderSettings";
import { setupLocalization } from "./builder/localization";

export const COMETCHAT_CONSTANTS = {
  APP_ID: "", // Replace with your App ID
  REGION: "", // Replace with your App Region
  AUTH_KEY: "", // Replace with your Auth Key
};

const uiKitSettings = new UIKitSettingsBuilder()
  .setAppId(COMETCHAT_CONSTANTS.APP_ID)
  .setRegion(COMETCHAT_CONSTANTS.REGION)
  .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
  .subscribePresenceForAllUsers()
  // Without this the call buttons do not render at all.
  .setCallingEnabled(true)
  .build();

const root = createRoot(document.getElementById("root")!);

Promise.resolve(CometChatUIKit.init(uiKitSettings))
  .then(() => {
    setupLocalization();
    root.render(
      <SettingsProvider settings={builderSettings}>
        <App />
      </SettingsProvider>
    );
  })
  .catch((error) => console.error("CometChat UI Kit failed to initialise", error));

Replacing main.tsx also removes the Vite template’s import "./index.css". Keep it removed, or delete its #root rules (fixed width, centering, text-align: center) — they offset the chat UI and make it overflow the page.

Create React App

Open src/index.tsx and update it:

import ReactDOM from "react-dom/client";
import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";
import App from "./App";
import "./builder/shell.css"; // Gives the chat UI its full height — required.
import { SettingsProvider } from "./CometChat/config/SettingsContext";
import { builderSettings } from "./builder/builderSettings";
import { setupLocalization } from "./builder/localization";

export const COMETCHAT_CONSTANTS = {
  APP_ID: "", // Replace with your App ID
  REGION: "", // Replace with your App Region
  AUTH_KEY: "", // Replace with your Auth Key
};

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

const root = ReactDOM.createRoot(document.getElementById("root") as HTMLElement);

Promise.resolve(CometChatUIKit.init(uiKitSettings))
  .then(() => {
    setupLocalization();
    root.render(
      <SettingsProvider settings={builderSettings}>
        <App />
      </SettingsProvider>
    );
  })
  .catch((error) => console.error("CometChat UI Kit failed to initialise", error));

Your app credentials (APP_ID, AUTH_KEY, REGION) are prepopulated in the exported code. If you need different credentials, find them in the Credentials block of your app’s Overview section on the CometChat Dashboard.

Upgrading from v6? CometChatProvider no longer comes from a local CometChat/context/CometChatContext, setupLocalization has moved to builder/localization, and CometChat/utils/utils and CometChat/CometChatApp no longer exist. The code above is the v7 replacement for all four.

Session storage. To use session storage instead of the default local storage, configure it during initialization — see the Setting Session Storage Mode guide.

​

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, with a CometChat SDK method, or via the API.
2. Use pre-generated test users: cometchat-uid-1 through cometchat-uid-5.

The app shell in Step 5 already handles this for you: it renders CometChatLogin until someone is logged in, and listens for SDK login and logout events afterwards. Use the methods below when you want to log users in from your own flow instead.

Auth Key (prototyping)

import { CometChatUIKit } from "@cometchat/chat-uikit-react";

const user = await CometChatUIKit.login("cometchat-uid-1");
console.log("Logged in:", user);

Auth Token (production)

import { CometChatUIKit } from "@cometchat/chat-uikit-react";

// Fetch the auth token from your backend, then:
const user = await CometChatUIKit.loginWithAuthToken(authToken);
console.log("Logged in:", user);

CometChatUIKit.getLoggedInUser() returns the current user synchronously, or null when nobody is logged in.

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 for details.

---

​

Step 5: Render the App Shell

v7 has no CometChatApp component. src/App.tsx is the integration point, and it is yours to edit:

import "./CometChat/styles/App.css";
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatProvider, CometChatUIKit } from "@cometchat/chat-uikit-react";
import { CometChatHome } from "./CometChat/components/CometChatHome/CometChatHome";
import CometChatLogin from "./CometChat/components/CometChatLogin/CometChatLogin";
import { AppContextProvider } from "./CometChat/context/AppContext";
import { useSettings } from "./CometChat/config/SettingsContext";
import useSystemColorScheme from "./builder/customHooks";
import { useBuilderTheme } from "./builder/useBuilderTheme";

function App() {
  const [loggedInUser, setLoggedInUser] = useState<CometChat.User | null>(null);
  const { style } = useSettings();
  const systemTheme = useSystemColorScheme();

  // The UI Kit accepts only 'light' | 'dark' — resolving 'system' is the consumer's job.
  const theme: "light" | "dark" =
    style.theme === "light" || style.theme === "dark" ? style.theme : systemTheme;

  useBuilderTheme(style, theme);

  useEffect(() => {
    setLoggedInUser(CometChatUIKit.getLoggedInUser() ?? null);

    CometChat.addLoginListener(
      "app-login-listener",
      new CometChat.LoginListener({
        loginSuccess: (user: CometChat.User) => setLoggedInUser(user),
        logoutSuccess: () => setLoggedInUser(null),
      })
    );

    return () => CometChat.removeLoginListener("app-login-listener");
  }, []);

  const handleLogout = async () => {
    await CometChatUIKit.logout();
    setLoggedInUser(null);
  };

  return (
    /* The chat UI fills its parent, so give it explicit dimensions. */
    <div className="App" style={{ width: "100vw", height: "100dvh" }}>
      <CometChatProvider theme={theme} locale="en-us">
        <AppContextProvider>
          {loggedInUser ? (
            <CometChatHome loggedInUser={loggedInUser} onLogout={handleLogout} />
          ) : (
            <CometChatLogin onLoginSuccess={setLoggedInUser} />
          )}
        </AppContextProvider>
      </CometChatProvider>
    </div>
  );
}

export default App;

Sizing. .App sets the size — change its style to fit the chat into part of your page. The .cometchat element that CometChatProvider renders inside it has no height of its own; src/builder/shell.css, imported in Step 3, makes it fill .App. If you don’t import that file, add this to your own CSS — without it the chat shrinks to its content and the message composer is pushed off-screen:

.App > .cometchat {
  height: 100%;
}

---

​

Step 6: Customize Through Settings

Layout and feature choices live in src/builder/cometchat-builder-settings.json, which the dashboard writes at export time and which you can edit by hand afterwards. Anything the file omits falls back to a default, so partial files are safe.

Setting	Effect
layout.withSideBar	false renders a single chat pane with no conversations list.
layout.chatType	user or group — which chat opens when there is no sidebar.
style.theme	light, dark, or system.
style.color, style.typography	Brand color, text colors and font, applied by useBuilderTheme.
chatFeatures.*, callFeatures.*	Per-feature toggles, mapped to UI Kit props by buildFeatureProps.

Group action messages (joins, leaves, kicks, bans) are the exception: there is no settings key for them. They are on by default, and the only way to change that from code is the showGroupActionMessages prop on CometChatHome — the same prop v6 had on CometChatApp. Whether they are generated at all is an app-level choice: Chat > Settings > Include Group Actions in the dashboard.

Every setting is described in UI Kit Builder Settings.

​

Step 7: Run the App

Vite

npm run dev

Create React App

npm start

---

​

Troubleshooting

TypeScript configuration. Check that your TypeScript config includes both of these. In a Vite project that is tsconfig.app.json, not the root tsconfig.json. New Vite and Create React App projects already have them:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "resolveJsonModule": true
  }
}

resolveJsonModule is required — builderSettings imports the settings JSON directly. Restart your dev server after changing it.

The chat renders but has no height. src/builder/shell.css is not imported, or your own CSS overrides it. See the sizing note in Step 5.

No call buttons in the message header. setCallingEnabled(true) is missing from the initialization in Step 3. Calling is off by default, and the header hides both buttons entirely rather than rendering them inert.

Call buttons render but calls fail. @cometchat/calls-sdk-javascript is not installed.

The chat is off-centre or overflows the page. The Vite template’s index.css is still imported; its #root rules fight the chat’s layout. See the note in Step 3.

---

​

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, settings, and styling directly in your project.

Customizations

Adjust component props, behavior, and UI elements.

UI Kit Builder Settings

Understand the settings file and feature toggles.

Directory Structure

See how the exported code is organized.

Advanced Theming

Customize colors, typography, and styling to match your brand.

​

Customize via UI Kit Builder

Return to the Builder to update your configuration, then re-export. Because your customizations live in src/builder, a re-export only needs src/CometChat replaced — unless you also changed settings in the Builder, in which case copy src/builder/cometchat-builder-settings.json across too.

Launch UI Kit Builder

Open the CometChat Dashboard to reconfigure and re-export.

---