Skip to content

v14.0.0

Choose a tag to compare

View all tags
@stream-ci-bot stream-ci-bot released this 16 Apr 15:17
· 114 commits to master since this release
v14.0.0
5435b9b

Released: 2026-04-16 · Full diff · Migration guide

A full visual and architectural refresh of the SDK. This release brings a redesigned component system, new message composer, overhauled theming, and a cleaner customization model — alongside significant breaking changes to component APIs, CSS class names, and context wrappers.

⚠️ Breaking Changes

Resources for migrating:

Component & Import Renames

v13 v14
MessageInput MessageComposer
MessageInputFlat MessageComposerUI
MessageInputContext MessageComposerContext
useMessageInputContext useMessageComposerContext
MessageOptions MessageActions
MessageDeleted MessageDeletedBubble
MessageNotification NewMessageNotification
ScrollToBottomButton ScrollToLatestMessageButton
ReactionsListModal MessageReactionsDetail
ChannelListMessenger ChannelListUI
ChannelPreview ChannelListItem
ChannelPreviewMessenger ChannelListItemUI
ChannelSearch Search (now stable, main entrypoint)
Modal GlobalModal
UploadButton FileInput
MessageIsThreadReplyInChannelButtonIndicator MessageAlsoSentInChannelIndicator
MessageListNotifications NotificationList
isOnlyEmojis messageTextHasEmojisOnly
useAudioController useAudioPlayer

Removed entirely (no replacement via rename): FixedHeightMessage, EditMessageForm, EditMessageModal, MessageActionsBox, MessageActionsWrapper, CustomMessageActionsList, QuotedPoll, ButtonWithSubmenu, ConnectionStatus, MessageErrorText, RemindMeActionButton. See the migration guide for recommended alternatives.

Removed icon exports: ActionsIcon, ReactionIcon, ThreadIcon, MessageErrorIcon, PauseIcon, PlayTriangleIcon, GeolocationIcon, CloseIcon, SendIcon, MicIcon. Migrate to the public Icons set or higher-level components such as MessageActions, SendButton, and MessageStatus.

MessageActions and Search are no longer exported from stream-chat-react/experimental. Import from the main package:

import { MessageActions, Search } from 'stream-chat-react';

UI Overrides: Channel → WithComponents

  • Channel no longer accepts component override props. Move all overrides to <WithComponents overrides={{...}}>.
  • ChannelList direct override props removed: List, Preview, Avatar, LoadingIndicator, LoadingErrorIndicator. Use WithComponents for all of these.
  • The with*Context HOC wrappers have been removed: withChannelActionContext, withChannelStateContext, withChatContext, withComponentContext, withMessageContext, withTranslationContext, withTypingContext. Use use*Context hooks inside function components instead.
  • Channel now renders EmptyStateIndicator by default when no channel is active. Pass EmptyPlaceholder={null} to restore the old blank behavior.
  • ChannelList.additionalChannelSearchProps and the ChannelList.ChannelSearch override prop were removed. Customize search via WithComponents with Search, SearchBar, or SearchResults.

Message, Actions & Notifications

  • handleDelete signature changed from (event, options?) to (options?). It now rethrows server-side failures — wrap in try/catch in custom delete buttons.
  • onlySenderCanEdit removed from MessageProps. Editability follows channel capabilities; filter edit out of your messageActionSet for custom restrictions.
  • Notification callback props removed from Message: getDeleteMessageErrorNotification, getFetchReactionsErrorNotification, getFlagMessageErrorNotification, getMuteUserSuccessNotification, and others. Use notification translators in Streami18n or useNotificationApi().
  • customMessageActions removed from MessageContext, Message, MessageList, and VirtualizedMessageList. Use messageActionSet and MessageActions.
  • Own messages can no longer be marked unread, even when the channel has the read-events capability.
  • MessageEditedTimestamp removed. Use MessageEditedIndicator, or render your own Timestamp against message.message_text_updated_at.
  • MessageTimestamp now defaults to time-only formatting (HH:mm). Override via Streami18n or provide a custom MessageTimestamp for the old calendar-style output.
  • Edit-message flow no longer uses EditMessageForm / EditMessageModal. Start editing with messageComposer.initState({ composition: message }), cancel with messageComposer.clear().
  • MessageProps no longer injects endOfGroup, firstOfGroup, or groupedByUser as props. Read them from useMessageContext() inside your custom component.
  • The order of actions in MessageActions has changed. Define your own messageActionSet explicitly if your UX depends on a stable action order.

