Upgrading to v9

Version 9 of the Stream Chat React Native SDK is a ground-up redesign of the entire UI layer. Every visual component has been rethought to deliver a modern, polished chat experience out of the box — backed by a new design token system, a slot-based composition architecture for the message input, a centralized state store system, and a brand-new base UI component library.

If you are upgrading from V8, expect to touch theme overrides, component imports, and any code that customizes the message input, attachment picker, channel preview, or overlay system. This guide walks through every breaking change, highlights what replaced what, and ends with a concrete checklist you can follow.

React Native New Architecture Required

V9 supports the React Native New Architecture only. The old architecture (Paper renderer and the legacy bridge) is no longer supported. Before upgrading to V9, ensure that:

1. Your project is running on React Native 0.76+ (or an Expo SDK version that defaults to the New Architecture).
2. The New Architecture is enabled in your project configuration.
3. All other third-party native modules you depend on are New Architecture compatible.

If your project is still on the old architecture, you must migrate to the New Architecture first. Refer to the React Native New Architecture guide for instructions.

New Peer Dependencies

V9 introduces one new required peer dependency and one optional one:

# Required
yarn add react-native-teleport

# Optional — install for improved keyboard handling
yarn add react-native-keyboard-controller

react-native-keyboard-controller is entirely optional. The SDK works without it, but when installed it provides smoother keyboard animations and more reliable keyboard height tracking. You can add it at any time.

Expo users: Both packages ship with config plugins. Run npx expo prebuild after installing.

Dependency Version Bumps

Design Token System

V8 used ad-hoc color values and scattered style constants. V9 replaces all of this with a layered design token system that makes theming consistent and predictable.

The New theme/ Module

The SDK now exports a theme/ module with four layers:

The defaultTheme object now exposes a top-level semantics property alongside the existing colors:

const theme = useTheme();
const { semantics, colors } = theme;

// Semantic tokens are named by purpose, not by hue
const bgColor = semantics.backgroundElevationElevation1;
const borderColor = semantics.borderCoreDefault;
const textColor = semantics.textPrimary;

Migration tip: Wherever you were using raw colors.* values (e.g. colors.grey, colors.white_snow), prefer the equivalent semantics.* token. Semantic tokens automatically adapt across light, dark, and high-contrast themes.

Color Changes

The colors type no longer includes an index signature ({ [key: string]: string }). If you were storing custom color keys on the colors object, move them to the semantics object or extend the theme type.

Default Value Changes

New Base UI Component Library

V9 introduces a ui/ component library that provides standardized, token-driven UI primitives. These replace the older ad-hoc components and give you building blocks that are consistent with the SDK's new design language.

Avatar

The Avatar and GroupAvatar components have been moved from components/Avatar/ to components/ui/Avatar/. The old exports are removed.

V8:

import { Avatar, GroupAvatar } from "stream-chat-react-native";
// Props: image, name, online, presenceIndicator, size (number)

V9:

import { Avatar } from "stream-chat-react-native";
// Props: size ('2xl' | 'xl' | 'lg' | 'md' | 'sm' | 'xs'),
//        imageUrl, placeholder, showBorder, backgroundColor, style

Button

A new standardized Button component with variant, type, and size props:

import { Button } from "stream-chat-react-native";

<Button
  variant="primary" // 'primary' | 'secondary' | 'destructive'
  type="solid" // 'solid' | 'outline' | 'ghost' | 'liquidGlass'
  size="md" // 'sm' | 'md' | 'lg'
  LeadingIcon={SendRight}
  label="Send"
  disabled={false}
/>;

Badge Components

Other New Primitives

MessageInput — Complete Redesign

The message input underwent the most significant transformation in V9. It moves from a flat, prop-heavy component to a slot-based composition architecture that is easier to customize and extend.

Architecture Change

V8: A single component with many inline conditional renders. Buttons (Send, AudioRecord, Cooldown, Commands, MoreOptions) were rendered directly in the component body and customized via individual component props.

V9: A slotted layout with clearly defined regions that you can replace independently:

