Next.js Integration - CometChat Docs

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	CometChat requires browser APIs — use dynamic import with `ssr: false`
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 · React Router · Astro

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

CometChat UI Kit requires browser APIs (window, WebSocket, document). In Next.js, always load CometChat components client-side using dynamic imports with ssr: false.

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 Next.js Project

npx create-next-app@latest my-app --typescript
cd my-app

Step 2 — Install the UI Kit

npm
yarn

npm install @cometchat/chat-uikit-react

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
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);
  });

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. Note the ?.then() — in Next.js, init() may return undefined if settings are invalid.

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
JavaScript

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
  }
});

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() 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. globals.css):

globals.css

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

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

globals.css

html,
body {
  height: 100%;
}

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

Fork the sandbox, insert your CometChat credentials (App ID, Region, Auth Key), and preview the UI in real time.

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

Fork the sandbox, insert your CometChat credentials (App ID, Region, Auth Key), and preview the UI in real time.

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

Fork the sandbox, insert your CometChat credentials (App ID, Region, Auth Key), and preview the UI in real time.

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

​Prerequisites

​Step 1 — Create a Next.js Project

​Step 2 — Install the UI Kit

​Step 3 — Initialize CometChat

​Step 4 — Login

​Step 5 — Add the CSS Import

​Step 6 — Choose a Chat Experience

​Conversation List + Message View

Build Conversation List + Message View

​One-to-One / Group Chat

Build One-to-One / Group Chat

​Tab-Based Chat

Build Tab-Based Chat

​Build Your Own Chat Experience

​Next Steps

Components Overview

Theming

Core Features

Troubleshooting

Prerequisites

Step 1 — Create a Next.js Project

Step 2 — Install the UI Kit

Step 3 — Initialize CometChat

Step 4 — Login

Step 5 — Add the CSS Import

Step 6 — Choose a Chat Experience

Conversation List + Message View

One-to-One / Group Chat

Tab-Based Chat

Build Your Own Chat Experience

Next Steps