Channel

Channel is the main entry point for customization and hosts most of the contexts and logic used by the React Native SDK. MessageList, MessageInput, and Thread require it.

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 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,
  MessageInput,
  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 />
          <MessageInput />
        </Channel>
      </Chat>
    </OverlayProvider>
  );
};

Context Providers

Channel provides ChannelContext, KeyboardContext, MessageInputContext, MessagesContext, PaginatedMessageListContext, AttachmentPickerContext, MessageComposerContext, ThreadContext, and TypingContext via their hooks.

UI Customizations

Channel is the entry point for most UI customization. Replace components via props and they will be used throughout the SDK where applicable.

Customizing the message avatar can be done easily by providing a custom component to the appropriate prop.

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

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

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

<Channel MessageAvatar={CustomAvatar} />;

MessagesAttachments

Props

channel

keyboardVerticalOffset

Distance from the top of the screen to the top of the Channel component (often your header height).

additionalKeyboardAvoidingViewProps

Extra props passed to KeyboardAvoidingView.

additionalTextInputProps

additionalPressableProps

allowConcurrentAudioPlayback

Allow multiple audio players to play at once.

allowSendBeforeAttachmentsUpload

When enabled, the user can send a message before all attachments have finished uploading. Defaults to the value of enableOfflineSupport from the Chat component.

allowThreadMessagesInChannel

Show the Show thread message in channel button in thread MessageInput.

asyncMessagesLockDistance

Pixels the user must drag upward to lock recording and lift their finger without stopping it.

asyncMessagesMinimumPressDuration

Minimum press duration (ms) on the record button to start voice recording.

asyncMessagesMultiSendEnabled

When enabled, recordings don't send immediately. They stack in the composer so users can send multiple voice recordings in one message.

asyncMessagesSlideToCancelDistance

Pixels the user must drag toward the leading side to cancel voice recording.

audioRecordingEnabled

Enable or disable audio recording.

attachmentPickerBottomSheetHeight

Height of the attachment picker bottom sheet when open.

attachmentSelectionBarHeight

Height of the attachment selection bar in the attachment picker.

bottomInset

Height of items located below the MessageInput when present. This inset determines the underlying shift to the MessageList when it is opened.

compressImageQuality

Image compression quality before upload.

createPollOptionGap

Gap between options in the poll creation dialog.

customMessageSwipeAction

Custom action executed when the user swipes a message.

deletedMessagesVisibilityType

Controls visibility of deleted messages in the channel.

• always: Visible to both sender and receiver.
• never: Visible to no one.
• sender: Visible only to the sender.
• receiver: Visible only to the receiver.

disableAttachmentPicker

When true, the attachment picker is hidden. Defaults to true when the image media library is not available.

disableKeyboardCompatibleView

Enable or disable the underlying KeyboardAvoidingView.

disableTypingIndicator

Disable the typing indicator in MessageList.

dismissKeyboardOnMessageTouch

Dismiss the keyboard when the user touches a message in the list.

doFileUploadRequest

Override the file upload request when a user selects a file. Must return a Promise.

This matches the definition of UploadRequestFn from the stream-chat package.

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

doMarkReadRequest

Override the mark read request.

Example

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

doSendMessageRequest

Override the send message request. This function must return a Promise equivalent to client.sendMessage.

Example

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

preSendMessageRequest

A method invoked just after the first optimistic update of a new message, but before any other HTTP requests happen. Can be used to do extra work (such as creating a channel, or editing a message) before the local message is sent.

doUpdateMessageRequest

Override the update message request. This function must return a Promise equivalent to client.updateMessage.

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

enableMessageGroupingByUser

If false, consecutive messages from the same user won't be grouped.

enableSwipeToReply

If true, users can swipe to reply to a message.

enforceUniqueReaction

Limits reactions to one per user. Selecting a new reaction replaces the previous one (similar to iMessage).

forceAlignMessages

Forces all messages to align left or right. By default, received messages are left and sent messages are right.

getMessageGroupStyle

Messages are grouped so UI elements like avatars only appear for the last message in a group. Messages are grouped when the same user sends them within a time window (controlled by maxTimeBetweenGroupedMessages on Channel). Use getMessageGroupStyle to override group position logic (top, bottom, middle, single), which affects UI like timestamps and avatars.

Default logic lives in getGroupStyles. Access the computed styles via MessageContext.groupStyles in custom components.

giphyVersion

Giphy image version to render. See the Image Object keys for options.

handleAttachButtonPress

Customize behavior when the AttachButton is pressed in the message input.

handleBan

Called when the Ban User action is triggered. It does not override default behavior. See customize message actions.

handleBlockUser

Called when the Block User action is triggered. It does not override default behavior. See customize message actions.

