ComponentContext

ComponentContext is provided by Channel and can be consumed by any Channel child. It contains UI component overrides for customization. To override UI under Channel, pass the overrides as Channel props so they’re injected into ComponentContext. Access it via useComponentContext.

Best Practices

• Prefer WithComponents to scope overrides instead of global component props.
• Keep overrides small and composable to reduce future upgrade work.
• Reuse default components when only styles or minor behavior changes are needed.
• Avoid wrapping every subtree; scope overrides only where they differ.
• Document custom overrides to keep UI behavior predictable across teams.

Basic Usage

Pull values from ComponentContext with our custom hook:

const { Attachment, Avatar, Message } = useComponentContext();

WithComponents

WithComponents is an override helper built on ComponentContext. It replaces prop-based overrides, which are being deprecated.

Basic Usage of WithComponents

In this example, the top-level MessageInput uses the closest override (CustomMessageInputUi1). The Thread component uses its own MessageInput, and the closest override there is CustomMessageInputUi2. If you remove the WithComponents wrapper around Thread, its MessageInput falls back to CustomMessageInputUi1. With no WithComponents wrappers, defaults are used.

const CustomMessageInputUi1 = () => {
  /*...*/
};
const CustomMessageInputUi2 = () => {
  /*...*/
};

<Channel>
  <WithComponents overrides={{ Input: CustomMessageInputUi1 }}>
    <Window>
      <MessageList />
      <MessageInput focus />
    </Window>
    <WithComponents overrides={{ Input: CustomMessageInputUi2 }}>
      <Thread />
    </WithComponents>
  </WithComponents>
</Channel>;

You can also scope overrides like this: MessageInput inside Window uses CustomMessageInputUi2, ThreadList inside ChatView.Threads uses CustomThreadListItem, and both Thread components use CustomMessageInputUi1 for their internal MessageInput.

const CustomThreadListItem = () => {
  /*...*/
};

<Chat>
  <WithComponents
    overrides={{
      ThreadListItem: CustomThreadListItem,
      Input: CustomMessageInputUi1,
    }}
  >
    <ChatView>
      <ChatView.Selector />
      <ChatView.Channels>
        <ChannelList />
        <Channel>
          <WithComponents
            overrides={{
              Input: CustomMessageInputUi2,
            }}
          >
            <Window>
              {/*...*/}
              <MessageInput focus />
            </Window>
          </WithComponents>
          <Thread />
        </Channel>
      </ChatView.Channels>
      <ChatView.Threads>
        <ThreadList />
        <ChatView.ThreadAdapter>
          <Thread />
        </ChatView.ThreadAdapter>
      </ChatView.Threads>
    </ChatView>
  </WithComponents>
</Chat>;

Values

Attachment

Custom UI component to display attachment in an individual message.

AttachmentPreviewList

Custom UI component to display a attachment previews in MessageInput.

AttachmentSelector

Custom UI component to control adding attachments to MessageInput, defaults to and accepts same props as:

AttachmentSelectorInitiationButtonContents

Custom UI component for contents of attachment selector initiation button.

AudioRecorder

Custom UI component to display AudioRecorder in MessageInput.

AutocompleteSuggestionItem

Custom UI component to override the default suggestion Item component.

AutocompleteSuggestionList

Custom UI component to override the default List component that displays suggestions.

Avatar

Custom UI component to display a user's avatar.

BaseImage

Custom UI component to display image resp. a fallback in case of load error, in <img/> element. The default resp. custom (from ComponentContext) BaseImage component is rendered by:

• Image - single image attachment in message list
• Gallery - group of image attachments in message list
• AttachmentPreviewList - image uploads preview in message input (composer)

The BaseImage component accepts the same props as <img/> element.

The default BaseImage component tries to load and display an image and if the load fails, then an SVG image fallback is applied to the <img/> element as a CSS mask targeting attached str-chat__base-image--load-failed class.

CooldownTimer

Custom UI component to display the slow mode cooldown timer.

CustomMessageActionsList

Custom UI component to render set of buttons to be displayed in the MessageActionsBox.

DateSeparator

Custom UI component for date separators.

EditMessageInput

Custom UI component to override default edit message input.

EditMessageModal

Custom UI component to override default EditMessageModal component. It is useful when we want to override additionalMessageInputProps, e.g. number of rows in the textarea:

import {
  Channel,
  EditMessageModal,
  EditMessageModalProps,
} from "stream-chat-react";

const CustomEditMessageModal = (props: EditMessageModalProps) => (
  <EditMessageModal
    additionalMessageInputProps={{
      ...props.additionalMessageInputProps,
      maxRows: 10,
    }}
  />
);
const Component = ({ children }) => (
  <Channel EditMessageModal={CustomEditMessageModal}>{children}</Channel>
);