MessageInput
├── MessageComposerLeadingView    ← wraps InputButtons (attach, etc.)
├── Main Input Area
│   ├── MessageInputHeaderView    ← reply preview, edit header, attachments, link previews
│   ├── AudioRecordingPreview / AudioRecordingInProgress / InputView
├── MessageInputTrailingView      ← wraps OutputButtons (send, edit, cooldown, audio)
├── MessageComposerTrailingView   ← empty slot for your own custom content
├── AutoCompleteSuggestionList
└── Poll Creation Modal

New useMessageComposer Hook

V9 exposes a useMessageComposer() hook that gives you direct access to the composer's internal state without going through context:

const messageComposer = useMessageComposer();
const { attachmentManager, textComposer, editedMessage, channel, hasCommands } =
  messageComposer;

New Slot Props

These composition slot components can be passed to the Channel component to customize regions of the input:

Removed Props

The following props are removed from Channel and MessageInputContext:

New Upload Indicator Components

The single AttachmentUploadProgressIndicator is replaced by six specific components, giving you finer control over each upload state:

OutputButtons Component

A new OutputButtons component manages the trailing action buttons using priority-based rendering with animated transitions (ZoomIn/ZoomOut, 200ms):

Component Path Changes

New MessageInput Components

MessageInputContext Changes

Removed Values

Added Values

Modified Values

AudioAttachment Changes

The audio playback system has been rewritten to use a centralized player model.

Removed Props

Added Props

Hook Rename

MessageList Changes

New Props

Removed Props

Modified Props

The FlatList item type changed from LocalMessage to MessageListItemWithNeighbours. Each item now carries references to its preceding and following messages, enabling smarter grouping and rendering.

New Sub-Components

MessagesContext Changes

Removed Values

Added Values

Modified Values

Note: MessageHeader is now a required value in the context. If you were relying on it being optional, make sure your custom provider supplies a component.

MessageHeader redesign

In v8, MessageSimple passed a richer runtime prop bag into custom headers, including alignment, date, isDeleted, lastGroupMessage, members, message, MessageStatus, otherAttachments, and showMessageStatus.

In v9, the public prop surface is limited to message?, and the default MessageHeader reads its data and subcomponents from useMessageContext() and useMessagesContext() instead. If you customized MessageHeader, move that logic into hooks rather than relying on the old explicit props.

If your old customization was only about pinned, reminder, saved-for-later, or sent-to-channel header UI, prefer overriding MessagePinnedHeader, MessageReminderHeader, MessageSavedForLaterHeader, or SentToChannelHeader directly.

Channel Component Changes

New Props

All the MessageComposer*View and MessageInput*View slot props from the MessageInput section are also available on Channel.

Removed Props

Modified Default Values

Action required: If your UI depends on 'text' rendering before 'attachments', explicitly pass the V8 order array to messageContentOrder.

ChannelPreview Changes

The channel preview components have been redesigned with new hooks and a restructured layout.

Key API Change: latestMessagePreview → lastMessage

In V8, ChannelPreview exposed a latestMessagePreview object with pre-formatted preview data. In V9, this is replaced with lastMessage — the raw last message object — and specialized hooks for formatting:

// V8
const { latestMessagePreview } = useChannelPreviewContext();
const previewText = latestMessagePreview?.messageObject?.text;

// V9
const { lastMessage } = useChannelPreviewContext();
const previewText = lastMessage?.text;

New Components

Removed Components

New Props

New Hooks

Hook Export Changes

Individual hook exports from ChannelPreview/hooks/, ChannelList/hooks/, and Chat/hooks/ are consolidated into barrel exports. The hooks themselves are still available, but you import from the barrel:

// V8
import { useChannelPreviewDisplayName } from "stream-chat-react-native/ChannelPreview/hooks/useChannelPreviewDisplayName";

// V9
import { useChannelPreviewDisplayName } from "stream-chat-react-native";

Hook Rename

Attachment Components

Renamed Components

Removed Components

New Components

AttachmentPicker Overhaul

The attachment picker has been completely redesigned with a simpler, more extensible architecture.

Removed:

• AttachmentPickerBottomSheetHandle
• AttachmentPickerError / AttachmentPickerErrorImage
• CameraSelectorIcon / FileSelectorIcon / ImageSelectorIcon / VideoRecorderSelectorIcon
• AttachmentPickerIOSSelectMorePhotos
• AttachmentPickerItem