handleCopy

Called when the Copy Message action is triggered. It does not override default behavior. See customize message actions.

handleDelete

Called when the Delete Message action is triggered. It does not override default behavior. See customize message actions.

handleDeleteForMe

Called when the Delete Message for me action is triggered. It does not override default behavior. See customize message actions.

handleEdit

Called when the Edit Message action is triggered. It does not override default behavior. See customize message actions.

handleFlag

Called when the Flag Message action is triggered. It does not override default behavior. See customize message actions.

handleMarkUnread

Called when the Mark Unread action is triggered. It does not override default behavior. See customize message actions.

handleMute

Called when the Mute User action is triggered from the message actions list. It does not override default behavior. See customize message actions.

handlePinMessage

Called when the Pin to Conversation or Unpin from Conversation action is triggered. It does not override default behavior. See customize message actions.

handleReaction

Called when a reaction is selected in the message menu (add or remove). It does not override default behavior. See customize message actions.

handleQuotedReply

Called when the Reply action is triggered. It does not override default behavior. See customize message actions.

handleRetry

Called when the Retry action is triggered. It does not override default behavior. See customize message actions.

handleThreadReply

Called when the Thread Reply action is triggered. It does not override default behavior. See customize message actions.

hasCameraPicker

Enable the camera picker in MessageInput.

hasCommands

Enable commands in MessageInput.

hasFilePicker

Enable the file picker in MessageInput.

hasImagePicker

Enable the image picker in MessageInput.

hideDateSeparators

Hide inline date separators in MessageList.

hideStickyDateHeader

Hide the sticky date header in MessageList.

initialScrollToFirstUnreadMessage

Load the channel starting at the first unread message.

initializeOnMount

Controls whether Channel should run channel.watch() whenever it mounts a new channel. When set to false, it is the integrator's responsibility to run channel.watch() to receive WebSocket events for that channel.

Useful when viewing channels in a read-only mode or for ephemeral channels that should not be created until the first message is sent.

isAttachmentEqual

Returns true if rendering nextAttachment would produce the same result as prevAttachment, otherwise false.

isMessageAIGenerated

A function that determines whether a message was AI-generated. Used to enable streaming message rendering via StreamingMessageView.

keyboardBehavior

Behavior for the keyboard passed to the underlying KeyboardAvoidingView.

loadingMore

Override the loadingMore value supplied by the channel query logic.

loadingMoreRecent

Override the loadingMoreRecent value supplied by the channel query logic.

markdownRules

Rules for simple-markdown.

markReadOnMount

Enable/disable marking the channel as read when Channel mounts.

maxTimeBetweenGroupedMessages

Maximum time (ms) between consecutive messages from the same user to keep them grouped.

messageId

Load the channel at a specified message instead of the most recent message.

messageActions

An array of actions, or a function returning an array, shown in the message menu. See customize message actions.

messageContentOrder

Order for rendering message content.

messageInputFloating

When true, renders the message input in a floating style.

messageSwipeToReplyHitSlop

Defines the hitSlop area for the message swipe-to-reply gesture.

messageTextNumberOfLines

Number of lines for message text in the Message Overlay.

myMessageTheme

newMessageStateUpdateThrottleInterval

Throttle interval (ms) for channel state updates when new messages arrive. Default is 500 ms. For high concurrency, increase (for example 1000 ms) to reduce JS thread load.

numberOfAttachmentImagesToLoadPerCall

Number of images loaded per CameraRoll.getPhotos call.

numberOfAttachmentPickerImageColumns

Number of columns in the image picker.

onAlsoSentToChannelHeaderPress

Called when the "Also sent to channel" header is pressed in a thread message.

onLongPressMessage

Called when a user long-presses a message. The default opens the message menu.

onPressMessage

Called when a user presses a message.

additionalInfo provides extra data for certain emitters (for example, user details for textMention).

For example:

<Channel
      onPressMessage={({ additionalInfo, defaultHandler, emitter }) => {

          if (emitter === 'textMention') {
            console.log(additionalInfo?.user);
            return;
          }

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

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

          defaultHandler?.();
      }}
    >

onPressInMessage

Called on touch start, before onPressMessage.

overrideOwnCapabilities

Override the current user's capabilities (normally derived from permissions, channel type, and channel settings). These capabilities enable or disable UI features. See:

/chat/docs/javascript/chat_permission_policies/

Example:

<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 MessageInput.

reactionListPosition

Position of the reaction list in the message component. Default is above the message content.

reactionListType

Type of reaction list to render. Controls the visual style of the reaction list.

selectReaction

Full override of the message reaction handler. It must return a function that accepts reactionType (string). See customize message actions.

setInputRef

Callback function to set the ref on the underlying TextInput in MessageInput.

