React Router Integration

Add CometChat to a React Router app in 5 steps: create project, install, init, login, render.

AI Agent Component Spec

Field	Value
Package	@cometchat/chat-uikit-react
Peer deps	react >=18, react-dom >=18, rxjs ^7.8.1
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
SSR	React Router SSR — use lazy import + mounted check for CometChat components
CSS	@import url("@cometchat/chat-uikit-react/css-variables.css"); in global CSS
Calling	Optional. Install @cometchat/calls-sdk-javascript to enable
Other frameworks	React.js · Next.js · Astro

This guide walks you through adding CometChat to a React Router app. By the end you’ll have a working chat UI.

CometChat UI Kit requires browser APIs (window, WebSocket, document). In React Router, use lazy imports with a mounted check to ensure CometChat components only render client-side.

---

Prerequisites

You need three things from the CometChat Dashboard:

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.

Auth Key is for development only. In production, generate Auth Tokens server-side via the REST API and use loginWithAuthToken(). Never ship Auth Keys in client code.

---

Step 1 — Create a React Router Project

npx create-react-router@latest my-app
cd my-app

---

Step 2 — Install the UI Kit

npm

npm install @cometchat/chat-uikit-react

yarn

yarn add @cometchat/chat-uikit-react

This installs the UI Kit and its dependency @cometchat/chat-sdk-javascript automatically.

If you want voice/video calling, also install:

npm install @cometchat/calls-sdk-javascript

---

Step 3 — Initialize CometChat

TypeScript

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

/**
 * CometChat Constants - Replace with your actual credentials
 */
const COMETCHAT_CONSTANTS = {
  APP_ID: "APP_ID", // Replace with your actual App ID from CometChat
  REGION: "REGION", // Replace with your App's Region
  AUTH_KEY: "AUTH_KEY", // Replace with your Auth Key (leave blank if 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(() => {
    console.log("CometChat UI Kit initialized successfully.");
  })
  .catch((error) => {
    console.error("CometChat UI Kit initialization failed:", error);
  });

JavaScript

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

/**
 * CometChat Constants - Replace with your actual credentials
 */
const COMETCHAT_CONSTANTS = {
  APP_ID: "APP_ID", // Replace with your actual App ID from CometChat
  REGION: "REGION", // Replace with your App's Region
  AUTH_KEY: "AUTH_KEY", // Replace with your Auth Key (leave blank if 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(() => {
    console.log("CometChat UI Kit initialized successfully.");
  })
  .catch((error) => {
    console.error("CometChat UI Kit initialization failed:", error);
  });

init() must resolve before you call login(). Note the ?.then() — init() may return undefined if settings are invalid.

---

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

TypeScript

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

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

CometChatUIKit.getLoggedinUser().then((user: CometChat.User | null) => {
  if (!user) {
    CometChatUIKit.login(UID)
      .then((user: CometChat.User) => {
        console.log("Login Successful:", { user });
      })
      .catch(console.log);
  } else {
    // Already logged in
  }
});

JavaScript

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

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

CometChatUIKit.getLoggedinUser().then((user) => {
  if (!user) {
    CometChatUIKit.login(UID)
      .then((user) => {
        console.log("Login Successful:", { user });
      })
      .catch(console.log);
  } else {
    // Already logged in
  }
});

Key points:

• getLoggedinUser() checks for an existing session so you don’t re-login unnecessarily.
• login(uid) skips the API call if a session already exists and returns the cached user.
• Components must not render until login resolves — use a state flag to gate rendering.

For production, use loginWithAuthToken() instead of Auth Key. Generate tokens server-side via the REST API.

---

Step 5 — Add the CSS Import

Add this line at the top of your global CSS file (e.g. app.css):

app.css

@import url("@cometchat/chat-uikit-react/css-variables.css");

Also ensure your global CSS sets height: 100% on the root elements:

app.css

html,
body {
  height: 100%;
}

Without the CSS import, components will render with broken or missing styles. Without the height rules, the chat UI won’t fill the viewport.

---

Step 6 — 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 on the left, messages on the right. Think WhatsApp Web or Slack.

• Two-panel layout with conversation list and active chat window
• Switch between one-to-one and group conversations
• Tap-to-view on mobile — tapping a conversation opens the message view
• Real-time updates and message sync across sessions

Build Conversation List + Message View

Step-by-step guide to build this layout

---

One-to-One / Group Chat

Single chat window — no sidebar. 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 optimized for mobile
• Ideal for support chat or community messaging

Build One-to-One / Group Chat

Step-by-step guide to build this layout

---

Tab-Based Chat

Tabbed navigation — Chat, Call Logs, Users, Settings in separate tabs. Good for full-featured apps.

• Tab navigation between Chat, Call Logs, Users, and Settings
• Full-screen messaging within each tab
• Unified experience for conversations, call history, and settings
• Scales well for adding future features like notifications or contacts

Build Tab-Based Chat

Step-by-step guide to build this layout

---

Build Your Own Chat Experience

Need full control over the UI? Use individual components, customize themes, and wire up your own layouts.

• Sample App — Working reference app to compare against
• Components — All prebuilt UI elements with props and customization options
• Core Features — Messaging, real-time updates, and other capabilities
• Theming — Colors, fonts, dark mode, and custom styling
• Build Your Own UI — Skip the UI Kit entirely and build on the raw SDK

---

Next Steps

Components Overview

Browse all prebuilt UI components

Theming

Customize colors, fonts, and styles

Core Features

Chat features included out of the box

Troubleshooting

Common issues and fixes