CometChatProvider - CometChat Docs

Overview

Every CometChat component must be rendered inside a provider tree that supplies theme, locale, plugin registry, and real-time events. The UI Kit offers two ways to set this up:

Approach	Best for	Init & login	Provider setup
CometChatProvider (recommended)	Most apps	Automatic — just pass credentials	Single component wraps everything
Individual providers	Advanced control (custom login flows, multiple instances)	Manual — call `CometChatUIKit.init()` + `login()` yourself	Compose `ThemeProvider`, `LocaleProvider`, `EventsProvider`, `PluginRegistryContext` manually

Approach 1: CometChatProvider (Recommended)

CometChatProvider is a single component that handles SDK initialization, user login, plugin registration, theming, localization, and real-time events — all declaratively via props.

import { CometChatProvider, CometChatConversations } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/styles";

function App() {
  return (
    <CometChatProvider
      appId="YOUR_APP_ID"
      region="us"
      authKey="YOUR_AUTH_KEY"
      uid="cometchat-uid-1"
    >
      <CometChatConversations />
    </CometChatProvider>
  );
}

That’s it. No CometChatUIKit.init(), no UIKitSettingsBuilder, no manual login. The provider handles the full lifecycle:

Builds UIKitSettings from your props
Calls CometChatUIKit.init(settings) internally
Logs in the user (via uid + authKey, or authToken)
Sets up the plugin registry (default plugins included automatically)
Provides theme, locale, and event contexts to all child components

Props

Prop	Type	Required	Default	Description
`appId`	`string`	Yes*	—	CometChat app ID from the dashboard
`region`	`string`	Yes*	—	App region (`"us"`, `"eu"`, `"in"`)
`authToken`	`string`	—	—	Auth token for production login (server-generated)
`uid`	`string`	—	—	User UID for development login (used with `authKey`)
`authKey`	`string`	—	—	Auth key for development login (used with `uid`)
`settings`	`UIKitSettings`	—	—	Pre-built settings object for full control. When provided, `appId`/`region`/`callingEnabled`/`plugins` props are ignored
`callingEnabled`	`boolean`	No	`false`	Enable voice/video calling (requires `@cometchat/calls-sdk-javascript`)
`plugins`	`CometChatMessagePlugin[]`	No	—	Additional plugins beyond the defaults
`theme`	`"light" \| "dark"`	No	`"light"`	Active theme
`locale`	`string`	No	`"en-us"`	Language code for i18n
`config`	`CometChatGlobalConfig`	No	`{}`	Global flags (`hideReceipts`, `hideUserStatus`, etc.)
`onError`	`(error: Error) => void`	No	—	Called on init or login failure
`onLoginSuccess`	`(user: CometChat.User) => void`	No	—	Called when login succeeds

*Required unless settings is provided.

Authentication

Provide one of:

authToken — for production (generated server-side via REST API)
uid + authKey — for development/testing only

{/* Production */}
<CometChatProvider appId="..." region="us" authToken={serverGeneratedToken}>

{/* Development */}
<CometChatProvider appId="..." region="us" authKey="..." uid="cometchat-uid-1">

Advanced: Pre-built Settings

For full control over SDK configuration (presence subscription mode, custom hosts, storage mode), pass a UIKitSettings object:

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

const settings = new UIKitSettingsBuilder()
  .setAppId("YOUR_APP_ID")
  .setRegion("us")
  .setAuthKey("YOUR_AUTH_KEY")
  .subscribePresenceForRoles(["admin", "support"])
  .setCallingEnabled(true)
  .setAutoEstablishSocketConnection(true)
  .build();

function App() {
  return (
    <CometChatProvider settings={settings} uid="cometchat-uid-1">
      <MyChatApp />
    </CometChatProvider>
  );
}

With Calling Enabled

<CometChatProvider
  appId="YOUR_APP_ID"
  region="us"
  authKey="YOUR_AUTH_KEY"
  uid="cometchat-uid-1"
  callingEnabled={true}
>
  <MyChatApp />
</CometChatProvider>

With Custom Theme and Locale

<CometChatProvider
  appId="YOUR_APP_ID"
  region="eu"
  authKey="YOUR_AUTH_KEY"
  uid="cometchat-uid-1"
  theme="dark"
  locale="fr"
>
  <MyChatApp />
</CometChatProvider>

With Additional Plugins

Default plugins (text, image, file, audio, video) are always included. Pass additional plugins via the plugins prop:

import { CometChatProvider } from "@cometchat/chat-uikit-react";
import { CometChatAIPlugin } from "@cometchat/chat-uikit-react/plugins/ai";

<CometChatProvider
  appId="YOUR_APP_ID"
  region="us"
  authKey="YOUR_AUTH_KEY"
  uid="cometchat-uid-1"
  plugins={[CometChatAIPlugin]}
>
  <MyChatApp />
</CometChatProvider>

Accessing the Logged-In User

Inside your components (children of CometChatProvider), access the logged-in user via the useLoggedInUser() hook or CometChatUIKit.getLoggedInUser():

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