Message Composer (formerly MessageInput)

  • additionalMessageInputProps → additionalMessageComposerProps
  • handleSubmit now accepts only an optional event. The customMessageData and SendMessageOptions arguments were removed. Use composer middleware or messageComposer.customDataManager instead.
  • The default textarea now grows up to 10 rows (was 1). Pass maxRows={1} to restore single-line behavior.
  • QuotedMessagePreviewHeader removed. Customize the full quoted preview through QuotedMessagePreview or QuotedMessagePreviewUI.
  • Voice recordings moved out of AttachmentPreviewList into a dedicated VoiceRecordingPreviewSlot.
  • The EmojiPicker plugin now requires a separate stylesheet import: 
    import 'stream-chat-react/dist/css/emoji-picker.css';
  • str-chat__message-composer-container now wraps the full message composer area.

Avatar, Gallery & Attachments

  • Avatar props renamed: image → imageUrl, name → userName. The user prop was removed. size now accepts arbitrary strings.
  • ChannelAvatar / GroupAvatar: use displayMembers instead of groupChannelDisplayInfo. GroupAvatar now auto-caps displayed members at 4 (or 2 with an overflow badge) — callers no longer control slicing.
  • AvatarStack: new capLimit prop (default 3) controls overflow. Previously callers managed slicing manually.
  • AttachmentProps.Gallery → AttachmentProps.ModalGallery. The old Gallery component is now a carousel provider; use ModalGallery for the thumbnail-grid-plus-viewer behavior.
  • ModalGallery: migrate from the images / index API to the items-based API. Gallery payloads changed from images to items of type GalleryItem.
  • FileIcon: filename → fileName; big, size, sizeSmall, type removed; mimeTypeToIcon(type, mimeType) → mimeTypeToIcon(mimeType?).
  • ReactionSelector: props Avatar, detailedView, latest_reactions, reaction_counts, reaction_groups, reactionOptions, and reverse removed.
  • BaseImage now uses the ImageFallback component (instead of a CSS mask) to display fallbacks on error.

CSS Classes & Stylesheet

