> ## 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 Router Integration

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

<Accordion title="AI Integration Quick Reference">
  | 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](/ui-kit/react/react-js-integration) · [Next.js](/ui-kit/react/next-js-integration) · [Astro](/ui-kit/react/astro-integration) |
  | AI Skills        | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills)                                                    |
</Accordion>

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

<Warning>
  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.
</Warning>

***

## 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 <name>` 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 React Router version (v6 or v7), env prefix, router setup, 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.

<Warning>
  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.
</Warning>

***

## Step 1 — Create a React Router Project

```bash lines theme={null}
npx create-react-router@latest my-app
cd my-app
```

***

## Step 2 — Install the UI Kit

<Tabs>
  <Tab title="npm">
    ```bash lines theme={null}
    npm install @cometchat/chat-uikit-react
    ```
  </Tab>

  <Tab title="yarn">
    ```bash lines theme={null}
    yarn add @cometchat/chat-uikit-react
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="TypeScript">
    ```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);
      });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```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);
      });
    ```
  </Tab>
</Tabs>

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

***

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

<Tabs>
  <Tab title="TypeScript">
    ```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 });
          })
          .catch(console.log);
      } else {
        // Already logged in
      }
    });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```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 });
          })
          .catch(console.log);
      } else {
        // Already logged in
      }
    });
    ```
  </Tab>
</Tabs>

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.

<Note>
  For production, use [`loginWithAuthToken()`](/ui-kit/react/methods#login-using-auth-token) instead of Auth Key. Generate tokens server-side via the REST API.
</Note>

***

## Step 5 — Add the CSS Import

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

```css title="app.css" lines theme={null}
@import url("@cometchat/chat-uikit-react/css-variables.css");
```

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

```css title="app.css" lines theme={null}
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

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/-YC7tOebleeoFejE/images/e6411d13-chat_experience_sidebar_message-35c431d8bf694e5690e4e0f3a74165af.png?fit=max&auto=format&n=-YC7tOebleeoFejE&q=85&s=03a9df5c80f787357ebc4508839a88cb" width="1282" height="802" data-path="images/e6411d13-chat_experience_sidebar_message-35c431d8bf694e5690e4e0f3a74165af.png" />
</Frame>

<Card title="Build Conversation List + Message View" href="/ui-kit/react/react-router-conversation" icon="comments">
  Step-by-step guide to build this layout
</Card>

***

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

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/sVDw7GNAn28WGWte/images/4d640baf-chat_experience_one_on_one-db9d6d7716241c59bb026625b05019fe.png?fit=max&auto=format&n=sVDw7GNAn28WGWte&q=85&s=06320cc3e46aa95cb0538c84df500aae" width="1282" height="802" data-path="images/4d640baf-chat_experience_one_on_one-db9d6d7716241c59bb026625b05019fe.png" />
</Frame>

<Card title="Build One-to-One / Group Chat" href="/ui-kit/react/react-router-one-to-one-chat" icon="message">
  Step-by-step guide to build this layout
</Card>

***

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

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/8YlylzCf9CehSaWO/images/ca9f09bf-chat_experience_full_tab_based-9900ef578ec8687610d21535089554b2.png?fit=max&auto=format&n=8YlylzCf9CehSaWO&q=85&s=778d316df1879c4e649ae650a231b095" width="1282" height="802" data-path="images/ca9f09bf-chat_experience_full_tab_based-9900ef578ec8687610d21535089554b2.png" />
</Frame>

<Card title="Build Tab-Based Chat" href="/ui-kit/react/react-router-tab-based-chat" icon="table-columns">
  Step-by-step guide to build this layout
</Card>

***

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

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theme">
    Customize colors, fonts, and styles
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/react/core-features">
    Chat features included out of the box
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/ui-kit/react/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>