Added:

OverlayProvider Changes

The overlay system has been rearchitected to use a portal-based approach powered by react-native-teleport. This eliminates the need for complex z-index management and provides smoother overlay animations.

New Architecture

The OverlayProvider now wraps its children with a PortalProvider and renders a MessageOverlayHostLayer for the new portal-based message overlay. This means message context menus and reaction pickers render in a true overlay portal rather than within the component tree.

New Props

Removed Props

Image Gallery Customization — Flattened

The nested imageGalleryCustomComponents object is replaced by direct component props for simpler customization:

V8:

<OverlayProvider
  imageGalleryCustomComponents={{
    footer: { Component: CustomFooter },
    header: { Component: CustomHeader },
    grid: { Component: CustomGrid },
    gridHandle: { Component: CustomGridHandle },
  }}
>

V9:

<OverlayProvider
  ImageGalleryHeader={CustomHeader}
  ImageGalleryFooter={CustomFooter}
  ImageGalleryVideoControls={CustomVideoControls}
  ImageGalleryGrid={CustomGrid}
>

New Context Value

OverlayContextValue now includes overlayOpacity (SharedValue<number>) — a Reanimated shared value you can use to drive custom overlay animations.

ImageGallery Changes

The image gallery has been refactored to use a centralized state store instead of in-component state.

State Store

A new ImageGalleryStateStore replaces in-component state management:

• ImageGalleryAsset type replaces the old Photo type.
• Gallery configuration (autoPlayVideo, giphyVersion) moves from props to ImageGalleryOptions in the state store.
• Three utility functions are exported: isViewableImageAttachment, isViewableVideoAttachment, isViewableGiphyAttachment.

// V8
<Gallery autoPlayVideo={true} giphyVersion="original" />;

// V9
const { imageGalleryStateStore } = useImageGalleryContext();
imageGalleryStateStore.openImageGallery(/* ... */);

Removed

Added

Message Components

New Components

Removed Components

MessagePinnedHeader still exists in v9. It is now rendered as part of the consolidated MessageHeader flow alongside reminder, saved-for-later, and sent-to-channel headers.

MessagePreview → Hooks

The MessagePreview component is removed in favor of composable hooks:

State Store Additions

V9 adds four new centralized state store modules that follow the same observable pattern used elsewhere in the SDK:

VideoPlayer

Mirrors the existing audio player architecture for video:

• VideoPlayer class with VideoPlayerState, VideoDescriptor, VideoPlayerOptions types
• DEFAULT_PLAYBACK_RATES and INITIAL_VIDEO_PLAYER_STATE constants

VideoPlayerPool

Pool management for multiple concurrent video players:

• VideoPlayerPool class with VideoPlayerPoolState type

ImageGalleryStateStore

Centralized state for the image gallery (replaces in-component state):

• ImageGalleryStateStore class
• ImageGalleryAsset, ImageGalleryState, ImageGalleryOptions types
• isViewableImageAttachment, isViewableVideoAttachment, isViewableGiphyAttachment utilities

MessageOverlayStore

Complete state management for the portal-based overlay system:

• Store instances: overlayStore, closingPortalLayoutsStore
• Lifecycle functions: openOverlay, closeOverlay, scheduleActionOnClose, finalizeCloseOverlay
• Layout management: setOverlayMessageH, setOverlayTopH, setOverlayBottomH, bumpOverlayLayoutRevision
• Portal management: createClosingPortalLayoutRegistrationId, setClosingPortalLayout, clearClosingPortalLayout
• Hooks: useOverlayController, useIsOverlayClosing, useIsOverlayActive, useClosingPortalHostBlacklistState, useShouldTeleportToClosingPortal, useClosingPortalHostBlacklist, useClosingPortalLayouts

New Hooks

Renamed Hooks

New Contexts

Icons Changes

V9 significantly overhauls the icon set: many legacy icons are removed, and new icons are added to support the redesigned UI.

New Icons

Removed Icons

If you were importing any of these icons directly, you will need to provide your own icon components.

File type icons: CSV, DOCX, HTML, MD, ODT, PPT, PPTX, RAR, RTF, SEVEN_Z, TAR, TXT, XLS, XLSX

