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	Same as v6: `CometChatUIKit.init()` + `login()` imperatively, then wrap in `CometChatProvider`
Extensibility	`DataSource`/`ChatConfigurator` → `CometChatMessagePlugin` interface
Events	RxJS Subjects → `useCometChatEvents` hook
Theming	Same CSS variables, simpler setup via `theme` prop on provider

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)	Same: `CometChatUIKit.init()` + `login()` then wrap in `CometChatProvider`
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)
Message Bubbles	Presentational — receive pre-extracted props from parent	Self-extracting — accept SDK `message` and derive data internally
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.10 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.10` (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

The initialization pattern is nearly identical between v6 and v7. The only addition in v7 is wrapping your app in CometChatProvider:

// main.tsx
const settings = new UIKitSettingsBuilder()
  .setAppId("APP_ID")
  .setRegion("us")
  .setAuthKey("AUTH_KEY")
  .build();

CometChatUIKit.init(settings).then(async () => {
  await CometChatUIKit.login("uid");
  render(<App />);
});

// main.tsx — same init + login, just add CometChatProvider in your component tree
const settings = new UIKitSettingsBuilder()
  .setAppId("APP_ID")
  .setRegion("us")
  .setAuthKey("AUTH_KEY")
  .build();

CometChatUIKit.init(settings).then(async () => {
  await CometChatUIKit.login("uid");
  render(<App />);
});

// App.tsx — wrap in CometChatProvider
function App() {
  return (
    <CometChatProvider>
      <MyChatApp />
    </CometChatProvider>
  );
}

3. 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.

4. 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.

5. 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.

6. 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();

7. Enable Calling (If Used)

Calling is now configured via UIKitSettingsBuilder rather than a provider prop:

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

await CometChatUIKit.init(settings);

Without .setCallingEnabled(true), 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 on CometChatProvider

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.

Presentational Bubbles → Self-Extracting Bubbles

In v6, message bubble components (TextBubble, ImageBubble, etc.) were presentational — they received pre-extracted props like src, text, isSentByMe from the parent. The DataSource/plugin layer did the extraction and passed data down. In v7, bubble components are self-extracting — they accept the SDK message object as their primary input and derive rendering state internally (attachments, text, sender info, alignment). Some bubbles retain optional override props (e.g., text and isSentByMe on CometChatTextBubble), but the standard usage is to pass only message.

v6 — presentational (parent extracts data)

<CometChatImageBubble src={message.getURL()} isSentByMe={true} />

v7 — self-extracting (bubble handles it)

<CometChatImageBubble message={message} />

This applies to all message bubbles: CometChatTextBubble, CometChatImageBubble, CometChatVideoBubble, CometChatAudioBubble, CometChatFileBubble, CometChatPollBubble, CometChatStickerBubble, CometChatCallBubble, CometChatCollaborativeDocumentBubble, CometChatCollaborativeWhiteboardBubble, CometChatGroupActionBubble, and CometChatCallActionBubble.

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
Presentational bubble props (`src`, `text`, etc.) as required inputs	Bubbles now accept `message` as the primary prop and self-extract data — optional overrides like `text` or `isSentByMe` still exist on some bubbles

Next Steps

Property Changes

Full prop-by-prop migration reference for every component

CometChatProvider

Provider setup with all props 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. Replace DataSource/Decorator with Plugins

​4. Replace RxJS Event Subscriptions

​5. Update Component Props

​6. Update Theming (Minor)

​7. Enable Calling (If Used)

​Architecture Changes

​DataSource → Plugin System

​RxJS Subjects → Unified Event Bus

​Flat API → Compound Components

​Presentational Bubbles → Self-Extracting Bubbles

​Removed Concepts

​Next Steps