Upgrading from v6 to v7 - CometChat Docs

AI Integration Quick Reference

Field	Value
Package	`@cometchat/chat-uikit-react` v6 → v7
React minimum	`>=18.0.0 <21.0.0`
New peer dep	`dompurify` ^3.3.1
Removed dep	`rxjs` (no longer needed)
Init change	`CometChatProvider` (declarative) or manual `CometChatUIKit.init()` (both work)
Extensibility	`DataSource`/`ChatConfigurator` → `CometChatMessagePlugin` interface
Events	RxJS Subjects → `useCometChatEvents` hook
Theming	Same CSS variables, simpler setup via `theme` prop

What’s New in v7

v7 is a ground-up rewrite that replaces global singletons with React-native patterns while keeping most component props compatible. The core shifts:

Area	v6	v7
Initialization	`CometChatUIKit.init()` + `login()` (imperative)	`CometChatProvider` (declarative) OR manual init (both supported)
Extensibility	`DataSource` / `DataSourceDecorator` / `ChatConfigurator`	Plugin system (`CometChatMessagePlugin` interface)
Events	Multiple RxJS Subject classes	Unified event bus (`useCometChatEvents` hook)
Component API	Flat props only	Compound components (flat API still works)
Theming	CSS variables + manual `data-theme` setup	CSS variables + `theme` prop on provider (same tokens)
Dependencies	`rxjs` required	No `rxjs` dependency

Step-by-Step Migration Checklist

1. Update Dependencies

npm install @cometchat/chat-uikit-react@7 @cometchat/chat-sdk-javascript@^4.1.9 dompurify@^3.3.1
npm uninstall rxjs  # No longer needed for CometChat

Package	v6	v7
`@cometchat/chat-uikit-react`	`^6.x`	`^7.0.0`
`@cometchat/chat-sdk-javascript`	`^4.x`	`^4.1.9` (peer dep)
`react`	`>=18`	`>=18 <21`
`dompurify`	—	`^3.3.1` (new peer dep)
`rxjs`	Required	Not needed
`@cometchat/calls-sdk-javascript`	Optional	Optional (unchanged)

2. Update Initialization

Option A: Declarative (recommended) Replace manual init() + login() with CometChatProvider:

// main.tsx
CometChatUIKit.init(settings).then(() => render(<App />));

// App.tsx
CometChatUIKit.login("uid").then(() => setLoggedIn(true));

<CometChatProvider
  appId="APP_ID"
  region="us"
  authKey="AUTH_KEY"
  uid="cometchat-uid-1"
>
  <App />
</CometChatProvider>

Option B: Manual (same as v6) You can still use CometChatUIKit.init() + login() and compose individual providers. See CometChatProvider — Individual Providers.

3. Update CSS Import

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

// App.tsx (or main.tsx)
import "@cometchat/chat-uikit-react/styles";

The CSS variables are the same — just the import mechanism changed.

4. Replace DataSource/Decorator with Plugins

class MyDecorator extends DataSourceDecorator {
  getTextMessageBubble() { ... }
  getAttachmentOptions() { ... }
}
ChatConfigurator.enable(new MyDecorator());

const MyPlugin: CometChatMessagePlugin = {
  id: "my-plugin",
  messageTypes: ["custom-type"],
  messageCategories: ["custom"],
  renderBubble(message, context) { return <MyBubble />; },
  getOptions(message, context) { return [...]; },
  getLastMessagePreview(message) { return "Preview text"; },
};

<CometChatProvider plugins={[MyPlugin]}>

See Plugins Overview for the full guide.

5. Replace RxJS Event Subscriptions

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

CometChatMessageEvents.ccMessageSent.subscribe((data) => { ... });
CometChatMessageEvents.ccMessageEdited.subscribe((data) => { ... });

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

useCometChatEvents((event) => {
  if (event.type === "ui:message/sent") { ... }
  if (event.type === "message/edited") { ... }
});