Reaction icons: LOLReaction, LoveReaction, ThumbsDownReaction, ThumbsUpReaction, WutReaction

Navigation / UI icons: ArrowLeft, ArrowUp, AtMentions, Attach, Back, ChatIcon, CheckSend, CircleClose, Down, DownloadCloud, DragHandle, Error, Folder, GenericFile, Group, Imgur, Lightning, Link, Lock, MailOpen, MenuPointVertical, MessageBubble, Mic, Notification, PinHeader, SendCheck, SendPoll, SendUp, Unpin, UserMinus, Warning

MessageMenu (Context Menu)

The message context menu has been rebuilt around the current overlay system and its dedicated reaction and action components.

ActionType Union

The ActionType union has been expanded with blockUser:

type ActionType =
  | "banUser"
  | "blockUser" // new in V9
  | "copyMessage"
  | "deleteMessage"
  | "deleteForMeMessage"
  | "editMessage"
  | "flagMessage"
  | "markUnread"
  | "muteUser"
  | "pinMessage"
  | "selectReaction"
  | "reply"
  | "retry"
  | "quotedReply"
  | "threadReply"
  | "unpinMessage";

MessageActionType Structure

Actions now include a type field that separates standard actions from destructive ones — the menu renders them in distinct groups with a visual separator:

type MessageActionType = {
  action: () => void;
  actionType: ActionType | string;
  title: string;
  icon?: React.ReactElement;
  titleStyle?: StyleProp<TextStyle>;
  type: "standard" | "destructive";
};

Reaction Picker Changes

• Emoji picker uses a 7-column grid layout.
• New EmojiViewerButton component for expanding the full emoji list.
• Reactions filter to isMain reactions by default.
• Haptic feedback on reaction selection.
• useHasOwnReaction hook for highlighting already-reacted emojis.

Theme Changes

The theme structure has undergone extensive changes across nearly every component. Below are the most impactful changes — review these carefully if you have custom theme overrides.

messageInput Theme

Removed keys:

• attachmentSeparator, autoCompleteInputContainer, composerContainer
• commandInput (closeButton, container, text)
• commandsButton, moreOptionsButton, optionsContainer
• editingBoxContainer, editingBoxHeader, editingBoxHeaderTitle, editingStateHeader
• replyContainer
• searchIcon, sendRightIcon, sendUpIcon
• audioRecordingButton (container, micIcon)
• uploadProgressIndicator (container, indicatorColor, overlay)
• cooldownTimer.container (only text remains)
• imageUploadPreview.flatList

Added keys:

• Layout: wrapper, contentContainer, inputContainer, inputBoxWrapper
• Buttons: inputButtonsContainer, outputButtonsContainer, editButton, editButtonContainer, audioRecordingButtonContainer, cooldownButtonContainer
• Floating: floatingWrapper, inputFloatingContainer
• Upload indicators: fileUploadInProgressIndicator, fileUploadRetryIndicator, fileUploadNotSupportedIndicator, imageUploadInProgressIndicator, imageUploadRetryIndicator, imageUploadNotSupportedIndicator
• Link previews: linkPreviewList (with linkContainer, linkIcon, container, imageWrapper, dismissWrapper, thumbnail, wrapper, metadataContainer, text, titleText)

Modified keys:

• attachmentUploadPreviewList: from { filesFlatList, imagesFlatList, wrapper } to { flatList, itemSeparator }
• imageAttachmentUploadPreview: itemContainer → container, added wrapper
• videoAttachmentUploadPreview: from { recorderIconContainer, recorderIcon, itemContainer, upload } to { durationContainer, durationText }

messageList Theme

Added keys:

• inlineDateSeparatorContainer
• unreadUnderlayContainer
• scrollToBottomButtonContainer
• stickyHeaderContainer
• unreadMessagesNotificationContainer

Removed from scrollToBottomButton: touchable, wrapper, chevronColor

Modified unreadMessagesNotification:

• Removed: closeButtonContainer, closeIcon, text
• Added: leftButtonContainer, rightButtonContainer

messageSimple Theme

This section has the most extensive changes.

content:

