UI Kit Builder Integration

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.

The UI Kit Builder exports a React code package. There is no separate React Router export — this guide covers dropping that package into a React Router project, whether it renders entirely in the browser or uses framework mode with server rendering.

Complete Integration Workflow

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

Requirements

The exported app targets React UI Kit v7:


React	18 or 19
React Router	v6 or v7 — either a browser-only app (`react-router-dom` in Vite) or v7 framework mode
UI Kit	`@cometchat/chat-uikit-react` v7
TypeScript	`jsx: "react-jsx"` and `resolveJsonModule: true` — see Troubleshooting

If your app uses React Router v7 framework mode, which server-renders by default, read Framework mode and SSR before Step 3 — the chat has to be kept off the server.

Launch the UI Kit Builder

Log in to your CometChat Dashboard.
Select your application from the list.
Navigate to Chat & Messaging → Get Started.
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.

Open the cometchat-app-react folder.

Install dependencies:
npm i
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 Router 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
Create React App

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.

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:

Create new users on the CometChat Dashboard, with a CometChat SDK method, or via the API.
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)
Auth Token (production)

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

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

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 TokenAuth 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%;
}

Rendering the chat at a route

App above is the whole chat experience. In a React Router app you usually want it on one route rather than at the root, so render it as that route’s element:

import { createBrowserRouter, RouterProvider } from "react-router-dom";
import App from "./App";
import Home from "./Home";

const router = createBrowserRouter([
  { path: "/", element: <Home /> },
  { path: "/chat", element: <App /> },
]);

export default function Root() {
  return <RouterProvider router={router} />;
}

Keep initialization where Step 3 put it — at your entry file, outside the router — so the UI Kit is ready before any route renders, and is not re-initialized on navigation.

The chat fills its parent, so the route’s layout needs a height. If your route renders inside a shell with a header or sidebar, give the chat’s container a height (for example calc(100dvh - 64px)) rather than the 100dvh used above.

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
Create React App

npm run dev

npm start

Framework mode and SSR

React Router v7’s framework mode server-renders by default. The CometChat UI Kit and the copied CometChat folder touch browser APIs (window, document, WebSockets) as soon as they load, so rendering them on the server fails with window is not defined. Pick whichever fits your app.

Option A — turn server rendering off

If the app does not need SSR, set it off once in react-router.config.ts:

import type { Config } from "@react-router/dev/config";

export default {
  ssr: false,
} satisfies Config;

Your app now builds as an SPA, with two caveats:

Framework mode has no src/main.tsx or src/index.tsx, so Step 3’s initialization has nowhere to go as written. Run npx react-router reveal to generate app/entry.client.tsx and initialize there, or do it in a client-only effect in app/root.tsx.
ssr: false still pre-renders app/root.tsx at build time to produce index.html. Route modules below it render only in the browser, so the chat is fine inside a route — but anything that touches window while a module imported by root.tsx is evaluating fails the build with window is not defined.

With the chat rendered in a route rather than from root.tsx, Option A needs no lazy loading.

Option B — keep SSR, render the chat only in the browser

Keep server rendering for the rest of the app and load the chat after mount. Because the import itself must not run on the server, it has to be lazy — not a top-level import:

import { lazy, Suspense, useEffect, useState } from "react";

const App = lazy(() => import("../App")); // the shell from Step 5

export default function ChatRoute() {
  const [mounted, setMounted] = useState(false);

  // Effects never run on the server, so this flips only in the browser.
  useEffect(() => setMounted(true), []);

  if (!mounted) return null; // or your own loading state

  return (
    <Suspense fallback={null}>
      <App />
    </Suspense>
  );
}

Initialization (Step 3) must move into that client-only boundary too — put it in a useEffect in the same component, and render the shell once it resolves. The Next.js guide shows that shape in full; the only difference is that Next.js has dynamic(..., { ssr: false }) where React Router uses lazy plus the mounted guard.

A top-level import of the chat anywhere a server-rendered route can reach defeats both options — the module loads during SSR before your guard runs, and useEffect cannot help, because it delays when your code runs, not when the import is evaluated.That includes @cometchat/chat-uikit-react itself, not just CometChat/ and builder/. The UI Kit uses browser APIs as soon as it loads, so importing it at the top of a route fails with window is not defined. Keep all three behind the lazy import, and pull the UI Kit in from inside the effect:

useEffect(() => {
  void (async () => {
    const { CometChatUIKit, UIKitSettingsBuilder } = await import("@cometchat/chat-uikit-react");
    // ...initialization from Step 3
  })();
}, []);

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. window is not defined during build or dev. You are in framework mode and something imports the chat on the server — see Framework mode and SSR.

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.

​Complete Integration Workflow

​Requirements

​Launch the UI Kit Builder

​Review Your Export

​Preview Customizations (Optional)

​Integrate into Your Project

​Step 1: Install Dependencies

​Step 2: Copy Two Folders

​Step 3: Initialize CometChat UI Kit

​Step 4: User Authentication

​Step 5: Render the App Shell

​Rendering the chat at a route

​Step 6: Customize Through Settings

​Step 7: Run the App

​Framework mode and SSR

​Option A — turn server rendering off

​Option B — keep SSR, render the chat only in the browser

​Troubleshooting

​Next Steps

​Customize in Code

Customizations

UI Kit Builder Settings

Directory Structure

Advanced Theming

​Customize via UI Kit Builder

Launch UI Kit Builder

Complete Integration Workflow

Requirements

Launch the UI Kit Builder

Review Your Export

Preview Customizations (Optional)

Integrate into Your Project

Step 1: Install Dependencies

Step 2: Copy Two Folders

Step 3: Initialize CometChat UI Kit

Step 4: User Authentication

Step 5: Render the App Shell

Rendering the chat at a route

Step 6: Customize Through Settings

Step 7: Run the App

Framework mode and SSR

Option A — turn server rendering off

Option B — keep SSR, render the chat only in the browser

Troubleshooting

Next Steps

Customize in Code

Customize via UI Kit Builder