---
source_url: https://www.pubnub.com/docs/migration-guides/chat-components-to-chat-sdk
title: Move from Chat Components to Chat SDK
updated_at: 2026-09-30T07:20:08.000Z
---
# Move from Chat Components to Chat SDK
## Documentation index
To discover more PubNub resources:
1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.
Do not assume a path exists, always check the index first.
PubNub stopped supporting [Chat Components](https://www.pubnub.com/docs/chat/components/overview.md), the pre-built React and React Native chat UI kit, on January 1, 2025. If your app still renders `ChatProvider` and its child components, use this guide to decide what to rebuild on the [Chat SDK](https://www.pubnub.com/docs/chat/chat-sdk.md), the SDK that replaces it.
This is not a mechanical API swap. Chat Components rendered chat screens for you: channel lists, message bubbles, typing indicators, all as finished UI. Chat SDK is headless. It gives you `Chat`, `Channel`, `User`, `Membership`, and `Message` objects with methods that read and write chat data, but it renders nothing.
Every screen Chat Components used to draw, you now build yourself, in whatever UI library your app already uses. Budget for that UI work before you start. It's the bulk of this migration, not the method calls.
## Before you start
Confirm you have:
* A keyset with **App Context**, **Presence**, and **Message Persistence** enabled in the [Admin Portal](https://admin.pubnub.com/). Chat SDK requires all three, and Chat Components required the same features under the hood.
* A plan for the UI layer. Design your own components, or adopt an open-source kit such as [Chat UI Kit](https://github.com/chatscope/chat-ui-kit-react) (React) or [Gifted Chat](https://github.com/FaridSafi/react-native-gifted-chat) (React Native) and wire Chat SDK calls into it.
* The `@pubnub/chat` package installed in place of `@pubnub/react-chat-components`. Follow [Initial configuration](https://www.pubnub.com/docs/chat/chat-sdk/build/configuration.md) to install it and call `Chat.init()` with your publish key, subscribe key, and user ID.
## Migrate with an AI coding assistant
If you use an AI coding assistant, paste this prompt into it to plan and run the rebuild. The prompt makes the assistant read this guide, list every Chat Components feature your app uses, and rebuild one feature at a time. It also makes the assistant stop before it removes `ChatProvider` or the old package.
```text
Migrate this React or React Native app from PubNub Chat Components, the
@pubnub/react-chat-components package, to the PubNub Chat SDK, the @pubnub/chat
package.
1. Read the migration guide first:
https://www.pubnub.com/docs/migration-guides/chat-components-to-chat-sdk.md
If the PubNub MCP server is connected, you can call get_general_migration_guide
instead. Where the guide and your own knowledge of PubNub disagree, follow the
guide and tell me.
2. This is not a mechanical API swap. Chat SDK is headless and renders nothing,
so every screen Chat Components drew must be rebuilt as our own UI.
3. Before you edit anything, list every Chat Components element, hook such as
usePresence, and ChatProvider callback the app uses. Map each one to its
Chat SDK replacement with the table in the guide. Skip features the app
doesn't use. Then show me a plan and wait for my approval.
4. Ask me which UI approach to use before you build any screen: components we
write, or an open-source kit. Use the UI library the app already uses.
5. Ask me to confirm that App Context, Presence, and Message Persistence are
enabled on the keyset. Chat SDK needs all three.
6. Initialize Chat SDK with Chat.init() and keep the Chat object in app state.
7. Rebuild one feature at a time. Replace each ChatProvider callback, such as
onUser, onChannel, onMembership, onMessageAction, onFile, or onStatus, with
the per-entity update method, such as channel.onUpdated() or
membership.onUpdated(), attached where the app holds that entity.
8. Chat SDK has no theming. Move any Chat Components theme into our own styles.
9. Don't rewrite stored user or channel metadata. App Context data reads back
through Chat SDK without changes on the PubNub side.
10. STOP before you delete ChatProvider or the @pubnub/react-chat-components
package. Ask me to confirm that every feature we use has a replacement.
11. After each feature, run the build and tests and show me the output.
12. Never put the PubNub secret key in client code, and never commit keys or
credentials.
13. When you finish, list every file you changed and the steps left for me.
```
## Map what you're rebuilding
Chat Components bundled a UI and a data layer into one package. Chat SDK gives you only the data layer and expects you to render it yourself.
With Chat Components, `ChatProvider` wraps your app and supplies the pre-built UI components and the `usePresence` hook. The components are Channel List, Message List, and Message Input, with typing, reactions, and file upload built in. Together they render a ready-to-use chat UI. With Chat SDK, you initialize the headless `Chat` object, which exposes the core entities `Channel`, `User`, `Message`, and `Membership`. Those entities return data and events only, so you write the UI layer that renders them.
```mermaid
flowchart TB
subgraph BEFORE["Chat Components (before)"]
CP_PROVIDER["ChatProvider
wrapper component"]
CP_UI["Pre-built UI components
Channel List · Message List ·
Message Input (typing, reactions,
file upload built in)"]
CP_PRESENCE["usePresence
hook"]
CP_RESULT["Rendered chat UI,
ready to use"]
CP_PROVIDER --> CP_UI
CP_PROVIDER --> CP_PRESENCE
CP_UI --> CP_RESULT
CP_PRESENCE --> CP_RESULT
end
subgraph AFTER["Chat SDK (after)"]
SDK_CHAT["Chat object
headless SDK entry point"]
SDK_ENTITIES["Core entities
Channel · User ·
Message · Membership"]
SDK_RESULT["Data and events only"]
SDK_UI["Your UI
components you build"]
SDK_CHAT --> SDK_ENTITIES
SDK_ENTITIES --> SDK_RESULT
SDK_RESULT -.->|"you write this layer"| SDK_UI
end
CP_RESULT -.->|"migrate to"| SDK_CHAT
class CP_PROVIDER,SDK_CHAT emphasis
class CP_UI,CP_PRESENCE,CP_RESULT,SDK_ENTITIES,SDK_RESULT muted
```
The table below maps each Chat Components piece to the Chat SDK entities and methods that replace it:
| Chat Components gave you | Rebuild it with Chat SDK |
| --- | --- |
| `ChatProvider` wiring the app to PubNub and feeding every child component | [Chat.init()](https://www.pubnub.com/docs/chat/chat-sdk/build/configuration.md#initialize-pubnub), held in your own state, no child components to feed |
| Channel List component | [chat.getChannels()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/list.md) for every channel, or [chat.currentUser.getMemberships()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/membership.md#get-membership) for the channels the current user belongs to, rendered in your own list |
| Member List component | [channel.getMembers()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/membership.md#get-members), rendered in your own list |
| Message List component | [channel.getHistory()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/history.md) for the page load, then [channel.onMessageReceived()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/watch.md) for live updates, rendered in your own list |
| Message Input component | [channel.sendText()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/send-receive.md) or a [MessageDraft](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/message-draft.md) for mentions, links, quotes, or files, rendered as your own input field |
| Typing indicator (built into Message Input) | [channel.startTyping()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/typing-indicator.md#start-typing), [channel.stopTyping()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/typing-indicator.md#stop-typing), and [channel.getTyping()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/typing-indicator.md) to receive it, rendered as your own indicator |
| `usePresence` hook and OccupancyIndicator | [chat.wherePresent()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/presence.md#return-channels-where-user-is-present), [chat.whoIsPresent()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/presence.md#return-all-users-present-on-channel), and [chat.isPresent()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/presence.md#check-users-channel-presence) |
| Message reactions (built into Message List) | [message.toggleReaction()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/reactions.md), rendered as your own emoji picker |
| File upload (built into Message Input) | A `MessageDraft` with [attached files](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/files.md), rendered as your own attachment UI |
| Theming through CSS variables or style injection | No equivalent. You own every visual style, since there's no PubNub-rendered component to theme |
Every row rebuilds a UI feature, not a single function call. Treat the linked pages as your API reference for each rebuild, not as a checklist to complete in order. Pick whichever features your app actually used in Chat Components and skip the rest.
## Carry over what didn't change
App Context still stores your user and channel metadata the same way it did under Chat Components. If your app already writes `name`, `email`, or `custom` fields on users and channels, that data reads back through [chat.getUser()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/details.md#get-user-details) and [chat.getChannel()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/details.md) without any changes on the PubNub side. Only the client-side call that reads it changes, from a Chat Components hook to a Chat SDK method.
## Replace the object-event callbacks
Chat Components' `ChatProvider` accepted `onUser`, `onChannel`, `onMembership`, `onMessageAction`, `onFile`, and `onStatus` callbacks and ran them on the matching event. Chat SDK exposes the same events through per-entity update methods instead of one central prop. For example, replace an `onChannel` callback with [channel.onUpdated()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/updates.md#get-channel-updates) on the specific channel you care about, and replace `onMembership` with [membership.onUpdated()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/membership.md#event-based-methods). Attach each listener where you now hold the corresponding entity, rather than in one top-level provider.
## Update your own code and links
* Replace every import from `@pubnub/react-chat-components` with `@pubnub/chat`, and delete the `ChatProvider` element and any Chat Components you removed.
* Search your codebase for the removed hooks (`usePresence`, and any custom hooks built on top of `ChatProvider`'s callbacks) and replace them with the Chat SDK calls from the table above.
* If your own code links to the old React or React Native components documentation, point those links at [Chat SDK](https://www.pubnub.com/docs/chat/chat-sdk.md) instead.
## Related tasks
* [Chat SDK](https://www.pubnub.com/docs/chat/chat-sdk.md). Install the SDK and see what it covers beyond the features Chat Components exposed.
* [Chat SDK entities](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/chat.md). The `Chat`, `Channel`, `User`, and `Message` objects every Chat SDK call in this guide runs on.
* [Initial configuration](https://www.pubnub.com/docs/chat/chat-sdk/build/configuration.md). Install `@pubnub/chat` and initialize it with your keys.
* [Sample chat](https://www.pubnub.com/docs/chat/chat-sdk/build/sample-chat.md). Run a working Chat SDK app to see the entities from this guide wired together.
* [Chat Components](https://www.pubnub.com/docs/chat/components/overview.md). The deprecated package this guide moves you away from.
Last updated at: 2026-09-30T07:20:08.000Z