Move from Chat Components to Chat SDK

PubNub stopped supporting Chat Components, 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, 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. 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 (React) or 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 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.

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.

show all 33 lines

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.

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(), held in your own state, no child components to feed
Channel List component	chat.getChannels() for every channel, or chat.currentUser.getMemberships() for the channels the current user belongs to, rendered in your own list
Member List component	channel.getMembers(), rendered in your own list
Message List component	channel.getHistory() for the page load, then channel.onMessageReceived() for live updates, rendered in your own list
Message Input component	channel.sendText() or a MessageDraft for mentions, links, quotes, or files, rendered as your own input field
Typing indicator (built into Message Input)	channel.startTyping(), channel.stopTyping(), and channel.getTyping() to receive it, rendered as your own indicator
usePresence hook and OccupancyIndicator	chat.wherePresent(), chat.whoIsPresent(), and chat.isPresent()
Message reactions (built into Message List)	message.toggleReaction(), rendered as your own emoji picker
File upload (built into Message Input)	A MessageDraft with attached files, 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() and chat.getChannel() 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() on the specific channel you care about, and replace onMembership with membership.onUpdated(). 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 instead.

Related tasks

• Chat SDK. Install the SDK and see what it covers beyond the features Chat Components exposed.
• Chat SDK entities. The Chat, Channel, User, and Message objects every Chat SDK call in this guide runs on.
• Initial configuration. Install @pubnub/chat and initialize it with your keys.
• Sample chat. Run a working Chat SDK app to see the entities from this guide wired together.
• Chat Components. The deprecated package this guide moves you away from.