```
### Advanced: Pre-built Settings
For full control over SDK configuration (presence subscription mode, custom hosts, storage mode), pass a `UIKitSettings` object:
```tsx theme={null}
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 (
);
}
```
### With Calling Enabled
```tsx theme={null}
```
### With Custom Theme and Locale
```tsx theme={null}
```
### With Additional Plugins
Default plugins (text, image, file, audio, video) are always included. Pass additional plugins via the `plugins` prop:
```tsx theme={null}
import { CometChatProvider } from "@cometchat/chat-uikit-react";
import { CometChatAIPlugin } from "@cometchat/chat-uikit-react/plugins/ai";
```
### Accessing the Logged-In User
Inside your components (children of `CometChatProvider`), access the logged-in user via the `useLoggedInUser()` hook or `CometChatUIKit.getLoggedInUser()`:
```tsx theme={null}
import { useLoggedInUser } from "@cometchat/chat-uikit-react";
function MyComponent() {
const loggedInUser = useLoggedInUser();
if (!loggedInUser) return Logging in...
;
return Welcome, {loggedInUser.getName()}
;
}
```
***
## 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.
### Step 1: Initialize and Login
Call `CometChatUIKit.init()` and `CometChatUIKit.login()` before rendering:
```tsx title="src/main.tsx" theme={null}
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();
});
```
### Step 2: Compose Providers
After init and login, wrap your app with the individual providers:
```tsx title="src/App.tsx" theme={null}
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 (
);
}
```
### 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:
```tsx title="app/providers.tsx" theme={null}
"use client";
import { CometChatProvider } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/styles";
export function ChatProviders({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
***
## Migration from v6
In v6, initialization was always imperative:
```tsx title="v6 (before)" theme={null}
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");
```
```tsx title="v7 (after)" theme={null}
```
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)