• container simplified from ViewStyle & { borderRadiusL, borderRadiusS } to ViewStyle
• Removed: deletedContainer, deletedContainerInner, deletedMetaText, deletedText, editedLabel, messageUser, metaContainer, receiverMessageBackgroundColor, senderMessageBackgroundColor
• Added: contentContainer

New sub-components:

• deleted — containerInner, deletedText, container
• footer — container, name, editedText
• bubble — reactionListTopContainer, contentContainer, wrapper, errorContainer
• savedForLaterHeader — container, label
• reminderHeader — container, label, dot, time
• sentToChannelHeader — container, label, dot, link
• unsupportedAttachment — container, details, title
• contentContainer, leftAlignItems, rightAlignItems
• messageGroupedSingleStyles, messageGroupedBottomStyles, messageGroupedTopStyles, messageGroupedMiddleStyles

avatarWrapper: Removed leftAlign, rightAlign

card → UrlPreview:

• Removed: authorName, authorNameContainer, authorNameFooter, authorNameFooterContainer, authorNameMask, noURI, playButtonStyle, playIcon
• Added: linkPreview, linkPreviewText
• New sub-component compactUrlPreview with wrapper, container, cardCover, cardFooter, title, description, linkPreview, linkPreviewText

giphy:

• Removed: buttonContainer, cancel, giphyHeaderTitle, selectionContainer, send, shuffle, title
• Added: actionButtonContainer, actionButton, actionButtonText, imageIndicatorContainer

reactionListBottom: Restructured from { contentContainer, item: { container, countText, filledBackgroundColor, icon, iconFillColor, iconSize, iconUnFillColor, unfilledBackgroundColor } } to { contentContainer, columnWrapper, rowSeparator }

New reaction list theme keys:

• reactionListItem — reactionCount, icon
• reactionListClustered — contentContainer, reactionCount, iconStyle, icon
• reactionListItemWrapper — wrapper, container

reactionListTop: Restructured from { container, item: { container, icon, iconFillColor, iconSize, iconUnFillColor, reactionSize }, position } to { container, contentContainer, list, position }. Default position changed from 16 to 8.

replies:

• Removed: avatar, avatarContainerMultiple, avatarContainerSingle, leftAvatarsContainer, leftCurve, rightAvatarsContainer, rightCurve, avatarSize
• Added: content, avatarStackContainer

status:

• Removed: readByCount, statusContainer
• Added: container

Gallery defaults changed:

channelPreview Theme

Removed: avatar, checkAllIcon, checkIcon, row, mutedStatus (old structure with height, iconStyle, width)

Added:

• messageDeliveryStatus — container, text, checkAllIcon, checkIcon, timeIcon
• lowerRow, upperRow, statusContainer, titleContainer, wrapper
• typingIndicatorPreview — container, text
• messagePreview — container, subtitle
• message expanded with subtitle, errorText, draftText

channelListSkeleton Theme

Completely restructured:

• Removed: background, gradientStart, gradientStop, height, maskFillColor
• Added: avatar, badge, content, headerRow, subtitle, textContainer, title
• animationTime changed from 1800 to 1000

reply Theme

Completely redesigned:

• Removed: fileAttachmentContainer, imageAttachment, markdownStyles, messageContainer, secondaryText, textContainer, videoThumbnail
• Added: audioIcon, dismissWrapper, fileIcon, leftContainer, locationIcon, linkIcon, photoIcon, pollIcon, rightContainer, title, subtitle, subtitleContainer, videoIcon, wrapper, messagePreview

threadListItem Theme

Completely restructured:

• Removed: boldText, contentRow, contentTextWrapper, headerRow, infoRow, parentMessagePreviewContainer, parentMessageText, touchableWrapper, unreadBubbleText
• Added: wrapper, container, content, channelName, lowerRow, messageRepliesText, messagePreview, messagePreviewDeliveryStatus

Other Theme Changes

