> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading from v6 to v7

> Migration guide covering breaking changes, architecture shifts, and step-by-step upgrade path from CometChat React UI Kit v6 to v7.

<Accordion title="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 |
</Accordion>

## 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

```bash theme={null}
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 |

<Note>
  `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.
</Note>

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

```tsx title="v6 — remove this" theme={null}
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`:

```tsx title="v6" theme={null}
// 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 />);
});
```

```tsx title="v7" theme={null}
// 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()` |

<Warning>
  `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.
</Warning>

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

```tsx title="v7 — init doubles as the session check" theme={null}
const existingUser = await CometChatUIKit.init(settings);
if (!existingUser) {
  await CometChatUIKit.login("uid");
}
render(<App />);
```

### 3. Replace DataSource/Decorator with Plugins

```tsx title="v6" theme={null}
class MyDecorator extends DataSourceDecorator {
  getTextMessageBubble() { ... }
  getAttachmentOptions() { ... }
}
ChatConfigurator.enable((dataSource) => new MyDecorator(dataSource));
```

```tsx title="v7" theme={null}
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](/ui-kit/react/plugins/overview) for the full guide.

### 4. Replace RxJS Event Subscriptions

```tsx title="v6" theme={null}
import { CometChatMessageEvents } from "@cometchat/chat-uikit-react";

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

```tsx title="v7" theme={null}
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](/ui-kit/react/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](/ui-kit/react/migration-property-changes#porting-a-v6-formatter) |

For the full prop-by-prop reference, see [Property Changes](/ui-kit/react/migration-property-changes).

### 6. Update Theming (Minor)

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

```tsx title="v6" theme={null}
// Manual data-theme attribute
<div className="cometchat-root" data-theme="dark">
```

```tsx title="v7" theme={null}
// theme prop on provider
<CometChatProvider theme="dark">
```

Or use the `useTheme()` hook for runtime switching:

```tsx theme={null}
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`:

```tsx title="v7" theme={null}
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:

```tsx title="Flat API (works same as v6)" theme={null}
<CometChatConversations showSearchBar={false} onItemClick={handleClick} />
```

```tsx title="Compound (new in v7)" theme={null}
<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.

<Warning>
  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`.
</Warning>

### 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`.

```tsx title="v6 — presentational (parent extracts data)" theme={null}
<CometChatImageBubble src={message.getURL()} isSentByMe={true} />
```

```tsx title="v7 — self-extracting (bubble handles it)" theme={null}
<CometChatImagesBubble message={message} />
```

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

<Note>
  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.
</Note>

***

## 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

<CardGroup cols={2}>
  <Card title="Property Changes" icon="list" href="/ui-kit/react/migration-property-changes">
    Full prop-by-prop migration reference for every component
  </Card>

  <Card title="CometChatProvider" icon="box" href="/ui-kit/react/cometchat-provider">
    Provider setup with all props explained
  </Card>

  <Card title="Plugins" icon="puzzle-piece" href="/ui-kit/react/plugins/overview">
    The new plugin system that replaces DataSource
  </Card>

  <Card title="Event System" icon="bolt" href="/ui-kit/react/event-system">
    Unified event bus replacing RxJS Subjects
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.