ComponentContext

ComponentContext holds the React Chat SDK UI override surface for a Channel subtree. Read it with useComponentContext(). Register overrides with WithComponents.

Best Practices

• Scope overrides with WithComponents as close as possible to the subtree that needs them.
• Prefer wrapping or lightly extending default SDK components before replacing whole surfaces.
• Keep custom message UIs based on useMessageContext() and related hooks, not on assumed injected props.
• Use local component props only when that component still exposes a supported prop surface.
• Prefer wrapping the default ContextMenu or ContextMenuContent when you need custom menu behavior, so anchoring, submenu state, and dismissal stay aligned with the SDK.
• Keep your override map documented, because most SDK UI customization now flows through ComponentContext.

Basic Usage

Read values from the context inside any Channel child:

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

export const CustomMessageListHeader = () => {
  const { EmptyStateIndicator, MessageActions } = useComponentContext();
  return (
    <div>
      <span>
        {EmptyStateIndicator ? "empty state available" : "no override"}
      </span>
      <span>
        {MessageActions ? "custom actions registered" : "default actions"}
      </span>
    </div>
  );
};

Registering Overrides With WithComponents

WithComponents merges the nearest override set into the existing ComponentContext. Inner wrappers win over outer wrappers.

import {
  Channel,
  ChannelHeader,
  MessageComposer,
  MessageList,
  Thread,
  Window,
  WithComponents,
} from "stream-chat-react";

export const App = () => {
  return (
    <WithComponents
      overrides={{
        MessageComposerUI: CustomMessageComposer,
        Message: CustomMessage,
        MessageActions: CustomMessageActions,
      }}
    >
      <Channel>
        <Window>
          <ChannelHeader />
          <MessageList />
          <MessageComposer />
        </Window>
        <Thread />
      </Channel>
    </WithComponents>
  );
};

You can scope overrides more narrowly too:

import {
  Channel,
  MessageComposer,
  MessageList,
  Thread,
  Window,
  WithComponents,
} from "stream-chat-react";

export const App = () => {
  return (
    <WithComponents overrides={{ MessageComposerUI: MainChannelInput }}>
      <Channel>
        <Window>
          <MessageList />
          <MessageComposer />
        </Window>
        <WithComponents overrides={{ MessageComposerUI: ThreadInputOverride }}>
          <Thread />
        </WithComponents>
      </Channel>
    </WithComponents>
  );
};

Message and VirtualMessage overrides should read SDK state from hooks like useMessageContext() instead of assuming the SDK injects message UI props directly.

Current Override Keys

The current ComponentContext value includes the following keys.

Composer And Input

Message, Notifications, And Lists

Reactions, Polls, And Media

Channel Preview, Thread, Search, And Shared Utility UI

Choosing Between Props And Context

Use the local component prop when that component still exposes a supported prop surface. Use WithComponents and ComponentContext when you want to replace SDK-owned UI deeper in the tree.

Examples:

• wrap a single MessageComposer or Thread subtree in WithComponents when only that composer should use a different MessageComposerUI
• use <WithComponents overrides={{ MessageComposerUI: CustomInput }}> when you want every nested SDK input to use the same override
• use <WithComponents overrides={{ MessageActions: CustomMessageActions }}> when you want to replace the default message action UI
• use <WithComponents overrides={{ ContextMenu: CustomContextMenu }}> when you need to change anchored menu behavior such as outside-click dismissal or close animations without rebuilding the whole surface