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`
SDK peer dep	`@cometchat/chat-sdk-javascript` ^4.2.0 (required by 7.2.x)
Bundled deps	`dompurify` (new in v7) and `@cometchat/cards-react` (already a dependency since 6.5.0) — installed automatically, not peer deps
Removed dep	`rxjs` (no longer needed)
Stylesheet	Delete the v6 `css-variables.css` import — v7 loads its own styles
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.2.0
npm uninstall rxjs  # No longer needed for CometChat

Package	v6	v7
`@cometchat/chat-uikit-react`	`^6.x`	`^7.2.1`
`@cometchat/chat-sdk-javascript`	`^4.x`	`^4.2.0` — peer dep, required by 7.2.x
`react`	`>=18`	`>=18 <21`
`rxjs`	Required	Not needed — uninstall it
`@cometchat/calls-sdk-javascript`	Optional	Optional (unchanged)
`dompurify`	—	Bundled — do not install it yourself
`@cometchat/cards-react`	Bundled (since 6.5.0)	Bundled — do not install it yourself

dompurify and @cometchat/cards-react are regular dependencies of the UI Kit, so npm pulls them in automatically. They are not peer dependencies and do not belong in your package.json.Bump your SDK first. 7.2.x declares @cometchat/chat-sdk-javascript ^4.2.0, so staying on a 4.1.x pin fails with ERESOLVE — ^4 is not sufficient. Installing ^4.2.0 is safe on every v7 release, including 7.0.x and 7.1.x, whose ranges it also satisfies.

Delete your v6 stylesheet import. v6 required you to import the base stylesheet yourself:

v6 — remove this

import "@cometchat/chat-uikit-react/css-variables.css";
// or, in CSS:
// @import url("@cometchat/chat-uikit-react/css-variables.css");

v7 injects its own stylesheet when you import any component, so no CSS import is needed. The package does still expose a @cometchat/chat-uikit-react/styles subpath for compatibility, but importing it is redundant. Remove the import rather than switching it over.

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

Checking for an existing session

The v6 init snippet used getLoggedinUser() to skip re-login when a session already existed, so most v6 apps carry one of these two calls. Both changed shape in v7:

v6	v7
`await CometChatUIKit.getLoggedinUser()`	`await CometChat.getLoggedinUser()` (SDK), or `CometChatUIKit.getLoggedInUser()` (sync, after login)
`CometChatUIKitLoginListener.getLoggedInUser()`	`CometChatUIKit.getLoggedInUser()`

CometChatUIKit.getLoggedInUser() is synchronous in v7 and returns CometChat.User | null directly — not a Promise. Note the capital I: v6’s async method was spelled getLoggedinUser(), and that spelling no longer exists on CometChatUIKit, so v6 code carried over unchanged throws a TypeError at runtime (… getLoggedinUser is not a function; the exact prefix depends on your bundler). TypeScript flags it at compile time.Await the SDK’s CometChat.getLoggedinUser() when you need the asynchronous form, or drop the await and call CometChatUIKit.getLoggedInUser() once login has completed. CometChatUIKitLoginListener no longer exists in v7.

CometChatUIKit.init() also resolves with the existing user (or null), so a session check often collapses into the init call you already have:

v7 — init doubles as the session check

const existingUser = await CometChatUIKit.init(settings);
if (!existingUser) {
  await CometChatUIKit.login("uid");
}
render(<App />);

3. Replace DataSource/Decorator with Plugins

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

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) => {
  // ui:message/sent fires at each stage — check status, or you will
  // handle the same message twice (once with no ID yet, once confirmed).
  if (event.type === "ui:message/sent" && event.status === "success") { ... }
  if (event.type === "message/edited") { ... }
}, []); // deps is required — omitting it throws at runtime

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	Back in 7.2.0 on Conversations, MessageList and ThreadHeader. A v6 formatter carries over when its transform lives in `customLogicToFormatText()` or `getFormattedText()` (add `readonly id` in TypeScript); transforms in `onRegexMatch()`, and hooks such as `formatMessageForSending()`, are never called in v7 — see Porting a v6 formatter

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 opt-in. v6 turned it on by itself: once @cometchat/calls-sdk-javascript was installed, the UI Kit enabled calling during login and call buttons appeared. v7 only enables it when you ask, via UIKitSettingsBuilder:

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. This is a silent change for a v6 app that had calling working: nothing errors, the call buttons simply stop appearing until you add the flag.

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) => { ... }, [deps]) — the deps array is required
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 showSearchBar={false} 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.

One Conversations default did flip: showSearchBar defaulted to false in v6 and defaults to true in v7, so a v6 app that never set the prop gains a search bar after upgrading. Pass showSearchBar={false} to keep the v6 look. Note there is no hideSearch prop on CometChatConversations in either version — hideSearch belongs to CometChatUsers, CometChatGroups and CometChatGroupMembers.

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)

<CometChatImagesBubble message={message} />

This applies to all message bubbles: CometChatTextBubble, CometChatImagesBubble, CometChatVideosBubble, CometChatAudiosBubble, CometChatVoiceNoteBubble, CometChatFilesBubble, CometChatPollBubble, CometChatStickerBubble, CometChatCallBubble, CometChatCollaborativeDocumentBubble, CometChatCollaborativeWhiteboardBubble, CometChatGroupActionBubble, and CometChatCallActionBubble.

In v7 the default rendering moves to the multi-attachment media bubbles: CometChatImageBubble → CometChatImagesBubble, CometChatVideoBubble → CometChatVideosBubble, CometChatFileBubble → CometChatFilesBubble, and CometChatAudioBubble → CometChatAudiosBubble (attached audio files) or CometChatVoiceNoteBubble (recorded voice notes). The singular CometChat*Bubble components still ship and can be used standalone — only the message list’s default routing changed.

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

​Checking for an existing session

​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

Property Changes

CometChatProvider

Plugins

Event System

What’s New in v7

Step-by-Step Migration Checklist

1. Update Dependencies

2. Update Initialization

Checking for an existing session

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