See Event System for the full event catalog.

6. Update Component Props

Most component props are unchanged. Key patterns to watch for:

Pattern	v6	v7
View props type	`JSX.Element`	`ReactNode` (compatible)
Date format type	`CalendarObject`	`CometChatDateFormatConfig` (same shape)
Error handling	`hideError` prop	`errorView` prop (pass custom error UI)
Loading state	`disableLoadingState` prop	`loadingView` prop (pass custom loading UI)
Templates	`templates` prop	Plugin system (removed from components)
Text formatters on lists	`textFormatters` prop	Plugin system (removed from list components)

For the full prop-by-prop reference, see Property Changes.

7. Update Theming (Minor)

CSS variables are the same between v6 and v7. The only change is how you set the theme:

// Manual data-theme attribute
<div className="cometchat-root" data-theme="dark">

// theme prop on provider
<CometChatProvider theme="dark" ...>

Or use the useTheme() hook for runtime switching:

const { theme, setTheme } = useTheme();

8. Enable Calling (If Used)

Calling is now opt-in:

<CometChatProvider callingEnabled={true} ...>

Without callingEnabled, call buttons are hidden and the Calls SDK is not loaded.

Architecture Changes

DataSource → Plugin System

v6 used a decorator pattern (DataSourceDecorator) to customize message rendering. v7 replaces this with a simpler plugin interface:

Each plugin owns one or more message types
Plugins provide renderBubble(), getOptions(), getLastMessagePreview()
Default plugins are included automatically
Custom plugins are passed via the plugins prop

RxJS Subjects → Unified Event Bus

v6 had separate RxJS Subject classes for each event category (CometChatMessageEvents, CometChatGroupEvents, CometChatCallEvents, etc.). v7 merges all events into a single typed pub/sub system:

Subscribe: useCometChatEvents((event) => { ... })
Publish: const publish = usePublishEvent()
SDK events (from network) and UI events (from components) flow through the same bus

Flat API → Compound Components

v7 components support both flat API (same as v6) and compound composition:

Flat API (works same as v6)

<CometChatConversations hideSearch onItemClick={handleClick} />

Compound (new in v7)

<CometChatConversations.Root onItemClick={handleClick}>
  {/* Search omitted — just don't render it */}
  <CometChatConversations.List />
</CometChatConversations.Root>

The flat API is fully backward-compatible. Compound composition is optional for advanced customization.

Removed Concepts

v6 Concept	Replacement in v7
`DataSource` / `DataSourceDecorator`	`CometChatMessagePlugin` interface
`ChatConfigurator.enable()`	`plugins` prop on `CometChatProvider`
`CometChatMessageEvents` (RxJS)	`useCometChatEvents` hook
`CometChatGroupEvents` (RxJS)	`useCometChatEvents` hook
`CometChatCallEvents` (RxJS)	`useCometChatEvents` hook
`CometChatUIEvents` (RxJS)	`usePublishEvent` hook
`CometChatMessageTemplate`	Plugin `renderBubble()` method
`*Configuration` objects	Direct props on compound sub-components
`MessagesDataSource.getAttachmentOptions()`	Composer handles attachments directly

Next Steps

Property Changes

Full prop-by-prop migration reference for every component

CometChatProvider

New declarative setup with both approaches explained

Plugins

The new plugin system that replaces DataSource

Event System

Unified event bus replacing RxJS Subjects

​What’s New in v7

​Step-by-Step Migration Checklist

​1. Update Dependencies

​2. Update Initialization

​3. Update CSS Import

​4. Replace DataSource/Decorator with Plugins

​5. Replace RxJS Event Subscriptions

​6. Update Component Props

​7. Update Theming (Minor)

​8. Enable Calling (If Used)

​Architecture Changes

​DataSource → Plugin System

​RxJS Subjects → Unified Event Bus

​Flat API → Compound Components

​Removed Concepts

​Next Steps