EmojiIcon

Custom UI component for emoji button in input.

EmptyStateIndicator

Custom UI component to be displayed when the MessageList is empty.

FileUploadIcon (deprecated)

Custom UI component for file upload icon. The component is now deprecated. Use AttachmentSelectorInitiationButtonContents instead.

GiphyPreviewMessage

Custom UI component to render a Giphy preview in the VirtualizedMessageList.

HeaderComponent

Custom UI component to render at the top of the MessageList.

Input

Custom UI component handling how the message input is rendered.

LinkPreviewList

Custom component to render link previews in MessageInput.

LoadingErrorIndicator

Custom UI component to be shown if the channel query fails.

LoadingIndicator

Custom UI component to render while the MessageList is loading new messages.

Message

Custom UI component to display a message in the standard MessageList.

MessageActions

Custom UI component for message actions popup, accepts no props, all the defaults are set within MessageActions (unstable).

MessageBlocked

Custom UI component for a moderation-blocked message, defaults to and accepts same props as: MessageBlocked

MessageBouncePrompt

Custom UI component for the content of the modal dialog for messages that got bounced by the moderation rules.

MessageDeleted

Custom UI component for a deleted message.

MessageIsThreadReplyInChannelButtonIndicator

Custom UI component to indicate a message is a thread reply sent to channel list as well.

MessageListNotifications

Custom UI component that displays message and connection status notifications in the MessageList.

MessageNotification

Custom UI component to display a notification when scrolled up the list and new messages arrive.

MessageOptions

Custom UI component for message options popup.

MessageRepliesCountButton

Custom UI component to display message replies.

MessageStatus

Custom UI component to display message delivery status.

MessageSystem

Custom UI component to display system messages.

MessageTimestamp

Custom UI component to display a timestamp on a message. This does not include a timestamp for edited messages.

See also Timestamp.

Modal

Custom UI component for viewing content in a modal, defaults to and accepts the same props as Modal.

It is possible to override the default Modal component with GlobalModal to have the content displayed via React portal at the top of the Chat components tree:

import { GlobalModal } from "stream-chat-react";

const Component = () => <Channel Modal={GlobalModal}></Channel>;

Using the GlobalModal prevents UI glitches in some browsers (e.g. Safari cutting of the modal overlay to the dimensions of the message list).

ModalGallery

Custom UI component for viewing message's image attachments.

PinIndicator

Custom UI component to override default pinned message indicator.

PollActions

Custom UI component to override default poll actions rendering in a message.

PollContent

Custom UI component to override default poll rendering in a message.

PollCreationDialog

Custom UI component to override default poll creation dialog contents.

PollHeader

Custom UI component to override default poll header in a message.

PollOptionSelector

Custom UI component to override default poll option selector.

QuotedMessage

Custom UI component to override quoted message UI on a sent message.

QuotedMessagePreview

Custom UI component to override the message input's quoted message preview.

QuotedPoll

Custom UI component to override the rendering of quoted poll.

ReactionSelector

Custom UI component to display the reaction selector.

ReactionsList

Custom UI component to display the list of reactions on a message.

ReactionsListModal

Custom UI component to display the modal with detailed listing of reactions. The modal is rendered upon clicking on the ReactionsList.

ReminderNotification

Custom UI component to display the message reminder information in the Message UI.

SendButton

Custom UI component for send button.

SendToChannelCheckbox

Custom UI component allowing to send the composed thread reply to the channel's message list as well. Should be rendered only with thread message composer.

TextareaComposer

Custom UI component to handle message text input

ThreadHead

Custom UI component to be displayed at the beginning of a thread. By default, it is the thread parent message. It is composed of Message context provider component and ThreadStart component. The latter can be customized by passing custom component to Channel props. The ThreadHead component defaults to and accepts the same props as MessageSimple.

ThreadHeader

Custom UI component to display the header of a Thread.

ThreadInput

Custom UI component to replace the MessageInput of a Thread. The component uses MessageInputFlat by default.

ThreadStart

Custom UI component to display the start of a threaded MessageList.

Timestamp

Custom UI component to display a date used in timestamps. It's used internally by the default MessageTimestamp, and to display a timestamp for edited messages.

TypingIndicator

Custom UI component for the typing indicator.

UnreadMessagesNotification

Custom UI component that indicates a user is viewing unread messages. It disappears once the user scrolls to UnreadMessagesSeparator.

UnreadMessagesSeparator

Custom UI component inserted before the first message marked unread.

VirtualMessage

Custom UI component to display a message in the VirtualizedMessageList.