shouldShowUnreadUnderlay

Enable/disable the unread underlay background in the message list.

stateUpdateThrottleInterval

Throttle interval (ms) for channel state updates (excluding new messages). Default is 500 ms. For high concurrency, increase (for example 1000 ms) to reduce JS thread load.

supportedReactions

thread

threadList

Indicates the Channel is rendering a thread. Used to avoid concurrency issues between the main channel and thread.

openPollCreationDialog

Called when the poll creation button is clicked in the attachment picker. Use it to override the default modal UI.

If overridden, a payload is passed with sendMessage from MessageInputContext for use in CreatePoll.

hasCreatePoll

Controls whether the poll creation button is visible.

topInset

Distance from the top of the screen the attachment picker should open to when expanded. This is often set to the header height.

urlPreviewType

Controls the type of URL preview shown for messages with links.

maximumMessageLimit

A prop that limits how many messages are kept in memory.

Useful for high-traffic channels (for example, a livestream) where retaining every message in memory is unnecessary.

Behavior notes:

• It affects how the underlying MessageList works
• When the limit is exceeded, the oldest messages are pruned (in memory only)
• Messages are not pruned if you are near the top of the MessageList
• Pagination still works for messages removed from memory

UI Components Props

AttachButton

Renders the attach button next to the input box.

Attachment

Renders attachments in MessageList.

Available props:

• attachment {object}

AudioAttachment

Renders the audio attachment.

AudioAttachmentUploadPreview

Customize the audio attachment upload preview in MessageInput.

AudioRecorder

Custom UI for audio recorder controls in MessageInput.

AudioRecordingInProgress

Custom UI for an in-progress audio recording in MessageInput (waveform, duration, etc.).

AudioRecordingLockIndicator

Custom lock indicator for audio recording in MessageInput.

AudioRecordingPreview

Custom UI to preview and play an audio recording in MessageInput.

AudioRecordingWaveform

Custom waveform UI for audio recording in MessageInput.

AutoCompleteSuggestionHeader

Renders the autocomplete suggestion header.

AutoCompleteSuggestionItem

Renders an autocomplete suggestion item.

AutoCompleteSuggestionList

Renders the autocomplete suggestion list.

AttachmentPickerContent

Renders the content of the attachment picker bottom sheet.

AttachmentPickerSelectionBar

Renders the attachment picker selection bar (image, file, camera icons).

AttachmentPickerIOSSelectMorePhotos

Renders the "select more photos" option for limited gallery access on iOS.

AttachmentUploadPreviewList

Renders previews of attached files and images in MessageInput.

CooldownTimer

Renders a countdown timer for message send cooldowns in MessageInput.

DateHeader

Renders the sticky date header in MessageList.

EmptyStateIndicator

Renders when the channel has no messages.

FileAttachmentIcon

FileAttachment

Renders file attachments in MessageList.

FileAttachmentGroup

Renders a group of file attachments when a message has multiple files.

FilePreview

Renders a preview of a file attachment.

FileAttachmentUploadPreview

Customize the file attachment upload preview in MessageInput.

FileUploadInProgressIndicator

Renders the progress indicator shown while a file is being uploaded.

FileUploadRetryIndicator

Renders the retry indicator shown when a file upload fails.

FileUploadNotSupportedIndicator

Renders an indicator when file upload is not supported.

ImageAttachmentUploadPreview

Customize the image attachment upload preview in MessageInput.

ImageUploadInProgressIndicator

Renders the progress indicator shown while an image is being uploaded.

ImageUploadRetryIndicator

Renders the retry indicator shown when an image upload fails.

ImageUploadNotSupportedIndicator

Renders an indicator when image upload is not supported.

VideoAttachmentUploadPreview

Customize the video attachment upload preview in MessageInput.

ImageOverlaySelectedComponent

Indicator shown for selected images in the image picker.

FlatList

FlatList component used by MessageList.

Gallery

Giphy

Renders Giphy attachments in MessageList.

ImageLoadingFailedIndicator

Renders when an image fails to load in Gallery.

ImageLoadingIndicator

Renders while an image is loading in Gallery.

InlineDateSeparator

Renders inline date separators between messages more than a day apart.

InlineUnreadIndicator

Renders an inline separator in MessageList to mark the last read message.

Input

Renders the UI for the enclosed MessageInput. See Customizing Message Input.

InputButtons

Renders action buttons (AttachButton) on the left side of the MessageInput.

KeyboardCompatibleView

Override the default KeyboardCompatibleView. You likely won't need this; use these props instead:

• keyboardVerticalOffset
• disableKeyboardCompatibleView

LoadingErrorIndicator

Full-screen error indicator when the channel fails to load.

LoadingIndicator

