Channel

Channel is the main entry point for customization and hosts most of the contexts and logic used by the React Native SDK. MessageList, MessageComposer, and Thread require it. It provides the following contexts to its children:

• ChannelContext (via useChannelContext) - channel state and configuration
• KeyboardContext (via useKeyboardContext) - keyboard handling state
• MessageInputContext (via useMessageInputContext) - message input state and actions
• MessagesContext (via useMessagesContext) - message rendering configuration
• PaginatedMessageListContext (via usePaginatedMessageListContext) - message pagination state
• AttachmentPickerContext (via useAttachmentPickerContext) - attachment picker state
• MessageComposerContext (via useMessageComposerAPIContext) - message composer API
• ThreadContext (via useThreadContext) - thread state
• TypingContext (via useTypingContext) - typing indicator state

Best Practices

• Create and watch channels once, then reuse the instance across renders.
• Render Channel under OverlayProvider and Chat to ensure all contexts are available.
• Customize UI by replacing specific components via WithComponents instead of re-implementing core logic.
• Keep custom components lightweight to avoid performance regressions in lists.
• Use channel props for behavior changes before reaching for custom overrides.

Basic Usage

Channel takes a StreamChat channel instance. Create one via creating channels or read it from ChannelList via the onSelect callback.

import { useEffect, useState } from "react";
import { StreamChat } from "stream-chat";
import {
  Channel,
  Chat,
  MessageComposer,
  MessageList,
  OverlayProvider,
} from "stream-chat-react-native";

const client = StreamChat.getInstance("api_key");

export const App = () => {
  const [channel, setChannel] = useState();

  useEffect(() => {
    const createAndWatchChannel = async () => {
      const newChannel = client.channel("messaging", "channel_id");
      await newChannel.watch();
      setChannel(newChannel);
    };

    createAndWatchChannel();
  }, []);

  return (
    <OverlayProvider>
      <Chat client={client}>
        <Channel channel={channel}>
          <MessageList />
          <MessageComposer />
        </Channel>
      </Chat>
    </OverlayProvider>
  );
};

Registering Custom Components

Component overrides are provided via the WithComponents wrapper instead of props on Channel. Wrap Channel (or any ancestor) with <WithComponents overrides={{ ... }}> and the custom components will be used throughout the SDK where applicable.

Customizing the message author can be done by providing a custom component to the overrides prop on WithComponents.

import { Image } from "react-native";
import {
  Channel,
  MessageComposer,
  MessageList,
  WithComponents,
  useMessageContext,
} from "stream-chat-react-native";

const CustomAuthor = () => {
  const { message } = useMessageContext();

  return <Image source={{ uri: message.user?.image }} />;
};

<WithComponents overrides={{ MessageAuthor: CustomAuthor }}>
  <Channel channel={channel}>
    <MessageList />
    <MessageComposer />
  </Channel>
</WithComponents>;

WithComponents can be placed at any level of the tree. Overrides are merged with any parent WithComponents providers, so you can set global defaults at the top and refine them deeper in the tree.

MessagesAttachmentsindicatorsinput

Props

Examples

Override the file upload request

The doFileUploadRequest prop accepts a function matching the UploadRequestFn type from the stream-chat package:

export type UploadRequestFn = (
  fileLike: FileReference | FileLike,
) => Promise<MinimumUploadRequestResult>;

Send before attachment uploads finish

allowSendBeforeAttachmentsUpload controls whether the composer can create the optimistic message before selected attachments have finished uploading.

When it is false, the send button waits for the attachment manager to finish uploads. When it is true, the SDK includes pending attachments in the optimistic message, tracks each upload by its local attachment id, and renders progress in the message list while client.uploadManager finishes the upload work.

<Channel channel={channel} allowSendBeforeAttachmentsUpload>
  <MessageList />
  <MessageComposer />
</Channel>

The final message sent to Stream still contains uploaded CDN URLs. The default value follows enableOfflineSupport, because offline support depends on preserving pending attachment state in the local message.

Conditional mark-read requests

const doMarkReadRequest = (channel) => {
  if (/** Some custom logic here */) {
    channel.markRead();
  }
};

Override the send message request

const doSendMessageRequest = (channelId, messageObject) => {
  if (/** Some custom logic here */) {
    messageObject.isSpecial = true;
  }
  return channel.sendMessage(messageObject);
}

Override the update message request

const doUpdateMessageRequest = (channelId, messageObject) => {
  const numberOfUpdates = (messageObject.numberOfUpdates ?? 0) + 1;
  const messageToSend = { ...messageObject, numberOfUpdates };
  return client.updateMessage(messageToSend);
};

Custom message press handler

additionalInfo provides extra data for certain emitters. For emitter === 'textMention', it includes:

• mentionedEntity - the matched MentionEntity (from stream-chat). Switch on mentionedEntity.mentionType to handle each of the five mention variants (user, channel, here, role, user_group)
• user - kept for back-compat. Populated only when mentionType === 'user'

<Channel
  onPressMessage={({ additionalInfo, defaultHandler, emitter }) => {
    if (emitter === 'textMention') {
      const { mentionedEntity, user } = additionalInfo ?? {};
      switch (mentionedEntity?.mentionType) {
        case 'user':
          // `user` is also populated for back-compat.
          openUserProfile(user?.id ?? mentionedEntity.id);
          break;
        case 'channel':
        case 'here':
          // Broadcast mentions — usually no-op.
          break;
        case 'role':
          openRoleInfo(mentionedEntity.name);
          break;
        case 'user_group':
          openGroupInfo(mentionedEntity.id);
          break;
      }
      return;
    }

    if (emitter === 'urlPreview' || emitter === 'textLink') {
      console.log(additionalInfo?.url);
      return;
    }

    if (emitter === 'fileAttachment') {
      console.log(additionalInfo?.attachment);
      return;
    }

    defaultHandler?.();
  }}
>

Override user capabilities

<Channel
  overrideOwnCapabilities={{
    uploadFile: false,
    sendLinks: false
  }}

Available keys:

• banChannelMembers — When false, "Block User" is hidden in the message menu.
• deleteAnyMessage — When false, "Delete Message" is hidden for received messages.
• deleteOwnMessage — When false, "Delete Message" is hidden for own messages.
• flagMessage — When false, "Flag Message" is hidden.
• pinMessage — When false, "Pin Message" is hidden.
• quoteMessage — When false, "Reply" is hidden.
• readEvents — When false, read receipts aren't rendered.
• sendLinks — When false, users can't send URLs.
• sendMessage — When false, SendMessageDisallowedIndicator replaces the input.
• sendReaction — When false, the reaction selector is hidden.
• sendReply — When false, "Thread Reply" is hidden.
• sendTypingEvents — When false, typing events aren't sent.
• updateAnyMessage — When false, "Edit Message" is hidden for received messages.
• updateOwnMessage — When false, "Edit Message" is hidden for own messages.
• uploadFile — When false, AttachButton is hidden in MessageComposer.

Component Overrides

UI component overrides are no longer passed as props to Channel. Instead, use the WithComponents wrapper to provide custom components. See the Registering Custom Components section above for usage examples.