CSS import path: stream-chat-react/dist/css/v2/* is no longer valid. Use stream-chat-react/dist/css/* instead.

Removed CSS variables: --str-chat__message-bounce-*, --str-chat__jump-to-latest-message-*

Old class New class
str-chat__channel-preview* str-chat__channel-list-item*
str-chat__channel-preview-container str-chat__channel-list-item-container
str-chat__message-input-cooldown str-chat__message-composer-cooldown
str-chat__message-simple-name str-chat__message-metadata__name
str-chat__simple-message--error-failed str-chat__message-inner--error
str-chat__message-simple-timestamp str-chat__message-metadata__timestamp
str-chat__message-error-icon str-chat__message-error-indicator
str-chat__reaction-list str-chat__message-reactions
str-chat__message-reactions str-chat__message-reactions__list
str-chat__message-reaction str-chat__message-reactions__list-item
str-chat__message-reaction-emoji str-chat__message-reactions__item-icon
str-chat__message-reaction-count str-chat__message-reactions__item-count
str-chat__reaction-list--counter str-chat__message-reactions__total-count
str-chat__channel-list-messenger str-chat__channel-list-inner
str-chat__channel-header-end str-chat__channel-header__data
str-chat__message-reactions-container (removed)
str-chat__reaction-list--reverse (removed)
str-chat__message-reaction-own (removed)
str-chat__message-simple (root) (removed from MessageUI)
str-chat__avatar--single (removed)
str-chat__avatar-group--three-part (removed)

Sidebar, Polls, Dialogs & Misc

  • Sidebar state is now app-owned. The initialNavOpen prop and navOpen / openMobileNav / closeMobileNav from useChatContext() have been removed. Manage sidebar state in your own app and inject toggle UI via HeaderStartContent. See the Collapsible Sidebar cookbook.
  • Explicit query limits required. Channel and ChannelList no longer inject default query limits: 
    <Channel channelQueryOptions={{ messages: { limit: 20 } }}>
<ChannelList options={{ limit: 30 }} />
  • Poll components renamed: AddCommentForm → AddCommentPrompt, EndPollDialog → EndPollAlert, SuggestPollOptionForm → SuggestPollOptionPrompt. QuotedPoll and Poll.isQuoted removed.
  • Modal replaced by GlobalModal. Dismiss dialogs via useModalContext(). The .str-chat__modal__inner wrapper no longer exists.
  • useChannelPreviewInfo() now always returns a defined groupChannelDisplayInfo. Code checking groupChannelDisplayInfo == null as "not a group" should be updated to groupChannelDisplayInfo.members.length >= 2.
  • ChannelHeader.live removed. The header no longer renders channel.data.subtitle under the title.
  • DropdownProps: openButtonProps → TriggerComponent; dialogId removed.
  • addNotification from ChannelStateContext replaced with the client.notifications API.

✨ New Features

UI & Theming

  • Full visual refresh — every component redesigned: message bubbles, reactions, channel previews, thread headers, typing indicators, polls, attachment previews, loading states, search, date separators, and more.
  • Dark mode — official dark theme across the full component set, toggled via CSS variable palettes.
  • New CSS variable system — comprehensive palette, component-level, and global CSS custom properties for deep theming without overriding internal selectors.
  • Migrated to Phosphor icon set — all SDK icons replaced with Phosphor icons, exported individually as Icon* named exports.

Message & Actions

  • New MessageActions & ContextMenu API — message actions rebuilt on a general-purpose context menu system. Filter, reorder, or add actions via messageActionSet / defaultMessageActionSet with quick-toggle and dropdown placement support.
  • ContextMenu animations API — global close-on-click-outside configuration, enter/exit transitions, and ContextMenuButton, ContextMenuHeader, ContextMenuBackButton primitives.
  • MessageEditedIndicator — new component with label + tooltip showing when a message was last edited.
  • Message translation indicator — visual indicator on auto-translated messages with toggle to view the original text.
  • Download attachment action — new built-in "Download" action in the message actions menu.
  • Redesigned deleted message UI via MessageDeletedBubble, now shown inside the message bubble with annotations, metadata, and replies button.

Message List

  • Smooth scrolling added to MessageList.
  • ScrollToLatestMessageButton now rendered by default inside the message list with redesigned markup.
  • UnreadMessagesSeparator now shows the unread count by default and includes a mark-read button. Pass showCount={false} for simpler behavior.

Composer

  • Attachment upload progress tracked and displayed in real time in AttachmentPreviewList.
  • AttachmentSelector redesigned with command submenu support and selectCommand action.
  • LinkPreviewList now shows one preview by default and no longer suppresses previews while quoting.

Reactions

  • Extended ReactionSelector with extended emoji picker mode.
  • MessageReactionsDetail (replaces ReactionsListModal) — redesigned reaction detail rendered in a dialog, with extended reaction list and per-user breakdown.

Avatar & Gallery

  • New Avatar and GroupAvatar designs with updated markup and automatic overflow handling.
  • New AvatarStack component with configurable capLimit and overflow badge, used in message reply buttons and typing indicator.
  • Proprietary Gallery component replaces react-image-gallery. ModalGallery handles the thumbnail-grid-plus-viewer experience. Shared gallery preview added to AttachmentPreviewList.
  • MediaBadge — new component for labeling media attachments.

Audio

  • Improved wave progress bar smoothness and sizing.
  • Audio player now resets progress when the track finishes.
  • New "Voice message deleted" notification.

Channel List & Search

  • ChannelListItem (formerly ChannelPreviewMessenger) fully redesigned.
  • Search promoted to stable with redesigned UI; ChannelSearch dropped.
  • Redesigned channel list loading skeletons, reused for thread list.

Thread & Headers

  • Thread preview fully redesigned.
  • ChatView.ThreadAdapter now shows an empty-state placeholder when no thread is selected.
  • Dual typing indicators: TypingIndicator (message list, with avatar stack + animated dots) and new TypingIndicatorHeader (channel/thread header subtitle) for distinct placement contexts.
  • Redesigned ChannelHeader and ThreadHeader.

Sidebar & Layout

  • Sidebar toggle externalized — state is now fully app-owned via HeaderStartContent / HeaderEndContent.
  • Sidebar display control API added.

Notifications

  • NotificationList replaces MessageListNotifications, now parented under MessageListMainPanel.
  • useNotificationApi() wrapper for app-owned notification management.

Polls

  • Redesigned poll in-message UI and poll creation dialog.
  • Redesigned poll actions modals.

Misc

  • channelActionSet introduced for channel-level action customization.
  • useChannelListContext() diagnostic parameter removed (no-arg call only).
  • TypingIndicator no longer manually slices typing users — delegates to AvatarStack's capLimit.

🐛 Bug Fixes

MessageList

  • Pinned message highlight now extends edge-to-edge across the full list width
  • Fixed jump-to-message snap-back caused by bottom autoscroll interference
  • Fixed scroll position not being maintained when new messages arrive
  • Set correct width on the scroll container to prevent layout overflow
  • Prevented floating date separator from being hidden by scroll position

MessageUI

  • Used isDeleted flag consistently to determine deletion state across all components
  • Unified "deleted message" definition across all rendering components
  • Corrected read-status calculation for the first message in a channel
  • Fixed padding for messages containing only images

Composer

  • Prevented empty textarea from growing beyond its initial height
  • Composer state now cleared on unmount, preventing stale drafts
  • Aligned textarea placeholder and text with surrounding UI
  • Attachment previews now wrap correctly on narrow viewports
  • Hidden attachment selector and action buttons when a slash command is active
  • Voice recorder button now correctly shown when quoting a message

Audio

  • Improved wave progress bar smoothness and sizing consistency

Giphy

  • Fixed layout shifts in Giphy preview by applying a fixed height
  • Only attachments of type giphy are now categorized as Giphy
  • Disabled pointer interactions on Giphy previews
  • Fixed Giphy argument being incorrectly exposed in quoted message / channel preview

Polls

  • Made poll forms submittable via Enter key and submit button
  • Prevented poll options from layout-shifting on vote
  • Fixed suggesting a poll option incorrectly casting a vote
  • Removed extra bottom padding from voted option rows in results view
  • Removed tooltip from PollVote
  • Corrected modal title casing, placeholder text, and button placement

Reactions

  • Message reactions now aligned vertically to the center of the message list

Dialog

  • Prevented outside-click events from closing dialogs managed by a different instance
  • Post-review layout and accessibility fixes for MessageReactionsDetail

ChannelList

  • Fixed dialog portal rendering outside its expected DOM position
  • Fixed ChatView selector button styles and icon alignment

Navigation

  • Improved click-origin detection before closing mobile nav sidebar
  • Prevented mobile sidebar overlays from shifting main chat content

ContextMenu

  • Command menus now sorted consistently
  • Command menus now maintain a constant distance from their invoking button

Search

  • Search correctly exits on input blur (keyboard dismiss on mobile)

Threading

  • Toggle sidebar button now shown in thread view's ThreadHeader

Read State

  • Fixed unread count being incorrectly incremented by useMarkRead when read events are disabled

Styling

  • Single delivery checkmark now uses the correct color in dark mode
  • Correct inverse text color tokens applied in themed components
  • Cleaned up CSS build output; removed dead rules and unused variables

Misc

  • Fixed isDayjs import for ESM bundlers
  • useNotificationTarget now correctly allows returning undefined
  • Removed customMessageData from handleSubmit type declaration
  • Allowed forwarding unsafeHTML to system messages (EventComponent)
  • Stopped typewriter animation on ai_indicator.stop event
Assets 2
Loading