Renders a full-screen loading indicator when a channel is loading.

Message

Renders a message wrapper component in MessageList.

MessageActionList

Renders the message action list in the message menu.

MessageActionListItem

Renders a message action item within the action list.

MessageAvatar

MessageBlocked

Renders a blocked message indicator in MessageList.

MessageBounce

Renders the bounce action handler for bounced messages in MessageList.

MessageComposerLeadingView

Renders the leading (left) view in the message composer.

MessageComposerTrailingView

Renders the trailing (right) view in the message composer.

MessageContent

Renders message content (status, attachments, reactions, etc.) in MessageList.

MessageDeleted

Renders a deleted message.

MessageError

Customize the message error component.

MessageFooter

Renders the message footer in MessageList.

MessageHeader

Renders the header for a message in MessageList.

MessageInputHeaderView

Renders the header view of the message input area (for example, reply preview or editing state).

MessageInputLeadingView

Renders the leading (left) view of the message input area.

MessageInputTrailingView

Renders the trailing (right) view of the message input area.

MessageList

Renders the list of messages in the channel.

MessageLocation

Renders location attachments in messages.

MessageMenu

Legacy placeholder for the long-press context menu container.

The active runtime overlay path is composed directly from MessageReactionPicker, MessageActionList, and MessageUserReactions. Overriding MessageMenu does not affect the current long-press UI.

MessagePinnedHeader

Renders the pinned message label in MessageList.

MessageReminderHeader

Renders the reminder header for messages that have reminders set.

MessageSavedForLaterHeader

Renders the "saved for later" header for bookmarked messages.

SentToChannelHeader

Renders the "also sent to channel" header for thread messages shown in the main channel.

MessageReplies

Shows thread reply count and avatars of users who replied.

MessageRepliesAvatars

Renders avatars of users who replied in the thread.

MessageSimple

Renders a message in MessageList.

See Customizing Message UI.

MessageStatus

Renders message status (time and read receipts).

MessageSwipeContent

Renders content when the user swipes a message.

MessageSystem

Renders system messages that inform users about channel changes. System messages are part of history and have type: "system".

System messages appear when:

• A user gets added to or removed from channel
• A user accepts invite to join a channel
• Channel is updated

MessageText

Renders message text. By default, the SDK uses Simple Markdown. If you override this, you must handle markdown rendering yourself.

MessageTimestamp

Renders the timestamp for a message.

MessageReactionPicker

Reaction selector shown in the long-press overlay.

MessageUserReactionsAvatar

Renders an avatar in the user reactions sheet shown from the long-press overlay.

MessageUserReactionsItem

Customize an individual item in MessageUserReactions (avatar, reaction type, user name, etc.).

MessageUserReactions

Renders the reactions list shown from the long-press overlay.

NetworkDownIndicator

Renders an indicator at the top of the channel when the network/connection is down.

ReactionListBottom

Renders the reactions list below the message bubble.

ReactionListTop

Renders the reactions list above the message bubble.

ReactionListClustered

Renders a clustered reaction list that groups reactions together.

ReactionListItem

Renders an individual reaction item in the reaction list.

ReactionListItemWrapper

Renders a wrapper around each reaction item in the reaction list.

ReactionListCountItem

Renders the count badge for a reaction type in the reaction list.

Reply

ScrollToBottomButton

Renders a button that scrolls the message list to the bottom.

SendButton

Renders the send message button inside MessageInput.

SendMessageDisallowedIndicator

Renders an indicator when the current user can't send messages.

ShowThreadMessageInChannelButton

Renders a checkbox in Thread that sets show_in_channel to true when checked.

StartAudioRecordingButton

Custom mic button for audio recording in MessageInput.

StickyHeader

Renders the sticky date header component in MessageList.

TypingIndicator

Renders the typing indicator in MessageList.

TypingIndicatorContainer

Renders the container for the typing indicator in MessageList.

UnreadMessagesNotification

Renders the floating unread indicator when the first unread message is off-screen.

UnsupportedAttachment

Renders a fallback for attachment types that are not natively supported by the SDK.

UrlPreview

Renders URL previews in MessageList.

URLPreviewCompact

Renders compact URL previews in MessageList when urlPreviewType is set to 'compact'.

VideoThumbnail

Renders video thumbnails for video attachments in MessageList.

CreatePollContent

PollContent

A Component prop used to render the content of the Poll component in MessageList.

The component has full access to the entire Poll reactive state through the usePollState hook.

Props

PollHeader

A Component prop used to render the header of the PollContent component.

PollButtons

A Component prop used to render the buttons of the PollContent component.

StreamingMessageView

Custom UI for an AI-generated message.

StopMessageStreamingButton

Custom button to stop AI generation, shown instead of SendButton in MessageInput.