• poll.answersList: buttonContainer → contentContainer
• poll.createContent: Added optionCardWrapper and expanded settings with description, optionCardContent, optionCardSwitch for addComment, anonymousPoll, multipleAnswers, suggestOption
• poll.message.option: Removed color strings (progressBarEmptyFill, progressBarVotedFill, etc.), added info, header, votesText, progressBarContainer
• progressControl: Removed filledColor
• typingIndicator: Added loadingDotsBubble, avatarStackContainer
• attachmentPicker: Removed errorButtonText, errorContainer, errorText; added content (container, infoContainer, text)
• audioAttachment: Added centerContainer, audioInfo
• threadListUnreadBanner: touchableWrapper renamed to container
• thread.newThread: Restructured to include container
• New top-level theme keys: channelDetailsMenu, threadListSkeleton

Migration Checklist

Follow these steps in order to migrate your project from V8 to V9:

1. Install New Dependencies

# Required
yarn add react-native-teleport

# Optional — for improved keyboard handling
yarn add react-native-keyboard-controller

Update stream-chat to ^9.36.0 and pin @gorhom/bottom-sheet to 5.1.8.

2. Update Avatar Usage

Replace Avatar with numeric size → new Avatar with string enum ('xs' through '2xl'). Rename image to imageUrl. Replace GroupAvatar with AvatarGroup or AvatarStack.

3. Update MessageInput Customizations

Replace removed props with the new slot-based components:

4. Update Attachment Picker Customizations

Replace individual selector icons (CameraSelectorIcon, FileSelectorIcon, etc.) with AttachmentTypePickerButton. Remove references to AttachmentPickerBottomSheetHandle, AttachmentPickerError, and AttachmentPickerErrorImage.

5. Update Upload Progress Indicators

Replace AttachmentUploadProgressIndicator with the six granular indicators (FileUploadInProgressIndicator, FileUploadRetryIndicator, FileUploadNotSupportedIndicator, ImageUploadInProgressIndicator, ImageUploadRetryIndicator, ImageUploadNotSupportedIndicator).

6. Update URL Preview Customizations

Replace Card / CardProps with UrlPreview / URLPreviewProps. Use the urlPreviewType prop on Channel to switch between 'full' and 'compact' modes.

7. Update Audio Hooks and Props

• Rename useAudioController → useAudioRecorder.
• Rename useAudioPlayerControl → useAudioPlayer.
• Remove onLoad, onPlayPause, onProgress callbacks from AudioAttachment — use the useAudioPlayer hook instead.

8. Update Image Gallery Customizations

Replace the imageGalleryCustomComponents nested object on OverlayProvider with direct component props (ImageGalleryHeader, ImageGalleryFooter, ImageGalleryVideoControls, ImageGalleryGrid).

9. Update ChannelPreview Customizations

• Replace latestMessagePreview with lastMessage in any custom PreviewStatus or PreviewMessage components.
• Replace ChannelAvatar usage with the new ChannelAvatar from ui/Avatar/.
• Rename useMutedUsers → useClientMutedUsers.
• If you customized MessageHeader, stop relying on the old explicit prop bag from MessageSimple. Read data from useMessageContext() / useMessagesContext() instead, or override the dedicated header components (MessagePinnedHeader, MessageReminderHeader, MessageSavedForLaterHeader, SentToChannelHeader).

10. Update Theme Overrides

Review any custom theme overrides against the Theme Changes section. The most impacted areas are:

• messageInput — completely restructured layout keys
• messageSimple — new sub-components (bubble, footer, deleted, etc.)
• channelPreview — new layout keys (upperRow, lowerRow, etc.)
• reply — completely redesigned
• threadListItem — completely restructured

11. Migrate Colors to Semantic Tokens

Replace raw colors.* usage with semantics.* tokens where available. This ensures your customizations adapt correctly across light, dark, and high-contrast themes.

12. Update Icon Imports

Replace any removed icon imports with custom alternatives. See Icons Changes for the full removal list.

13. Update FlatList Types

If you use additionalFlatListProps or setFlatListRef, update your types from LocalMessage to MessageListItemWithNeighbours.

14. Review messageContentOrder

The default order now places 'attachments' before 'text'. If your UI depends on the V8 order, pass it explicitly:

<Channel
  messageContentOrder={['quoted_reply', 'gallery', 'files', 'poll', 'ai_text', 'text', 'attachments', 'location']}
>

15. Update Message Action Types

If you customize message actions, note the new 'blockUser' action type and the type: 'standard' | 'destructive' classification that controls visual grouping in the menu.