Getting Started With CometChat React UI Kit For Next.js

Step-by-step guide to integrate CometChat React UI Kit into your Next.js application with App Router support.

AI Agent Component Spec

• Package: @cometchat/chat-uikit-react — npm install @cometchat/chat-uikit-react
• Required setup: CometChatUIKit.init(UIKitSettings) then CometChatUIKit.login("UID") — must complete before rendering
• SSR: CometChat requires browser APIs — use 'use client' directive or dynamic imports with ssr: false
• Init code: new UIKitSettingsBuilder().setAppId("APP_ID").setRegion("REGION").setAuthKey("AUTH_KEY").build()
• Framework: Next.js (this page) | React.js | React Router | Astro
• All components: Components Overview

The CometChat UI Kit for React provides prebuilt UI components for in-app chat — one-to-one and group conversations, theming (light/dark modes), and calling. This guide covers Next.js integration with App Router.

CometChat UI Kit requires browser APIs (window, WebSocket, document). For Next.js, render components only on the client side using 'use client' directive or dynamic imports with ssr: false.

Prerequisites

Create a CometChat application via the CometChat Dashboard. The dashboard provides user management, group chat, voice/video calling, and real-time notifications.

Required credentials from the dashboard:

1. App ID
2. Auth Key
3. Region

Getting Started

1. Create a Next.js Project

   npx

   npx create-next-app@latest my-app --typescript
   cd my-app
   
2. Install Dependencies

   The UI Kit package includes the CometChat JavaScript SDK as a dependency.

   npm install @cometchat/chat-uikit-react
   
3. Initialize CometChat UI Kit

   Call CometChatUIKit.init() at app startup before rendering any components or calling SDK methods.

   Auth Key is for development/POC only. In production, generate Auth Tokens server-side via the REST API. See Auth Token.

   TypeScript

   import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";
   
   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";
   
   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);
     });
   

   Replace APP_ID, AUTH_KEY, and REGION with credentials from the CometChat Dashboard.

4. User Login

   Authentication requires a UID. Create users on the CometChat Dashboard, via the SDK, or API.

   Pre-generated test users: cometchat-uid-1 through cometchat-uid-5.

   The login method returns a CometChat.User object.

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

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

5. Choose a Chat Experience

   Three layout options:

   Conversation List + Message View

   Two-panel layout: conversation list on the left, active chat on the right. Supports 1:1 and group conversations with real-time updates.

   

   

   Integrate Conversation List + Message

   One-to-One/Group Chat

   Single chat window without a conversation list. Supports both 1:1 and group messaging.

   

   

   Integrate One-to-One/Group Chat

   Tab-Based Chat Experience

   Tab navigation between Chat, Call Logs, Users, and Settings. Works across desktop and mobile.

   

   

   Integrate Tab-Based Chat

Build Your Own Chat Experience

For full control over the chat interface, use individual components directly:

• React Sample App
• Core Features
• Components
• Themes
• Build with SDK

Next Steps

Conversation List + Message

Two-panel layout with conversation list and message view.

One-to-One Chat

Focused direct messaging experience without a sidebar.

Tab-Based Chat

Multi-tab navigation for chats, calls, users, and settings.

Advanced Customizations

Customize colors, fonts, and styles.