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. Disabled by default. Available since v8.9.0.

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.

attachmentPickerErrorText

Error text for AttachmentPickerError.

attachmentPickerErrorButtonText

Button text in AttachmentPickerError that opens the app’s OS settings.

attachmentPickerBottomSheetHeight

Height of the attachment picker bottom sheet when open.

attachmentSelectionBarHeight

Height of the attachment selection bar in the attachment picker.

attachmentPickerBottomSheetHandleHeight

Height of the attachment picker bottom sheet handle.

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.

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.

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);
}

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

Note: Available in SDK version >= v3.9.0.

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.

formatDate

Format function for dates in message status and deleted message components.

getMessagesGroupStyles

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

globalUnreadCountLimit

Maximum number of unread messages to show as a count on a channel before adding a +. The max allowable is 255, which when reached displays as 255+.

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.

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

Note: Available in SDK version >= v3.9.0.

Hide the sticky date header in MessageList.

initialScrollToFirstUnreadMessage

Load the channel starting at the first unread message.

isAttachmentEqual

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

keyboardBehavior

Behavior for the keyboard passed to the underlying KeyboardAvoidingView.

legacyImageViewerSwipeBehaviour

Note: Available in SDK version >= v3.9.0.

Enable/disable legacy image viewer behavior.

When true, the image viewer lets you swipe through all loaded images in the channel. This adds JS thread work to track and pre-populate images for smooth transitions.

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.

maxMessageLength

Maximum message length. The default comes from the channel config.

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.

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

Note: Available in SDK version >= v3.9.0.

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.

numberOfLines

Maximum number of lines the underlying TextInput in MessageInput can expand to.

numberOfAttachmentImagesToLoadPerCall

Number of images loaded per CameraRoll.getPhotos call.

numberOfAttachmentPickerImageColumns

Number of columns in the image picker.

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.

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

Note: Available in SDK version >= v3.9.0.

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.

closePollCreationDialog

Function called whenever the close button is pressed on the poll creation modal. Has no effect if PollCreateContent is custom.

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.

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}

AttachmentActions

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.

AttachmentPickerBottomSheetHandle

Bottom sheet handle component for the attachment picker.

AttachmentPickerSelectionBar

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

AttachmentPickerIOSSelectMorePhotos

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

AttachmentPickerError

Error component shown when the app lacks permission to access photos.

AttachmentPickerErrorImage

Image component used by AttachmentPickerError.

AttachmentUploadPreviewList

Renders previews of attached files and images in MessageInput.

AttachmentUploadProgressIndicator

Renders upload progress for images/files in the message input.

CameraSelectorIcon

Camera selector icon in the attachment selector bar.

CooldownTimer

Renders a countdown timer for message send cooldowns in MessageInput.

Card

Renders custom attachment types. See Custom Attachment.

CardCover

Renders the main body of Card attachments. See Custom Attachment.

CardFooter

Renders the footer for Card attachments. See Custom Attachment.

CardHeader

Renders the header for Card attachments. See Custom Attachment.

CommandsButton

Renders the button next to the input box that opens the commands list.

CommandInput

Renders the message input in an active command state.

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.

FileSelectorIcon

File selector icon in the attachment selector bar.

ImageSelectorIcon

Image selector icon in the attachment selector bar.

VideoRecorderSelectorIcon

Video recorder selector icon in the attachment selector bar.

FileAttachmentUploadPreview

Customize the file attachment upload preview in MessageInput.

ImageAttachmentUploadPreview

Customize the image attachment upload preview in MessageInput.

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 (CommandsButton and AttachButton) on the left side of the MessageInput.

InputEditingStateHeader

Renders the header when editing a message in the input.

InputReplyStateHeader

Renders the reply header in the message input.

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.

MessageActionList

Renders the message action list in the message menu.

MessageActionListItem

Renders a message action item within the action list.

MessageAvatar

MessageBounce

Renders the bounce action handler for bounced messages in MessageList.

MessageContent

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

MessageDeleted

Renders a deleted message.

MessageEditedTimestamp

Renders the “edited” label in MessageList. Only shown for other users’ messages.

MessageError

Customize the message error component.

MessageFooter

Renders the message footer in MessageList.

MessageHeader

Renders the header for a message in MessageList.

MessageMenu

Customize the message menu used for actions and reactions.

MessagePinnedHeader

Renders the pinned message label in MessageList.

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.

MessageReactionPicker

Reaction selector shown in the message menu on long-press.

MessageUserReactionsAvatar

Renders an avatar in message user reactions within the message menu.

MessageUserReactionsItem

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

MessageUserReactions

Renders the reactions list in the message menu.

MoreOptionsButton

Renders the MessageInput “more options” button (for AttachButton, CommandsButton, etc.).

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.

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.

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.

UrlPreview

Renders URL previews 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.