function MyComponent() {
  const loggedInUser = useLoggedInUser();

  if (!loggedInUser) return <div>Logging in...</div>;

  return <div>Welcome, {loggedInUser.getName()}</div>;
}

Approach 2: Individual Providers (Advanced)

For apps that need custom login flows, multiple CometChat instances, or fine-grained control over the provider tree, you can initialize manually and compose providers yourself. Call CometChatUIKit.init() and CometChatUIKit.login() before rendering:

src/main.tsx

import ReactDOM from "react-dom/client";
import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";
import App from "./App";

const settings = new UIKitSettingsBuilder()
  .setAppId("YOUR_APP_ID")
  .setRegion("us")
  .setAuthKey("YOUR_AUTH_KEY")
  .subscribePresenceForAllUsers()
  .setCallingEnabled(true)
  .build();

CometChatUIKit.init(settings).then(async () => {
  // Login — use loginWithAuthToken() in production
  await CometChatUIKit.login("cometchat-uid-1");
  ReactDOM.createRoot(document.getElementById("root")!).render(<App />);
});

Step 2: Compose Providers

After init and login, wrap your app with the individual providers:

src/App.tsx

import {
  CometChatThemeProvider,
  CometChatEventsProvider,
  LocaleProvider,
  CometChatPluginRegistryContext,
  CometChatPluginRegistry,
  defaultPlugins,
} from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/styles";

const pluginRegistry = new CometChatPluginRegistry(defaultPlugins);

function App() {
  return (
    <CometChatThemeProvider theme="light">
      <CometChatEventsProvider>
        <CometChatPluginRegistryContext.Provider value={pluginRegistry}>
          <LocaleProvider locale="en-us">
            <MyChatApp />
          </LocaleProvider>
        </CometChatPluginRegistryContext.Provider>
      </CometChatEventsProvider>
    </CometChatThemeProvider>
  );
}

When to Use This Approach

Custom login flows — your app has its own auth system and you need to control when login happens
Multiple chat instances — you need separate plugin registries or themes for different parts of the app
Gradual migration — you’re migrating from v6 and want to keep the imperative init pattern temporarily
Server-side rendering — you need to defer initialization to a specific lifecycle point

Even with individual providers, CometChatUIKit.init() must be called before rendering any CometChat components. The individual providers do not handle initialization — they only provide React context.

Internal Architecture

CometChatProvider composes these internal providers in order:

CometChatProvider
  └─ PluginRegistryContext     — plugin registry from CometChatUIKit
     └─ GlobalConfigProvider   — hideReceipts, hideUserStatus, etc.
        └─ ThemeProvider        — data-theme attribute + CSS variables
           └─ LocaleProvider   — i18n translations
              └─ EventsProvider — SDK listeners + UI events (mounted after login)
                 └─ {children}

The EventsProvider only mounts after login succeeds. Before that, children render without real-time event subscriptions (which is correct since there’s no authenticated session to listen on).

Next.js App Router

CometChatProvider uses browser APIs internally, so it must be placed inside a Client Component:

app/providers.tsx

"use client";

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

export function ChatProviders({ children }: { children: React.ReactNode }) {
  return (
    <CometChatProvider
      appId={process.env.NEXT_PUBLIC_COMETCHAT_APP_ID!}
      region={process.env.NEXT_PUBLIC_COMETCHAT_REGION!}
      authToken={getAuthToken()}
      callingEnabled
    >
      {children}
    </CometChatProvider>
  );
}

Migration from v6

In v6, initialization was always imperative:

v6 (before)

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

const settings = new UIKitSettingsBuilder()
  .setAppId("APP_ID")
  .setRegion("REGION")
  .setAuthKey("AUTH_KEY")
  .build();

await CometChatUIKit.init(settings);
await CometChatUIKit.login("USER_ID");

v7 (after)

<CometChatProvider appId="APP_ID" region="REGION" authKey="AUTH_KEY" uid="USER_ID">
  <App />
</CometChatProvider>

Key differences:

No manual init() or login() calls needed
No UIKitSettingsBuilder required for basic usage
Default plugins are included automatically
Theme and locale are props, not separate configuration steps
Real-time events are managed internally (no RxJS, no manual listener setup)

​Overview

​Approach 1: CometChatProvider (Recommended)

​Props

​Authentication

​Advanced: Pre-built Settings

​With Calling Enabled

​With Custom Theme and Locale

​With Additional Plugins

​Accessing the Logged-In User

​Approach 2: Individual Providers (Advanced)

​Step 1: Initialize and Login

​Step 2: Compose Providers

​When to Use This Approach

​Internal Architecture

​Next.js App Router

​Migration from v6

Overview

Approach 1: CometChatProvider (Recommended)

Props

Authentication

Advanced: Pre-built Settings

With Calling Enabled

With Custom Theme and Locale

With Additional Plugins

Accessing the Logged-In User

Approach 2: Individual Providers (Advanced)

Step 1: Initialize and Login

Step 2: Compose Providers

When to Use This Approach

Internal Architecture

Next.js App Router

Migration from v6