> ## 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.
# React.js Integration
> Add CometChat to a React.js app in 5 steps: create project, install, init, login, render.
| 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 |
| CSS | `@import url("@cometchat/chat-uikit-react/css-variables.css");` in global CSS |
| Calling | Optional. Install `@cometchat/calls-sdk-javascript` to enable |
| Other frameworks | [Next.js](/ui-kit/react/next-js-integration) · [React Router](/ui-kit/react/react-router-integration) · [Astro](/ui-kit/react/astro-integration) |
| AI Skills | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills) |
This guide walks you through adding CometChat to a React.js app. By the end you'll have a working chat UI.
***
## Integrate with AI Coding Agents
Skip the manual steps — use [CometChat Skills](https://github.com/cometchat/cometchat-skills) to integrate via your AI coding agent. Your agent has a short conversation with you to understand your project and chat requirements, then writes production-grade integration code tailored to the files you already have.
```bash theme={null}
npx @cometchat/skills add
```
Use `--ide ` to target a specific IDE (e.g. `--ide cursor`), or `--ide all` for all supported IDEs.
Then in your IDE:
```
/cometchat add chat to my app
```
The skill detects your bundler (Vite or CRA), env prefix (`VITE_` or `REACT_APP_`), router, and existing auth system. It onboards you to CometChat directly in the terminal — signup, login, and app creation all via the CLI. It reads your routes, nav, and components before proposing a placement, shows the plan, and waits for your approval before writing code.
After the first integration, re-run `/cometchat` to access the iteration menu: theme presets, 40+ features, component customization, floating widget, production auth, user management, and diagnostics.
Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [30+ more agents](https://github.com/cometchat/cometchat-skills).
***
## Prerequisites
You need three things from the [CometChat Dashboard](https://app.cometchat.com/):
| 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](/rest-api/chat-apis) and use [`loginWithAuthToken()`](/ui-kit/react/methods#login-using-auth-token). Never ship Auth Keys in client code.
***
## Step 1 — Create a React Project
```bash lines theme={null}
npm create vite@latest my-app -- --template react-ts
cd my-app
```
```bash lines theme={null}
npx create-react-app my-app --template typescript
cd my-app
```
***
## Step 2 — Install the UI Kit
```bash lines theme={null}
npm install @cometchat/chat-uikit-react
```
```bash lines theme={null}
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:
```bash lines theme={null}
npm install @cometchat/calls-sdk-javascript
```
***
## Step 3 — Initialize CometChat
Create a constants file and initialize the UI Kit before anything else.
```ts title="src/AppConstants.ts" lines theme={null}
export const COMETCHAT_CONSTANTS = {
APP_ID: "APP_ID", // Replace with your App ID
REGION: "REGION", // Replace with your Region
AUTH_KEY: "AUTH_KEY", // Replace with your Auth Key (dev only)
};
```
```ts lines highlight={7-9} theme={null}
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);
});
```
```js lines highlight={7-9} theme={null}
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()`. If you call `login()` before init completes, it will fail silently.
By default, session data is stored in `localStorage`. To use `sessionStorage` instead, see [Setting Session Storage Mode](/ui-kit/react/methods#setting-session-storage-mode).
***
## 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`
```ts lines highlight={3} theme={null}
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 });
// Mount your app
})
.catch(console.log);
} else {
// Already logged in — mount your app
}
});
```
```js lines highlight={3} theme={null}
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 });
// Mount your app
})
.catch(console.log);
} else {
// Already logged in — mount your app
}
});
```
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()`](/ui-kit/react/methods#login-using-auth-token) 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. `src/App.css` or `src/index.css`):
```css title="src/App.css" lines theme={null}
@import url("@cometchat/chat-uikit-react/css-variables.css");
```
Without this import, components will render with broken or missing styles.
***
## Step 6 — Choose a Chat Experience
Integrate a conversation view that suits your app's UX. Each option below includes a live CodeSandbox demo and 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
[](https://link.cometchat.com/react-conversation-list-message)
> **Tip:** Fork the sandbox, insert your CometChat credentials (App ID, Region, Auth Key), and preview the UI in real time.
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
[](https://link.cometchat.com/react-one-on-one)
> **Tip:** Fork the sandbox, insert your CometChat credentials (App ID, Region, Auth Key), and preview the UI in real time.
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
[](https://link.cometchat.com/react-tabs-sidebar-message)
> **Tip:** Fork the sandbox, insert your CometChat credentials (App ID, Region, Auth Key), and preview the UI in real time.
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](https://github.com/cometchat/cometchat-uikit-react/tree/v6/sample-app) — Working reference app to compare against
* [Components](/ui-kit/react/components-overview) — All prebuilt UI elements with props and customization options
* [Core Features](/ui-kit/react/core-features) — Messaging, real-time updates, and other capabilities
* [Theming](/ui-kit/react/theme) — Colors, fonts, dark mode, and custom styling
* [Build Your Own UI](/sdk/javascript/overview) — Skip the UI Kit entirely and build on the raw SDK
***
## iFrame Embedding
If your React app runs inside an `
[
](https://link.cometchat.com/react-conversation-list-message)
> **Tip:** Fork the sandbox, insert your CometChat credentials (App ID, Region, Auth Key), and preview the UI in real time.
[
[